Grill With Docs: Architecture Pressure Test

An architecture plan can sound clear while leaving retries, ownership, and failure states unresolved. Get an interactive challenge session that checks your assumptions against repository docs and code before you commit to the design.

What it does

• Finds conflicting meanings: Highlights terms that mean different things in your proposal, documentation, and implementation.
• Checks implementation claims: Traces relevant code to distinguish intended behavior from what actually happens.
• Challenges edge cases: Examines duplicate requests, late success, concurrent changes, and partial failures.
• Returns evidence-backed findings: Explains concerns, confidence, alternatives, and decisions that still need your input.
• Preserves agreed conclusions: Can update repository documentation when authorized.

How it works

1. Share the plan or domain question and provide access to the relevant repository.
2. Discuss focused questions supported by documentation and implementation evidence.
3. Refine the proposal as objections are tested and uncertainties become clearer.
4. Request documentation updates if you want settled conclusions recorded.

Works with

Repository source code, Markdown documentation, glossaries, architecture decision records, tests, and operational notes. It follows the repository's existing documentation conventions.

Why use this skill

Catch disagreements about behavior before they become implementation work. Evidence checks help separate real design gaps from concerns that existing code or documentation already answers.

Use cases

• Clarify cancellation rules across orders and items.
• Challenge retry behavior before changing a workflow.
• Resolve disagreements between architecture docs and code.

Known limitations

Needs relevant repository evidence. Designed for iterative discussion, not routine bug fixes or a one-shot architecture review.