| name | doc-align |
| description | Stress-test a plan against the project's CONTEXT.md glossary and docs/adr/ decisions by grilling the user one question at a time, surfacing contradictions between user claims and the actual code, and updating CONTEXT.md/ADRs lazily as terms resolve.
|
Plan Alignment Protocol
Overview
doc-align is the grilling discipline of Octopus. It treats
CONTEXT.md as the glossary of record and docs/adr/ as the ledger
of decisions, then walks the user through the decision tree of a plan
one question at a time. Drift in terminology gets recorded inline;
real architectural trade-offs get an ADR — but only if the triple
gate holds.
When to Engage
Engage when the user wants to:
- Stress-test a plan, design, or RFC against the existing domain model
- Resolve ambiguous terminology before writing code
- Discover hidden disagreements with documented decisions
Do not engage for greenfield brainstorming with no existing docs — use
superpowers:brainstorming first, then come back here.
The Triple Gate for ADRs
An ADR is proposed only when all three hold:
- Hard-to-reverse — shapes data, public APIs, or cross-module
contracts
- Surprising without context — a competent reader asks "why?"
from the code alone
- Real trade-off — alternatives were viable, and the rejection
had a recorded reason
Missing any one cancels the ADR. Most decisions fail the gate and stay
as code + commit message. Do not paper docs/adr/ with preferences.
Protocol
Step 1 — Map the domain
Read CONTEXT.md (or CONTEXT-MAP.md for multi-context repos). If
absent, offer to bootstrap a glossary stub before grilling — grilling
without a glossary surfaces drift but has nowhere to record it.
Step 2 — Walk the decision tree
Ask one question at a time. Each question targets one of: a term
not in CONTEXT.md, a term used differently from CONTEXT.md, a claim
the code might contradict, or a decision treated as obvious when the
trade-off is real. The user's answers reshape the tree — never batch.
Step 3 — Surface contradictions immediately
When the user's claim diverges from what the code actually says,
stop and surface the contradiction before the next question.
Continuing a chain on a false premise poisons the rest of the session.
Step 4 — Update CONTEXT.md lazily
CONTEXT.md is glossary only: term → one-sentence definition in the
project's voice. No implementation details, no spec content, no
scratchpad notes. Cross-references between terms are allowed; long
prose is not. Edit inline as terms resolve, never in a batch at the
end.
Step 5 — Propose an ADR only when the gate passes
Triple gate passes → draft via /octopus:doc-adr with the decision,
rejected alternatives, and the why. Gate fails → resolution lives in
the commit message or PR description.
Anti-Patterns
- More than one question per turn
- "Just to confirm…" recaps that delay the next real question
- Implementation details, prose, or open issues inside CONTEXT.md
- ADR for a preference, a style choice, or a reversible call
- Continuing the question chain after spotting a contradiction
without surfacing it
- Re-grilling territory already covered by an existing ADR — read it,
cite it, move on
Integration with Other Skills
doc-prd — synthesises the aligned plan into a tracker PRDrefactor-deepen — uses doc-align for its grilling sub-loopdoc-lifecycle — owns the ADR / Spec / RFC artifacts produced
or consultedsuperpowers:brainstorming — runs before doc-align when
the plan does not yet exist
