Skill Case Studies — MattPocock Skills

Session 3 · Case-study studio

Watch the design work

The first session gave you analytical axes. The second gave you a design loop. Now orient in the full portfolio before three real skills make those ideas visible—or expose where the theory does not quite explain the file.

65 minutes · one system map · three case files · one transfer lab · progress saved locally

Carry forward

Do not ask whether a skill “looks good.” Trace what failure it prevents, who invokes it, where its knowledge lives, how it constrains behavior, and what would count as evidence.

Your artifact

You will leave with a working map of all 25 skills, three completed traces, and a revised borrowing ledger grounded in concrete files rather than abstract preference.

0–15 minutes

1. See the system, then trace the cases

Surface formats mislead. A long file can be a tight discipline; a short file can hide a large dependency graph. Run the same five questions in the same order so the differences become comparable.

The five-part trace

1 · FailureWhat recurring mistake gives this skill a reason to exist?

2 · InterfaceWhat shape is it, and who owns invocation?

3 · PlacementWhat is inline, disclosed, or recovered from the environment?

4 · ControlWhat gate, loop, or separation changes the model’s default?

5 · EvidenceWhat observation could show that the control worked?

How Sessions 1 and 2 meet

Session 1 explains the interface: shape, invocation, composition, and evidence labels. Session 2 explains the mechanism: problem, pointer, information layer, control loop, and test. A case study is the full trace from one to the other.

Bird’s-eye view · 25 skills

The portfolio is a flow with support underneath

ask-matt is the human-chosen router. Its most useful claim is structural: one main route carries ideas toward shipped code, several on-ramps join that route, and vocabulary plus standalone tools support work without becoming extra stages.

The whole portfolio is visible. Each card states the skill’s goal; choose a starting situation to reveal one route through the system.

/ask-matt Orient the human: choose a fitting flow or skill, then hand control away.

/setup-matt-pocock-skills Configure the issue tracker, triage labels, and documentation layout the engineering flows assume.

Main flow · idea → ship

the route most feature work travels

/grill-with-docs Sharpen an idea by interview while preserving shared terms and decisions in the repo.

/to-spec Collapse the conversation or decision map into a buildable specification.

/to-tickets Split a plan into tracer-bullet tickets with explicit blocking edges.

/implement Build one issue from agreed seams through review and commit.

/tdd Drive one vertical red–green slice at a time.

/code-review Judge Standards and Spec independently.

runnable question?

/handoff Carry essential context across a new directory, harness, session, or collaborator.

→

/prototype Answer one design question with a small throwaway program, then return the finding.

On-ramps

different starts, deliberate merge points

/triage Turn raw incoming bugs and requests into agent-ready issues. joins at /implement →

/diagnosing-bugs Build a red-capable feedback loop before theorizing, then fix with a regression test. fixes, then may feed upkeep →

/wayfinder Resolve decision tickets until a huge, foggy effort has a shared map. joins at /to-spec →

Codebase health

upkeep generates better ideas

/improve-codebase-architecture Survey for deepening opportunities, then feed a chosen improvement into /grill-with-docs.

Vocabulary underneath

shared words, not extra stages

/domain-modeling Sharpen domain terms, scenarios, glossaries, and hard-to-reverse decisions.

/codebase-design Shape deep modules with small interfaces, clean seams, and local reasoning.

Standalone and supporting tools

use when the situation—not the pipeline—calls for them

/grill-meRun the same relentless interview without saving state to a working directory.

/grillingSupply the reusable interview primitive: rounds, frontier, facts, and human decisions.

/resolving-merge-conflictsResolve an active merge or rebase conflict by intent and finish the operation.

/researchInvestigate primary sources in the background and leave a cited Markdown finding.

/to-questionnaireTurn a knowledge gap into questions for the person who can answer it.

/wizardGuide a human through credentials, dashboards, provisioning, or other human-only steps.

/wait-whatRe-pitch an explanation that failed to land, using the missing context and shared vocabulary.

/teachTeach a concept across multiple stateful sessions in the current directory.

/writing-for-agentsGuide writing for skills, agent instructions, and documents reached by pointers.

One operating rule crosses the map: at a phase boundary, choose deliberately among continuing, clearing, handing off, delegating to a subagent, or compacting. Diagram reconstructed from the current ask-matt/SKILL.md and the repository’s engineering/productivity indexes, checked August 11, 2026.

15–45 minutes

2. Three skills, three control strategies

Move freely between the cases. Each case links to its original SKILL.md; your current case and lens are restored when you return.

Human-invoked · router · map of flows

`ask-matt`: useful because it does not do the work

Its interface is orientation. It turns “which skill, in what order?” into a named routing decision, then hands control away.

Read the original SKILL.md ↗

