grill-with-docs

To check a proposed software design against existing architectural decisions, you can pressure-test the plan by interrogating it against repository documentation. This process catches ambiguity, hidden trade-offs, and terminology drift before implementation begins.

Aligning domain terminology during codebase analysis involves resolving conflicting terms by inspecting existing files and asking focused questions. This ensures canonical terms are captured and updated directly in CONTEXT.md as decisions crystallize.

Documentation-driven design review works by asking focused questions one at a time and recommending a strong default answer for each design branch. It cross-references the codebase to resolve questions from existing files before prompting for user input.

You do not need existing ADRs to perform a documentation-aware plan review, but having them allows the process to record meaningful trade-offs directly. The review captures resolved terminology in CONTEXT.md and logs choices in ADRs as they become clear.

You can update CONTEXT.md with resolved terminology inline as design decisions are finalized during the interrogation process. This living documentation approach ensures canonical terms and key design choices are preserved for future readers.

You should use a codebase-aware grilling session when refining a feature spec and needing to align on canonical terms. It is ideal for exposing conflicts with current documentation and preserving key design choices for future readers.