pal-e-docs

Plan: Note Hierarchy Conventions

plan-2026-03-07-note-hierarchy-conventions Plan

active plan
Project

Vision

Every piece of work traces to a purpose. The note hierarchy — project → plan → phase → subphase → sub-subphase — is the spine of that traceability. When a tangent emerges (a QA nit, a rabbit hole, a discovered prerequisite), it becomes a subphase under its parent, not a floating orphan. The issue template reflects this lineage. Hooks enforce the structure.

Projects & Repos Touched

Project/Repo Platform Role
AI Agency / claude-custom Forgejo Hook for phase template enforcement
pal-e-docs (notes only) Forgejo Template + convention notes created/updated. No code changes.

Context

We naturally evolved a subphase pattern during the postgres plan (Act 2). Phases like 8d-1 (sentinel fix from QA nit on 8d), 8c-1 (claude-custom write protection discovered during 8c), and 4a (barman plugin migration found during Phase 4) are all tangent work that was properly scoped instead of lost. This works, but it's tribal knowledge — nothing documents the pattern, nothing enforces the structure, and the parent_slug field is underused (everything points flat to the plan instead of nesting recursively).
What's already done:
  • template-plan — documents plan structure and phase requirements
  • template-issue — documents Forgejo issue structure with ### Plan section
  • agent-spawn-conventions — "no plan, no agent" axiom
  • check-issue-template.sh — enforces issue template sections
  • parent_slug field exists in the schema and supports arbitrary nesting
  • 9 active templates total (plan, issue, PR, project-page, agent, skill, sprint-item, bug, repo-page[deprecated])
What's missing:
  • No template-phase — phase notes are ad-hoc HTML with no standard sections
  • No subphase convention — the pattern exists but isn't documented
  • Flat parent_slug — all phases/subphases point to the plan, not their parent phase
  • Issue template doesn't reflect lineage beyond plan slug
  • No enforcement hook for phase note structure

Previous Plan

None. This is the first plan for codifying the note hierarchy. The pattern emerged organically from plan-2026-02-26-tf-modularize-postgres (Act 2).

Depends On

None. This plan is independent — it touches conventions and templates, not application code.

Decisions Made

Decision Rationale
Recursive <code>parent_slug</code> nesting Subphases point to parent phase, not the plan. Enables <code>list_notes(parent_slug=phase_slug)</code> queries. Schema already supports it.
Phase template with standard sections Consistency. Same reason we have plan and issue templates — ad-hoc structure leads to drift.
Hook enforcement for phase notes Templates without enforcement are suggestions. Hooks make them law.
<code>### Plan</code> → <code>### Lineage</code> in issue template Full ancestry chain, not just plan slug. Agents don't read it, but humans trace purpose through it.

Phases

# Phase Owner Deliverable
1 Create <code>template-phase</code> + subphase convention Betty Sue (docs) Two pal-e-docs notes: <code>template-phase</code> with standard sections (Goal, Owner, Repo, Depends on, Problem [optional], Scope/Fix, Deliverables, Related) and <code>convention-subphase</code> documenting when/how to create subphases, naming pattern, recursive <code>parent_slug</code> usage.
2 Update <code>template-issue</code> and <code>template-plan</code> Betty Sue (docs) Issue template: rename <code>### Plan</code> to <code>### Lineage</code> with full ancestry. Plan template: add subphase reference and link to <code>convention-subphase</code>. Update <code>sop-index</code>.
3 Migrate existing phases to recursive nesting Betty Sue / Dottie Update <code>parent_slug</code> for existing subphases: 8d-1→8d, 8c-1→8c, 4a→4, 7a-7f→7, 8a-8g→8. Verify with <code>list_notes(parent_slug=...)</code> queries.
4 Hook: <code>check-phase-template.sh</code> Dev agent PreToolUse hook on <code>mcp__pal-e-docs__create_note</code> when <code>note_type=phase</code>. Validates required sections in content. Repo: <code>claude-custom</code>.

Key Files

Phase File Repo Change
1 pal-e-docs notes n/a (API) Create <code>template-phase</code> and <code>convention-subphase</code>
2 pal-e-docs notes n/a (API) Update <code>template-issue</code>, <code>template-plan</code>, <code>sop-index</code>
3 pal-e-docs notes n/a (API) Update <code>parent_slug</code> on ~15 existing phase notes
4 <code>hooks/check-phase-template.sh</code> claude-custom New PreToolUse hook for phase note validation

Dependency Chain




          
  
Verification



          
  
    
      
  • [ ] get_note(slug="template-phase") returns a template with standard sections
    • 
      
  • [ ] list_notes(parent_slug="phase-postgres-8-mcp-optimization") returns 8a, 8b, 8c, 8c-1, 8d, 8d-1, 8e, etc.
    • 
      
  • [ ] list_notes(parent_slug="phase-postgres-8d-sdk-sprints") returns 8d-1
    • 
      
  • [ ] Creating a phase note without required sections is blocked by hook
    • 
      
  • [ ] Issue template ### Lineage section traces full ancestry
    • 



          
  
Next Plan Seeds



          
  
    
      
  • Compiled page architecture (Phase 7e) could leverage recursive nesting for TOC generation
    • 
      
  • Sprint board items could display lineage for context
    • 



          
  


          
  
    
      
  • template-plan — updated in Phase 2
    • 
      
  • template-issue — updated in Phase 2
    • 
      
  • agent-spawn-conventions — traceability axiom this plan codifies
    • 
      
  • sop-index — updated with new template and convention
    • 
      
  • plan-2026-02-26-tf-modularize-postgres — the plan where this pattern emerged organically
    •