diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index 02f95bb..592412f 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -57,7 +57,7 @@ Optional. A short, checkable list of the observable signals that tell the reader Always present. Situate the skill in the system in a sentence or two: -- **Role.** Name it: a **chain step** (`grill-with-docs → to-prd → to-issues → tdd`), a **run-once setup** (`setup-matt-pocock-skills`), **periodic maintenance** (`improve-codebase-architecture`, "every few days"), or a **reach-for-it-anytime standalone** (`diagnosing-bugs`, `prototype`, `handoff`). A standalone's map is one honest sentence — far better than omitting the section. +- **Role.** Name it: a **chain step** (`grill-with-docs → to-prd → to-issues → implement → code-review`), a **run-once setup** (`setup-matt-pocock-skills`), **periodic maintenance** (`improve-codebase-architecture`, "every few days"), or a **reach-for-it-anytime standalone** (`diagnosing-bugs`, `prototype`, `handoff`). A standalone's map is one honest sentence — far better than omitting the section. - **Neighbours.** The one or two siblings that matter, each with a because-clause, linked absolutely. - **The map.** Point to [ask-matt](https://aihero.dev/skills-ask-matt), the router over the whole set, so this page stays a node and never has to redraw the graph. diff --git a/docs/engineering/ask-matt.md b/docs/engineering/ask-matt.md index 6fc9cf0..88c9c1d 100644 --- a/docs/engineering/ask-matt.md +++ b/docs/engineering/ask-matt.md @@ -24,7 +24,7 @@ Reach for it whenever you're unsure which skill or flow a situation calls for: y ## Flows, not just skills -The idea `ask-matt` gives you to think with is the **flow** — a path *through* the skills rather than a single one. Most work runs along one **main flow** (idea → ship: grill → PRD → issues → implement), two **on-ramps** merge onto it (a triage lane for incoming bugs and requests; a codebase-health lane that generates ideas), and everything else is a **standalone** you reach for on its own. Ask a question and you get placed on the right flow, at the right step — not just handed a tool. +The idea `ask-matt` gives you to think with is the **flow** — a path *through* the skills rather than a single one. Most work runs along one **main flow** (idea → ship: grill → PRD → issues → implement → review), two **on-ramps** merge onto it (a triage lane for incoming bugs and requests; a codebase-health lane that generates ideas), and everything else is a **standalone** you reach for on its own. Ask a question and you get placed on the right flow, at the right step — not just handed a tool. ## Where it fits diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index 0d4e7a6..e9cd220 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -44,7 +44,7 @@ What makes this variant its own skill is where the answers go. As the grill runs `grill-with-docs` is the opening step of the main build chain: ```txt -grill-with-docs → to-prd → to-issues → implement +grill-with-docs → to-prd → to-issues → implement → code-review ``` It comes first, before anything is written down as a spec: it produces the shared understanding and settled vocabulary that [to-prd](https://aihero.dev/skills-to-prd) then synthesises into a PRD without re-interviewing you. Its close neighbours are [grilling](https://aihero.dev/skills-grilling), the same interview without the docs, and [domain-modeling](https://aihero.dev/skills-domain-modeling), the glossary-and-ADR discipline it drives. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/implement.md b/docs/engineering/implement.md index 38707df..7e44167 100644 --- a/docs/engineering/implement.md +++ b/docs/engineering/implement.md @@ -30,10 +30,10 @@ Around that core it keeps the loop tight — typecheck often, run single test fi ## Where it fits -`implement` is the build step at the end of the main chain: +`implement` is the build step near the end of the main chain, just before the review: ```txt -grill-with-docs → to-prd → to-issues → implement +grill-with-docs → to-prd → to-issues → implement → code-review ``` -Reach for it after the work has been specced and sequenced, not before. Its key neighbours are [to-issues](https://aihero.dev/skills-to-issues), which produces the independently-grabbable tickets it works through, and [tdd](https://aihero.dev/skills-tdd), which it drives internally to write the tests at each seam before running its own `/code-review` pass and committing. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +Reach for it after the work has been specced and sequenced, not before. Its key neighbours are [to-issues](https://aihero.dev/skills-to-issues), which produces the independently-grabbable tickets it works through, and [tdd](https://aihero.dev/skills-tdd), which it drives internally to write the tests at each seam before running its own [code-review](https://aihero.dev/skills-code-review) pass and committing. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/tdd.md b/docs/engineering/tdd.md index 9657c4a..a0fe809 100644 --- a/docs/engineering/tdd.md +++ b/docs/engineering/tdd.md @@ -41,7 +41,7 @@ Refactoring only happens once the suite is green; never while red. `tdd` is the red-green loop the main build chain runs to write code: ```txt -grill-with-docs → to-prd → to-issues → implement +grill-with-docs → to-prd → to-issues → implement → code-review ``` -[implement](https://aihero.dev/skills-implement) is the chain's final step, and it drives `tdd` internally to build each ticket test-first — so `tdd` is the engine inside that step rather than a step of its own. You can also reach for it directly, whenever there's a concrete behaviour to build without a full spec. Its other neighbour is [codebase-design](https://aihero.dev/skills-codebase-design), which it leans on to find deep-module seams worth testing at. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +[implement](https://aihero.dev/skills-implement) is the chain's build step, and it drives `tdd` internally to build each ticket test-first before handing off to [code-review](https://aihero.dev/skills-code-review) — so `tdd` is the engine inside that step rather than a step of its own. You can also reach for it directly, whenever there's a concrete behaviour to build without a full spec. Its other neighbour is [codebase-design](https://aihero.dev/skills-codebase-design), which it leans on to find deep-module seams worth testing at. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/to-issues.md b/docs/engineering/to-issues.md index 6bec242..4f81518 100644 --- a/docs/engineering/to-issues.md +++ b/docs/engineering/to-issues.md @@ -37,7 +37,7 @@ Before slicing, `to-issues` looks for prefactoring — "make the change easy, th `to-issues` is a step in the main build chain: ```txt -grill-with-docs → to-prd → to-issues → implement +grill-with-docs → to-prd → to-issues → implement → code-review ``` -It sits between [to-prd](https://aihero.dev/skills-to-prd), which hands it a settled spec with user stories to slice against, and [implement](https://aihero.dev/skills-implement), which builds each independently-grabbable issue, driving [tdd](https://aihero.dev/skills-tdd) internally to write the tests test-first. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. +It sits between [to-prd](https://aihero.dev/skills-to-prd), which hands it a settled spec with user stories to slice against, and [implement](https://aihero.dev/skills-implement), which builds each independently-grabbable issue, driving [tdd](https://aihero.dev/skills-tdd) internally to write the tests test-first, before its [code-review](https://aihero.dev/skills-code-review) pass. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/engineering/to-prd.md b/docs/engineering/to-prd.md index c225759..1a8dbde 100644 --- a/docs/engineering/to-prd.md +++ b/docs/engineering/to-prd.md @@ -53,7 +53,7 @@ That matters for agentic development: a good interface gives tests something dur `to-prd` is a step in the main build chain: ```txt -grill-with-docs → to-prd → to-issues → implement +grill-with-docs → to-prd → to-issues → implement → code-review ``` Reach for it after the plan and domain language are resolved, and before you break the work into implementation tickets. Its key neighbours are [grill-with-docs](https://aihero.dev/skills-grill-with-docs), which sharpens the context so the PRD is precise, and [to-issues](https://aihero.dev/skills-to-issues), which turns the PRD into independently-grabbable issues for [implement](https://aihero.dev/skills-implement) to build. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 4c71d22..b81c63f 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -23,6 +23,8 @@ The route most work travels. You have an idea and want it built. - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on. - **No** → **`/implement`** right here, in the same context window. + Either way, `/implement` closes out by running **`/code-review`** — a two-axis review (Standards + Spec) of the diff — before committing. Reach for **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point. + ### Context hygiene Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue.