Requirements clarification and review engineering workflow

mattpocock/skills is a set of engineering workflows for AI agents that takes a feature from requirements clarification to release. It covers PRDs, issue breakdown, TDD implementation, review, diagnose and architecture cleanup; it is not provided as a single prompt. The repo describes its approach as real engineering, distinct from vibe coding, with small, composable and modifiable agent skills.

Each skill corresponds to an engineering action and provides instructions for that action:

• /grill-with-docs challenges requirements and aligns domain language.

• /to-prd combines conversation context and codebase understanding into a PRD.

• /to-issues splits a PRD into independently implementable vertical slices.

• /tdd implements through red-green-refactor.

• /review checks a diff along the Standards and Spec axes.

Skills connect through the repo's issue tracker and domain docs; setup configures these locations first.

Skill design follows clarification, planning, implementation and review in order. The official README also says agents accelerate software entropy, so use /zoom-out and /improve-codebase-architecture periodically to examine system design.

The official quickstart installs with one npx command. Choose your coding agent and select /setup-matt-pocock-skills.

After installation, run the setup skill once in your coding agent. It configures the repo's issue tracker, triage labels and domain docs locations for /to-prd, /to-issues, /tdd, /diagnose and other skills.

Initial setup rules

Specify the issue tracker, triage labels and domain doc layout together during setup, giving later skills fixed read/write locations.

The official reference lists 10 engineering skills:

• diagnose

• grill-with-docs

• triage

• improve-codebase-architecture

• setup-matt-pocock-skills

• tdd

• to-issues

• to-prd

• zoom-out

• prototype

The cards also include /review and /handoff, which are commonly used in workflows, grouped by work stage. The five core skills grill-with-docs, to-prd, to-issues, tdd and review can complete a workflow cycle.

Scenarios and skills

A. New feature planning

Set up repo rules, then use grill-with-docs to clarify requirements and write them to CONTEXT.md / ADR. Use to-prd to create a PRD and to-issues to split thin vertical slices. Implement each issue with tdd, then compare against the main branch with review main.

B. Bug fixes

Use diagnose to establish a reproducible feedback loop, then tdd to add a regression test and fix the bug. Finish with review main to check existing behavior.

Diagnosis sequence: feedback loop → reproduce → minimise → hypothesise → instrument → fix → regression-test. Establish an automatically runnable pass/fail signal before fixing, to avoid guessing at the bug.

C. Architecture cleanup

For codebases disorganized by rapid agent coding, start with zoom-out for a system overview, then use improve-codebase-architecture to identify shallow interfaces and exposed complexity. Verify changes with tdd and finish with review main. The official README says agents accelerate software entropy, requiring periodic attention to system design.

Paste the templates for each stage and replace the bracketed content. /grill-with-docs asks the agent to pose one question at a time, recommend an answer for each and inspect the codebase when needed; the agent reads code for answers available in the codebase.

/to-prd combines current conversation context and codebase understanding into a PRD without interviewing the user again. The PRD covers:

• problem

• solution

• user stories

• implementation decisions

• testing decisions

• out of scope

/tdd tests observable behavior through public interfaces, not implementation details. It uses a vertical red-green loop, completing one test and its implementation at a time instead of writing all tests before implementation.

/review compares the diff against a fixed point along the Standards and Spec axes, using issue references, PRD/spec, repo coding standards, CONTEXT, ADR and config as evidence.

This email/password login example starts with /grill-with-docs, uses /to-prd and /to-issues for planning and breakdown, implements the first issue with /tdd, and finishes with /review main.

Workflow verification

• grill-with-docs reads src/auth/* before asking questions, finding answers already available in the codebase.

• to-issues splits login into independently demoable vertical slices, marked AFK and HITL.

• tdd implements one behavior at a time and does not implement #124 error handling in advance.

• review uses the Spec axis to confirm no out-of-scope OAuth functionality was added.

Minimum viable configuration

These 6 skills complete an engineering workflow cycle. Add /diagnose for repos needing more debugging; add /zoom-out, /improve-codebase-architecture and /handoff for large codebases.