The left column is the complete, unmodified SKILL.md. Read it continuously; the numbered margin comments point to important design decisions without replacing the source.


              ---
              name: ask-matt
              description: Ask which skill or flow fits your situation. A router over the skills in this repo.
              disable-model-invocation: true
              ---
              
              # Ask Matt
              
              You don't remember every skill, so ask.
              
              A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
              
              ## The main flow: idea → ship
              
              The route most work travels. You have an idea and want it built.
              
              1. **`/grill-with-docs`** — sharpen the idea by interview. Start here whenever you are **working in a working directory**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No working directory? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail, which makes it the better of the two whenever a repo is there to leave it in.)
              2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (a prototype lives in its own directory, which is exactly what `/handoff` is for — see Phase boundaries):
                 - **`/handoff`** out, then open a fresh session against that file,
                 - **`/prototype`** to answer the question with throwaway code,
                 - **`/handoff`** back what you learned, and reference it from the original idea thread.
              3. **Branch — is this a multi-session build?**
                 - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
                 - **No** → **`/implement`** right here, in the same context window.
              
                 Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/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-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
              
              The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/compact` at the nearest phase boundary and carry on (see Phase boundaries).
              
              ## On-ramps
              
              A starting situation that generates work, then merges onto the main flow.
              
              - **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
              
                Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
              
              - **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
              
              - **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
              
                When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`/to-spec`**, which collapses the map's linked decisions into a buildable plan, then `/to-tickets` and `/implement` as usual. Looping the map straight into `/implement` skips that collapse and throws the linked detail away — go straight to `/implement` only when the effort turned out genuinely small.
              
              ## Codebase health
              
              Not feature work — upkeep.
              
              - **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
              
              ## Vocabulary underneath
              
              Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
              
              - **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
              - **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
              
              ## Phase boundaries
              
              A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. At the **boundary** between two of them you have five options, and picking between them is the fuzziest decision in this whole map:
              
              - **Continue** — stay put. Costs nothing, loses nothing.
              - **`/clear`** — empty the window, when nothing here matters to what's next.
              - **`/handoff`** — write a portable markdown file. Narrow: only for a **new harness**, a **new directory**, a **colleague**, or forking a side task **mid-phase**. What it buys is portability.
              - **Subagent** — send a tightly-scoped task to its own window and get a report back.
              - **`/compact`** — compress this context and seed a fresh session with it. The **default**, at the bottom of the tree rather than the first reach.
              
              Read [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) for the ordered tree — the five questions, the reasoning behind each branch, and why the primary-source cost makes **Continue** the one to rule out first. Make the decision **at** a boundary; mid-phase, continue or split the rest into subagents.
              
              ## Standalone
              
              Off the main flow entirely.
              
              - **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but **stateless**: it saves nothing locally and builds no `CONTEXT.md`. Reach for it when you are **not working in a working directory** — sharpening a plan, a design, a piece of writing, anything with no repo under it. If you are in a working directory, use `/grill-with-docs` instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.
              - **`/grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
              - **`/resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
              - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
              - **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
              - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
              - **`/wizard`** — for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
              - **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
              - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
              - **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.
              
              ## Precondition
              
              **`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.

01Invocation ownership

Line 4 · The metadata makes this a menu you choose yourself. The agent cannot silently route through it.

02The main route

Line 13 · This heading begins the default path from an idea to implementation. The numbered branches below are the router’s central work.

03Protect connected context

Line 28 · Interview, spec, and tickets stay together; each implementation ticket starts fresh. Context boundaries are part of the workflow.

04Three different entrances

Line 34 · Raw incoming work, a stubborn bug, and a huge foggy effort join the main route in different places.

05Shared vocabulary

Line 54 · These two skills supply common words to other workflows. They are reference layers, not extra ceremonies.

06Progressive disclosure

Line 61 · The five phase-boundary choices stay visible here; the detailed decision tree lives in a separate referenced file.

07Outside the pipeline

Line 73 · The standalone list prevents the idea-to-ship path from pretending that every useful skill belongs inside it.

08Explicit precondition

Line 88 · The other engineering skills assume shared tracker and documentation conventions, so setup is part of the interface.

Model-invoked · reusable discipline · gated loop

`diagnosing-bugs`: no theory before a red-capable loop

The file does not mainly teach debugging facts. It changes the order in which the agent is allowed to form confidence.

Read the original SKILL.md ↗

