grill-with-docs

Run a grilling session that interviews you about every branch of the design tree, one question at a time, with a recommended answer per question. The session checks the spec against CONTEXT.md terminology and existing ADRs, surfacing contradictions before implementation begins.

Maintain a CONTEXT.md glossary that defines canonical terms and lists aliases to avoid. During design discussions, conflicts between spoken language and the glossary are flagged immediately, and resolved terms are written back into CONTEXT.md inline.

Write an ADR only when three conditions hold: the decision is hard to reverse, it is surprising without context, and it resulted from a real trade-off between alternatives. Decisions failing any of these tests are skipped to avoid documentation noise.

Yes, it reads the most recently modified file in docs/superpowers/specs/ and treats it as the design under review without re-eliciting stated requirements. It only reads those artifacts and never edits them; its writes are limited to CONTEXT.md and docs/adr/.

The review quality depends on the accuracy of CONTEXT.md and existing ADRs; undocumented decisions cannot be cross-referenced. It also verifies claims against the codebase where possible, but it does not execute or test the proposed design itself.