Subphase Convention

convention-subphase Convention

active convention

Project

Subphase Convention

How to handle tangent work that emerges during a phase — QA nits, discovered prerequisites, rabbit holes, and scope creep that deserves its own tracking.

The Rule

If it needs its own issue, it needs its own phase note. Tangent work that can be handled within the current issue stays in the current phase. Tangent work that needs a separate Forgejo issue becomes a subphase.

When to Create a Subphase

Trigger	Example	Action
QA nit that needs its own PR	8d-1: sentinel pattern asymmetry found during QA of 8d	Create subphase under parent phase
Discovered prerequisite	4a: barman plugin migration discovered during backup verification	Create subphase under parent phase
Rabbit hole with independent value	8c-1: claude-custom write protection discovered during SDK blocks work	Create subphase under parent phase
Scope creep worth doing now	A small fix that would be silly to defer to a whole new plan	Create subphase under parent phase

When NOT to Create a Subphase

In-scope fix: A bug found and fixed within the same PR — just fix it
Future work: Something identified but not needed now — create a TODO note instead
Different plan entirely: Work that belongs to a different project/plan — create an issue on the right repo

How to Create a Subphase

Create the phase note using template-phase (subphase variant: Problem + Fix instead of Scope)
Create a Forgejo issue on the target repo using template-issue
Spawn the agent with the standard ~100 token prompt
After merge, update the subphase status and fill Deliverables

Recursive Nesting (parent_slug)

The parent_slug field creates a tree, not a flat list:

Query patterns:

list_notes(parent_slug="plan-slug") → top-level phases only
list_notes(parent_slug="phase-slug") → direct subphases of that phase
Full tree traversal: recursive list_notes(parent_slug=...) calls

Naming Convention

Level	Slug Pattern	Example
Top-level phase	<code>phase-{context}-{n}-{desc}</code>	<code>phase-postgres-8-mcp-optimization</code>
Subphase (lettered)	<code>phase-{context}-{n}{letter}-{desc}</code>	<code>phase-postgres-8d-sdk-sprints</code>
Sub-subphase (numbered)	<code>phase-{context}-{n}{letter}{num}-{desc}</code>	<code>phase-postgres-8d1-sprint-sentinel</code>

The pattern can nest further if needed, but three levels should cover most cases. If you're going deeper than three, consider whether the work belongs in a separate plan.

Traceability Chain

Every subphase traces back to a purpose:

The Forgejo issue's ### Lineage section captures this chain in human-readable form. The parent_slug field captures it in queryable form.

template-phase — the structure every phase/subphase note follows
template-plan — plans define top-level phases; subphases emerge during execution
template-issue — Forgejo issues reference the lineage chain
agent-spawn-conventions — "no plan, no agent" still holds; subphases ARE phases
plan-2026-03-07-note-hierarchy-conventions — the plan that created this convention

Subphase Convention