---
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:

1. **Hard-to-reverse** — shapes data, public APIs, or cross-module
   contracts
2. **Surprising without context** — a competent reader asks "why?"
   from the code alone
3. **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 PRD
- **`refactor-deepen`** — uses `doc-align` for its grilling sub-loop
- **`doc-lifecycle`** — owns the ADR / Spec / RFC artifacts produced
  or consulted
- **`superpowers:brainstorming`** — runs *before* `doc-align` when
  the plan does not yet exist