Note Conventions

Note Conventions

Note Types

• board is a first-class note_type. Board notes serve two roles: project-level kanban (one per project, permanent, via template-project-page) and ticket decomposition kanban (created when a ticket exceeds the 5-minute rule, archived when parent completes, via template-board). The fractal unit of work decomposition.
• Active types (8): board, project-page, sop, convention, template, skill, agent, doc. These are the established types used for new notes.
• New types (4): review, architecture, validation, user-story. Promoted from doc catch-all because they have distinct templates, enforcement needs, and traceability requirements.
• Frozen types (2): plan, phase. Remain in the enum. Existing notes are live infrastructure (parent-child links, status tracking). Do not create new notes with these types. See Frozen Types section below.
• Removed types: todo, issue, reference, journal, incident, post, milestone, sprint. These are removed from the enum entirely. todo/issue work items belong in Forgejo. The rest were never instantiated or are covered by doc.
• convention stays separate from sop. Conventions are rules/standards ("how to name things"). SOPs are procedures ("how to do things"). Merging would obscure a real distinction.
• doc is the catch-all. Insights, lessons, research, assessments, inventories, guides, audits, roadmaps — all become note_type: doc with topic tags providing sub-classification. Architecture, review, validation, and user-story have graduated out of doc into their own types.

Frozen Types

• Existing plan/phase notes stay queryable. Parent-child links, status fields, and block content remain intact. Agents can still read them, update their status, and reference them.
• No new plans or phases. New work decomposition uses boards (kanban) and Forgejo issues. See convention-kanban-over-plans.
• Templates retained but not offered. template-plan and template-phase remain for reference but create_note_from_template should not suggest them for new work.
• Status transitions still valid. An active plan can be moved to completed or deferred. A phase can move through not-started to completed. Frozen applies to creation, not lifecycle.
• Distinct from removed types. Removed types (todo, issue, etc.) are deleted from the enum entirely. Frozen types stay in the enum because existing data depends on them.

Status Values

Note Decomposition

Schema

What stays in the parent plan

• Vision, Context, Previous Plan, Depends On, Decisions Made
• Key Files table, Verification checklist, Next Plan Seeds, Related
• Projects & Repos Touched table
• Any plan-level context that applies to all phases

What becomes a child phase note

• Phase title, goal, owner, status
• Steps (the detailed work)
• Issue slug reference
• Deliverables (added on completion)
• Phase-specific verification criteria

Rules

• Phase slug convention: phase-{plan-date}-{n}-{short-description} (unchanged)
• Phases MUST have note_type: phase and parent_note_id set
• Phases MUST belong to the same project as the parent plan
• Position determines rendering order in the browse frontend
• Old monolithic plans render as-is — decomposition is opt-in per plan
• The "promote phase to plan" pattern is retired — phases grow in place

Baseline Measurements (2026-03-02)

Slug Naming

• All lowercase, hyphens only (no underscores, no spaces)
• Descriptive over terse — pr-review-loop not prl
• Plans get date prefixes because multiple plans can share a title over time
• Project pages, templates, skills, and agents get type prefixes because they're structurally distinct
• Issues use Forgejo as the canonical tracker. Legacy issue-{repo-slug}-{description} and bug-{description} slug patterns exist in pal-e-docs but new work items should be Forgejo issues, not notes.
• SOPs and conventions use descriptive names without type prefix (historical, may add sop- prefix convention later)

Tag Taxonomy

Transition State

Tags to Keep (topic/domain)

Tags Retiring (replaced by note_type)

Tags Retiring (replaced by status)

Tags Retiring (redundant with project FK)

Tagging Rules (Transition Period)

• Until schema migration: every note MUST have at least one type tag and one lifecycle tag (matching the note_type and status values above)
• After schema migration: tags are topic/domain only. Type and lifecycle come from columns.
• Scope tags are immediately redundant — stop using them on new notes. Use the project FK instead.
• Prefer existing topic tags over creating new ones. Check list_tags() first.
• Tag intersection is the current query pattern: ?tags=sop,active finds all current SOPs. This will be replaced by ?note_type=sop&status=active after migration.

Project Assignment

• Notes about a specific project belong to that project
• Cross-cutting SOPs and conventions belong to the project that owns the concept (usually pal-e-docs or ai-agency)
• Agent profiles and skills belong to ai-agency (Claude Config project)
• Platform-wide architecture docs belong to their primary project

README Convention

Linking

• If you reference a note by slug in prose, ALSO add it as a note_link
• Project pages should link to their active plan and all relevant SOPs
• Plans should link to their previous plan and any referenced notes
• Architecture notes should link to related SOPs and reference docs

Related

• tagging-conventions — deprecated, superseded by this note
• html-style-guide — HTML authoring convention for note content
• mermaid-authoring — mermaid diagram convention
• plan-2026-02-28-knowledge-system-consolidation — the plan implementing schema changes for note_type/status
• plan-2026-02-28-schema-api-mcp — the promoted schema plan (absorbed into decomposition plan)
• plan-2026-03-01-note-decomposition — the active plan. Implements note decomposition; will add phase to note_type enum.