First, size the ask. If it has no real decision tree (one obvious change, a small diff, a criterion statable in one sentence), say so and route straight to
with that sentence as the plan; a spec for an obvious change is ceremony. The fast path still drills its sentence: state it, then test it. A sentence that cannot be stated, or that surfaces a fork or a second decision, was not obvious: run the interview. A genuine fork discovered mid-task is never guessed: stop, name it, let the user answer or switch to deep. If
fails twice on a task judged obvious, the task was lying about its size: stop and drill it properly.
Deep mode (the
skill is active): no sizing, no routing past the interview; the full session runs and the spec is always written.
Run the
skill against the plan or design under discussion.
Shape of the session:
- Explore the project context before the first question: code, docs, recent commits.
- If the ask bundles several independent pieces, say so and drill the first piece; the rest queue up.
- Before settling a direction, put 2 or 3 genuinely different approaches on the table with trade-offs, leading with a recommendation. When a fork turns on look, feel, or flow that prose can't settle, build a throwaway mockup with fake data to react to instead, and discard it once the direction is picked.
- Cut ruthlessly: anything the stated constraints don't demand leaves the design.
Domain awareness
The interview also challenges the plan against the project's existing domain model. During exploration, look for existing documentation:
- at the root (or + per-context files in a multi-context repo)
- ADRs in (and any context-scoped directories)
Create files lazily: only when you have something to write. If no
exists, create one when the first term is resolved. If no
exists, create it when the first ADR is needed.
First contact. When no
exists and the codebase is nontrivial, offer a one-time seeding pass: distill candidate terms from the code and any existing docs, then confirm each through the interview. Only confirmed terms enter the glossary; a term nobody vouched for is not written.
During the session:
- Challenge against the glossary. When the user uses a term that conflicts with the existing language in , call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"
- Sharpen fuzzy language. When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account'. Do you mean the Customer or the User? Those are different things."
- Discuss concrete scenarios. When domain relationships are being discussed, stress-test them with specific scenarios that probe edge cases and force precision about the boundaries between concepts.
- Cross-reference with code. When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?"
- Update inline. When a term is resolved, update right there; don't batch. It is a glossary and nothing else: not a spec, not a scratchpad, not a home for implementation decisions. Format: CONTEXT-FORMAT.md.
- Offer ADRs sparingly. Only offer an ADR when all three are true: hard to reverse, surprising without context, the result of a real trade-off. If any is missing, skip it. Format: ADR-FORMAT.md.
The session ends when every branch of the decision tree is resolved: state the settled design in a short summary and get explicit agreement before any implementation starts.
When the settled design is implementation work, write the spec to
in the target project using
SPEC-FORMAT.md: goal, non-goals, checkable acceptance criteria, verification commands. The spec steers the loop:
builds from it,
gates against it,
closes it out and asks whether to keep or delete the file.
The tree does not fit this session: write the draft
When the decision tree cannot resolve here (decisions await research beyond this context, or the tree is simply too large for one session), do not force a settled spec out of an unsettled design. Write the spec as a
draft instead:
,
(empty),
,
(fog),
. Each open decision carries a Mode:
- AFK: a subagent can resolve it alone. Fire one subagent per AFK decision, in parallel, in this session, each writing its findings to
docs/research/<slug>-<decision-slug>.md
- HITL: only a live exchange with the user resolves it. Never answer your own HITL question.
Writing the draft is one session's work: name the destination, sketch the frontier, write the draft, fire the AFK subagents, stop. It resolves nothing itself.
Later sessions work the draft. When a session opens a spec that still has an
section:
- Load the whole spec: the low-res view, not one decision's deep dive.
- Pick the next open decision; if the user named one, use that. Claim it before working it.
- Resolve it: AFK decisions read the findings the subagent left at
docs/research/<slug>-<decision-slug>.md
- Record the resolution in , and remove the decision from . Graduate anything now sharp from into fresh open decisions. A decision revealed to sit beyond the destination is ruled out of scope instead of resolved.
- When the last open decision closes, delete the section: the spec is settled and the loop takes over.
One decision per session, except AFK decisions already dispatched. If no fog surfaces at all (the way is clear and the journey fits one session), there is no draft; settle normally.