grill-with-docs

To stress-test a design plan, interrogate it against the existing codebase and documented domain language to resolve ambiguous design decisions. This process cross-references source code and docs to validate trade-offs before committing changes.

Domain language alignment detects terminology conflicting with current domain vocabulary and pushes for precise canonical terms. It ensures software documentation and glossaries remain consistent with actual codebase behavior.

Validate design trade-offs by cross-checking stated behavior against the repository to surface contradictions immediately. Resolved terms are recorded in CONTEXT.md, and ADRs are created when decisions are hard to reverse, surprising, and trade-off driven.

You need to create an Architecture Decision Record when a design decision is hard to reverse, surprising, and trade-off driven. This ensures critical design choices are documented only when they carry significant architectural impact.

Resolve ambiguous design decisions by walking through each design branch with one-question-at-a-time discovery until unresolved parts are clear. This interrogation process updates relevant documentation inline as decisions are finalized.

Plan interrogation works effectively for software projects with existing documentation and glossaries by cross-referencing source code and docs. It aligns terminology, validates trade-offs, and updates CONTEXT.md inline during the grilling process.