The left column is the complete, unmodified SKILL.md. Read it continuously; the numbered margin comments point to important design decisions without replacing the source.


              ---
              name: diagnosing-bugs
              description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
              ---
              
              # Diagnosing Bugs
              
              A discipline for hard bugs. Skip phases only when explicitly justified.
              
              When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
              
              ## Redact
              
              This skill has you show commands, outputs and captured artifacts. **Redact every secret first** — write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
              
              If the redacted output is not enough to diagnose the bug, say so and ask the user.
              
              ## Phase 1 — Build a feedback loop
              
              **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
              
              Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
              
              ### Ways to construct one — try them in roughly this order
              
              1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
              2. **Curl / HTTP script** against a running dev server.
              3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
              4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
              5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
              6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
              7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
              8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
              9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
              10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
              
              Build the right feedback loop, and the bug is 90% fixed.
              
              ### Tighten the loop
              
              Treat the loop as a product. Once you have _a_ loop, **tighten** it:
              
              - Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
              - Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
              - Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
              
              A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower.
              
              ### Non-deterministic bugs
              
              The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
              
              ### When you genuinely cannot build a loop
              
              Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
              
              ### Completion criterion — a tight loop that goes red
              
              Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:
              
              - [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
              - [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
              - [ ] **Fast** — seconds, not minutes.
              - [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
              
              If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
              
              ## Phase 2 — Reproduce + minimise
              
              Run the loop. Watch it go red — the bug appears.
              
              Confirm:
              
              - [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
              - [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
              - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
              
              ### Minimise
              
              Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
              
              Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
              
              Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
              
              Do not proceed until you have reproduced **and** minimised.
              
              ## Phase 3 — Hypothesise
              
              Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
              
              Each hypothesis must be **falsifiable**: state the prediction it makes.
              
              > Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
              
              If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
              
              **Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
              
              ## Phase 4 — Instrument
              
              Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
              
              Tool preference:
              
              1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
              2. **Targeted logs** at the boundaries that distinguish hypotheses.
              3. Never "log everything and grep".
              
              **Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
              
              **Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
              
              ## Phase 5 — Fix + regression test
              
              Write the regression test **before the fix** — but only if there is a **correct seam** for it.
              
              A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
              
              **If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
              
              If a correct seam exists:
              
              1. Turn the minimised repro into a failing test at that seam.
              2. Watch it fail.
              3. Apply the fix.
              4. Watch it pass.
              5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
              
              ## Phase 6 — Cleanup + post-mortem
              
              Required before declaring done:
              
              - [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
              - [ ] Regression test passes (or absence of seam is documented)
              - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
              - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
              - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
              
              **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

01A discoverable discipline

Line 3 · The description names both the behavior and concrete trigger words: diagnose, debug, broken, failing, and slow.

02Evidence can leak secrets

Line 12 · Redaction appears before diagnosis because every later phase may expose commands, logs, traces, or captured requests.

03The load-bearing phase

Line 18 · The skill refuses causal stories until one command can show the exact bug. Everything later consumes this signal.

04Treat the loop as a product

Line 39 · A reproduction is not enough: it must become faster, sharper, and more deterministic so repeated experiments stay cheap.

05Flakes need probability, not perfection

Line 49 · For nondeterministic bugs, raising the reproduction rate creates a useful signal even when certainty is impossible.

06A real completion gate

Line 57 · Four checkable properties must be true before Phase 2. This is stronger than advice to “try reproducing first.”

07Reproduce, then minimise

Line 68 · First prove it is the user’s bug; then remove every element that is not necessary. These are separate jobs.

08Several falsifiable causes

Line 88 · Ranking multiple predictions counters attachment to the first plausible explanation and gives instrumentation something to distinguish.

09Instrument predictions

Line 100 · Each probe tests one hypothesis. Broad logging creates volume; targeted boundaries create discriminating evidence.

10Test at the real seam

Line 114 · A convenient shallow test can pass while the original bug remains possible. No honest seam is itself an architectural finding.

11Close the original loop

Line 130 · Completion returns to the unminimised reproduction, removes temporary scaffolding, and preserves the causal lesson.

Model-invoked · parallel review · aggregation

`code-review`: protect two questions from each other

Instead of asking whether a diff is “good,” the skill preserves two independent judgments: standards conformance and specification fidelity.

Read the original SKILL.md ↗

The left column is the complete, unmodified SKILL.md. Read it continuously; the numbered margin comments point to important design decisions without replacing the source.


              ---
              name: code-review
              description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
              ---
              
              Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
              
              - **Standards** — does the code conform to this repo's documented coding standards?
              - **Spec** — does the code faithfully implement the originating issue / spec?
              
              Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
              
              The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
              
              ## Process
              
              ### 1. Pin the fixed point
              
              Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
              
              Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
              
              Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
              
              ### 2. Identify the spec source
              
              Look for the originating spec, in this order:
              
              1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
              2. A path the user passed as an argument.
              3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
              4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
              
              ### 3. Identify the standards sources
              
              Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
              
              On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
              
              - **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
              - **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
              
              Each smell reads *what it is* → *how to fix*; match it against the diff:
              
              - **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
              - **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
              - **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
              - **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
              - **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
              - **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
              - **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
              - **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
              - **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
              - **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
              - **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
              - **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
              
              ### 4. Spawn both sub-agents in parallel
              
              **Standards sub-agent prompt** — include:
              
              - The full diff command and commit list.
              - The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
              - The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
              
              **Spec sub-agent prompt** — include:
              
              - The diff command and commit list.
              - The path or fetched contents of the spec.
              - The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
              
              If the spec is missing, skip the Spec sub-agent and note this in the final report.
              
              ### 5. Aggregate
              
              Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
              
              End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
              
              ## Why two axes
              
              A change can pass one axis and fail the other:
              
              - Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
              - Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
              
              Reporting them separately stops one axis from masking the other.

01The description is unusually complete

Line 3 · It names the artifact, both questions, the parallel mechanism, and the requests that should trigger the skill.

02Two independent questions

Line 6 · Engineering quality and specification fidelity can disagree. The rest of the file protects that disagreement.

03Freeze the review target

Line 17 · Both reviewers must examine the same merge-base diff. Invalid or empty input fails before parallel work begins.

04Recover requested intent

Line 25 · The spec search has an explicit order and an honest fallback: skip that axis only after confirming no spec exists.

05Local standards come first

Line 34 · Repository rules override the built-in smell list; smells remain judgment calls and tooling-owned checks are omitted.

06Reference embedded in the skill

Line 43 · The smell catalog is shared review vocabulary. It gives the standards reviewer a baseline when local documentation is thin.

07Context isolation is the mechanism

Line 58 · Each sub-agent receives one evidence bundle and one question, so success on one axis cannot bias the other.

08Do not blend at the end

Line 74 · The aggregator preserves separate reports and summaries. A single overall ranking would undo the entire design.

09The crossed cases explain why

Line 80 · Standards can pass while Spec fails, or the reverse. These examples are also the clearest behavior test for the skill.

Case 1 of 3

License for the reproduced skill files

MIT License

Copyright (c) 2026 Matt Pocock

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

45–50 minutes

3. Compare the mechanisms, not the prose

The cases look different because each one controls a different source of variance. The shared architecture becomes clearest in a matrix.

Lens

ask-matt

diagnosing-bugs

code-review

Variance controlled

Route selection

Premature causal confidence

One criterion masking another

Primary mechanism

Explicit handoff map

Ordered gates around a feedback loop

Independent contexts, then aggregation

Invocation cost

Human must remember to ask

Model carries a trigger pointer

Model carries a detailed review pointer

Fragile edge

Map can drift from child files

Heavy process can become ritual

Depends on recoverable source documents

The synthesis

“A skill is a behavioral contract” now has three concrete meanings: ask-matt constrains the handoff, diagnosing-bugs constrains the order of belief, and code-review constrains the separation of judgment.

50–59 minutes

4. Fresh file: reconstruct `tdd`

No walkthrough this time. The current file describes a model-discoverable reference for a red → green loop, asks the learner to agree testing seams first, discloses examples and mocking guidance, and forbids horizontal slicing. Use the trace yourself.

Build the trace

1 / 4

59–65 minutes

5. Revise the borrowing ledger

You are deciding about mechanisms, not endorsing whole files. Your choices persist locally.

A router that performs no downstream work

Useful when humans face a dense library; fragile when its map becomes a second source of truth.

A hard gate before expensive reasoning

Prevents premature confidence; needs an escape clause precise enough not to swallow the rule.

Separate contexts for independent judgments

Protects evidence boundaries when one attractive result could bias the other.

Course result

You can now move in both directions: from a file back to its hidden design decisions, and from a recurring failure forward to a skill whose interface, information, gates, and tests are deliberate.

Source notes

This session was checked against the public repository on August 11, 2026. Section 2 reproduces each case file in full and without rewriting; the accompanying margin comments are ours.

1. See the system, then trace the cases

The portfolio is a flow with support underneath

Main flow · idea → ship

On-ramps

Codebase health

Vocabulary underneath

Standalone and supporting tools

2. Three skills, three control strategies

ask-matt: useful because it does not do the work

diagnosing-bugs: no theory before a red-capable loop

code-review: protect two questions from each other

3. Compare the mechanisms, not the prose

4. Fresh file: reconstruct tdd

Build the trace

5. Revise the borrowing ledger

A router that performs no downstream work

A hard gate before expensive reasoning

Separate contexts for independent judgments

Source notes

`ask-matt`: useful because it does not do the work

`diagnosing-bugs`: no theory before a red-capable loop

`code-review`: protect two questions from each other

4. Fresh file: reconstruct `tdd`