pal-e-docs

Phase Template

template-phase Template

template deprecated
Project

Phase Template

DEPRECATED (2026-03-26) — Phase notes are replaced by kanban board items backed by Forgejo issues per convention-kanban-over-plans. Existing phase notes are preserved as historical artifacts. Do not create new phase notes. See template-ticket and sop-board-workflow for the current model.

When to Use a Phase Note

Not all work needs a phase note. Phases are for foundational, architectural work that shapes the project's capabilities. Improvements, bug fixes, and features on mature projects can go straight to a Forgejo issue on the board — see convention-todo-lifecycle for the two graduation paths.
Create a phase note when: the work would change an architecture diagram, has cross-repo dependencies, creates a new project capability, or needs explicit scoping (Goal, Scope, Depends on, Deliverables). Skip the phase note when: the full spec fits in a Forgejo issue with acceptance criteria, the work improves/fixes an existing capability, and the architecture doesn't change.

Design Principle: Two Shapes

Phases come in two natural shapes:
Shape When Required Sections Optional Sections
<strong>Full phase</strong> Planned work from a plan's phase table Goal, Owner, Repo, Depends on, Scope, Deliverables, Related Why, tables/mappings, Implementation Notes
<strong>Subphase (tangent)</strong> Discovered during another phase — QA nit, rabbit hole, prerequisite Goal, Owner, Repo, Depends on, Problem, Fix, Related Why (if not obvious from Problem)
Both shapes share a common spine. The hook enforces the spine; the optional sections add depth where needed.

Template (Required Sections)

Subphase Variant

When a tangent is discovered during a phase, replace Scope with Problem + Fix:

Metadata Conventions

Field Convention
<code>note_type</code> Always <code>phase</code> (both phases and subphases)
<code>parent_slug</code> <strong>Recursive nesting:</strong> Top-level phases point to their plan. Subphases point to their parent phase. Sub-subphases point to their parent subphase. Never skip levels.
<code>slug</code> Top-level: <code>phase-{plan-context}-{n}-{description}</code>. Subphase: <code>phase-{plan-context}-{parent-n}{sub-id}-{description}</code>. Examples: <code>phase-postgres-8-mcp-optimization</code>, <code>phase-postgres-8d1-sprint-sentinel-consistency</code>
<code>status</code> <code>not-started</code> → <code>in-progress</code> → <code>completed</code> (or <code>deferred</code>)
<code>position</code> Execution order among siblings (1-based). Null for subphases discovered ad-hoc.

Hook Enforcement

The check-phase-template.sh hook (Phase 4 of plan-2026-03-07-note-hierarchy-conventions) validates:
  • Header fields present: Goal, Owner, Repo, Depends on
  • At least one of: Scope, or Problem + Fix
  • Related section present

Examples

  • phase-postgres-8d-sdk-sprints — full phase (Goal, Owner, Repo, Depends on, Why, tables, Implementation Notes, Deliverables, Related)
  • phase-postgres-8d1-sprint-sentinel-consistency — subphase tangent (Goal, Owner, Repo, Depends on, Problem, Fix, Related)
  • phase-postgres-8e-integration-tests — full phase (Goal, Owner, Repo, Depends on, Scope, tables, Test Infrastructure, Related)

Phase → Forgejo Issue Flow

Same as documented in template-plan:
  • Betty Sue creates phase note with this template
  • Betty Sue creates Forgejo issue on target repo using template-issue
  • Betty Sue spawns agent with ~100 token prompt pointing to issue
  • After merge, Betty Sue updates phase status and fills Deliverables
  • template-plan — parent template (phases live inside plans)
  • template-issue — the Forgejo issue created from a phase
  • convention-subphase — when and how to create subphases
  • plan-2026-03-07-note-hierarchy-conventions — the plan that created this template