Menu
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Apply the architecture-knowledge-toolkit baseline for architecture documentation, traceability, metadata, quality scenarios, risks, ADRs, and adapter boundaries. Use before architecture-sensitive work or when creating derived agent adapters from canonical skills.
Enforce Living Documentation through Behaviour-Driven Development by writing a language-agnostic Gherkin feature specification for any new or changed observable behaviour and mapping each scenario to at least one automated verification, even when the target language has no native BDD framework. This is the strict default for features, behavioural enhancements, and behaviour-changing bug fixes; relax it only with an explicit recorded human waiver. Use when Codex is asked to specify feature or behaviour, write or update .feature files, add BDD or acceptance tests, keep behaviour specs and tests in sync, bridge Gherkin scenarios to classic tests, or apply a scenario-to-test naming convention with Given/When/Then structure.
Analyze and document architecture impact for feature requests, Epic issues, UserStory issues, refactoring tasks, issue implementation, and review tasks. Use when Codex is asked to handle a feature request, decide whether feature work should become an Epic or UserStory, create or refine an Epic, mark a UserStory or refactoring issue, implement feature or refactoring work, review a pull request or review task, assess whether code changes affect architecture documentation, update affected arc42 sections, connect features or refactorings to ADRs, quality goals, quality scenarios, risks, components, runtime scenarios, deployment views, or create follow-up ADRs with diagrams.
Implement GitHub issue work using the repository workflow: start from the latest main branch, create an issue_<number> branch, make focused changes, verify, commit using the commit-message skill, push, and open a pull request. Use when Codex is asked to implement or fix a GitHub issue, continue issue work, prepare a PR for issue work, or address pull request review comments.
Create proposed Architecture Decision Records and analyze their impact on related architecture artifacts. Use when Codex needs to draft or update ADRs, inspect existing architecture documentation and source code, compare options with a Pugh matrix, identify affected risks and quality scenarios, propose traceability metadata relations, update impacted artifacts only when justified, or produce an ADR impact report.
Create proposed quality scenarios and analyze their traceability to quality objectives, ADRs, risks, requirements, architecture artifacts, and code evidence. Use when Codex needs to draft or update measurable quality scenarios, inspect existing arc42 Chapter 10 quality requirements, derive scenarios from source evidence without inventing targets, propose metadata relations, or produce a quality scenario impact report.
| name | grill-with-docs |
| description | A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. |
| disable-model-invocation | true |
| metadata | {"Author":"Matt Pocock","source":"https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md"} |
Run a /grilling session, using the /domain-modeling skill.