ask-matt

Ask Matt

You don't have to remember every skill, so just ask.

Before explaining what a skill does or suggesting skipping a step, first read that skill's SKILL.md: the summaries here are only for locating.

flowis a path through the skills. Most paths follow amain flowand travel along it, with twoon-rampsmerging into it. Everything else is either a standalone skill or a vocabulary layer running underneath.

Main flow: idea → delivery

The route most work takes. You have an idea and want to build it.

1. /grill-with-docs: refine the idea through interrogation. As long as you are in aworking directory, start here: it is stateful and keeps what it learns in GLOSSARY.md and ADRs. (No working directory? Use /grill-me, see "standalone skills". Both run the same /grilling primitive;grill-with-docs is the one that leaves a written trace, so whenever there is a repository that can hold traces, it is the better choice.)

2. Branch: can all questions be resolved in conversation? If a question needs a runnable answer (state, business logic, UI that must be seen with your own eyes), detour through a prototype, bridged in both directions by /handoff (the prototype lives in its own directory, which is exactly where /handoff comes in, see "stage boundaries"):

   • /handoff jump out, then open a new session for that file,
   • /prototype use throwaway code to answer the question,
   • /handoff bring back what you learned and reference it in the original idea thread.

3. Branch: is this a multi-session build?

   • Yes → /to-spec(turn the conversation into a spec), then /to-tickets split it into tracer-bullet-style tickets, each declaring its ownblocking edges. Then advance the tickets in one of two ways:
     • /implement implement ticket by ticket,with /clear clearing context between each. On a local tracker, each ticket is a file under .scratch/<feature>/issues/ , advanced manually in blocking-first order; on a real tracker, blocking edges become native blocking links, so any ticket whose blockers are complete can be claimed. Each ticket is self-contained, so the previous one's context can be discarded.
     • /implement-spec implement the whole spec in one go. It reads the tickets as atask graph, runs implementer subagents in parallel on the claimablefrontier, and lands everything on oneintegration branch. Use it when you would rather orchestrate the whole build than drive the tickets one by one yourself.
   • No → in the same context window /implement。

   Either way, the code is built by driving /tdd(one red-green slice at a time), and finishes with /code-review , a two-axis review of the diff (standards + spec)./implement runs both of these steps once per ticket;/implement-spec each implementer drives their own /tdd, then run once on the integration branch /code-reviewOnly use it alone when you want to test-first build one specific behavior without a full spec, /tdd; use it alone whenever you want to review a branch or PR against a fixed point, /code-review。

   When the work is to be submitted as a PR,/pr is responsible for shaping the PR body: the minimal visualization that can articulate the change, before/after evidence proving it works, and the one-way door/two-way door judgment. It is model-invoked, so the agent proactively picks it up every time it writes a PR.

4. /retro closes this loop. After a build (especially a derailed one), it reviews the entire session and proposes changes for the agent'senvironment(not the code): navigation pointers, automated checks, coding standards enforced by/code-review , guidance files, tooling. Mechanical mistakes become deterministic checks; judgment calls become coding standards. The next build starts from a better environment.

Context hygiene

Keep steps 1–3 inone uninterrupted context window(do not compact or clear before /to-tickets ), so that the interrogation, spec, and ticket are all built on the same thinking. Afterward, each /implement starts fresh from the ticket. Run /retroin the session it reviewed, before clearing; after clearing, point it at that session's log.

The ceiling here is the **intelligence zone**: the window in which the model can still reason sharply (about 150k tokens for state-of-the-art models). If the session approaches it before /to-tickets , do not push on in a degraded state: /compact at the nearest phase boundary and continue (see "phase boundaries").

On-ramps

A starting-point scenario that generates work, then merges into the main flow.

• Bugs and requests pile up → /triage. It walks issues through the triage role, producing agent-ready issues, which are then taken over by /implement .

  Triage applies only toissues you did not create: bug reports, external feature requests, anything that arrives in raw form./to-tickets The tickets produced byare already agent-ready, so do not triage them。

• Something is broken → /diagnosing-bugs. For the tough ones: bugs that are not obvious at a glance, intermittent flakes, regressions that quietly slipped in between two known-good states. It refuses to theorize until it has atight feedback loop(a command that already goes red forthis bug), then fixes it with a regression test. Once the fix is done, run /retroin the same session and ask what could have prevented this bug; if the real finding is that a suitable seam is missing to pin it down, /improve-codebase-architecture handles it.

• A large, vague piece of work: a greenfield project or a large feature build, too big to fit in one session → /wayfinder. This is the highest-cognitive-load flow here. When the path from here to the destination is not yet visible, it draws on the issue tracker ashared map made up ofdecision tickets, resolving them one at a time: producingDecisions, not deliverables, until the fog is pushed back and the road is clear./grill-with-docs What you polish is the idea you can hold in a single session; wayfinder is for the ideas you can't hold: it's slower, denser, so reserve it only for such cases, and never use it for well-scoped features.

  When the map is clear,it hands off, it doesn't build: in /to-spec merge into the main workflow, fold the interconnected decisions on the map into a buildable plan, then proceed as usual with /to-tickets and /implement. Looping the map directly into /implement skips this folding and loses the interconnected details, so go directly into /implement。

Codebase health

Not feature work: maintenance.

• /improve-codebase-architecture: run it whenever you have time, to keep the codebase in an agent-friendly, workable state. It revealsdeepening opportunities; pick one andproduce an idea, which you can carry from /grill-with-docs into the main workflow. It's the survey that finds candidates;/codebase-design(see below) is the workbench where you design the chosen option.

Underlying vocabulary

Two references for model calls, running underother skills: each is the single source of truth for its vocabulary. When the problem is in thewordsrather than the process, reach for them directly; or let the skills above pull them in.

• /domain-modeling: polish the project'sdomainlanguage: challenge vague terms, resolve overloaded words ("account" doing triple duty), record hard-to-reverse decisions as ADRs. It's the proactive discipline that is /grill-with-docs -driven and keeps GLOSSARY.md as a clean glossary.
• /codebase-design: design the deep module vocabulary of a module'sshape(module, interface, depth, seam, adapter, leverage, locality): behind a clean seam, a small interface carrying a lot of behavior./tdd and /improve-codebase-architecture both speak this language.

Phase boundaries

Phaseis a block of work within a session: interrogation, implementation, QA. At theboundarybetween two phases you have five options, and on this map, which one to choose is the most ambiguous decision:

• Continue: stay put. It costs nothing and loses nothing.
• /clear: clear the window, when nothing here is relevant to the next step.
• /handoff: write a portable markdown file. Narrow use: only fora new environment、a new directory、a colleague, or tomid-phasefork a subtask. What it buys is portability.
• Subagent: send a strictly scoped task into its own window and get back a report.
• /compact: compress the current context and use it to seed a new session. It's thedefault, at the bottom of the tree rather than the first thing you reach for.

Read PHASE-BOUNDARIES.md for the decision tree of ordering: the five questions, the rationale behind each branch, and why the cost of primary sources makesContinuebecomes the first option to rule out. Make the decision at theboundary; mid-phase, either continue or split the remainder into sub-agents.

Standalone skills

Completely detached from the main flow.

• /grill-me: the same relentless interrogation as /grill-with-docs , butstateless: it saves nothing locally and builds no GLOSSARY.md. Use it when youare not in the working directory: polishing a plan, a design, an article, anything with no repo underneath it. If you are in the working directory, use /grill-with-docs instead: it runs the same interrogation and leaves a written trace, so strictly speaking it is better.
• /grilling: the interrogation primitive itself: rounds, frontier, facts are the agent's job and decisions are yours./grill-me and /grill-with-docs are two named entry points;/triage、/wayfinder and /improve-codebase-architecture both run it internally. Reach for it directly only when you want to interrogate but do not want any shell around it.
• /prototype: a small throwaway program that answers some 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 preserved as aprimary sourceon a branch named prototype/<name> outside main, pointed to by the implementation issue. It is a detour from step 2 of the main flow, but you can use it any time a design question is hard to settle on paper.
• /research: delegate the reading legwork to abackground agent: it investigates a question againstprimary sourcesand then leaves a Markdown file with citations in the repo. You keep working while it reads. The file it produces is meant to be broughtintothe main flow, at /grill-with-docs ; research feeds thinking, it does not replace it.
• /to-questionnaire: when what is blocking you is not in your head or in the codebase, but insomeone else'shead, this skill writes them a questionnaire to fill out. It is the opposite of /grill-me : instead of interrogating you about the subject, it interrogates you aboutsendingit (to whom, what you need back), and then aims the questions at the gaps. What comes back is material for /grill-with-docs or /to-spec .
• /wizard: for steps only ahumancan do: configuring infrastructure, setting up credentials or CI secrets, clicking around an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens URLs one by one, captures each value, and writes it into .env and GitHub secrets, so the process no longer needs to be re-explained to the agent every time. The model calls it, so the agent reaches for it as soon as it hits a wall only you can get past. If the agent can do it itself, it should do it itself; this is for cases that genuinely need a human in the loop.
• /wait-what: a correction for a message that did not land. Use it inside any other skill, mid-conversation, and the agent will restate what it just said in plain language, with the context you were missing, in the vocabulary of GLOSSARY.md . It is a remedy after the fact;/grill-with-docs is the antidote beforehand, because agreeing on a common language early is the only way to keep jargon from appearing.
• /teach: learn a concept across multiple sessions, treating the current directory as a stateful workspace.
• /writing-for-agents: a reference for writing documentation that agents consume: skills, AGENTS.md, and the documents they point to.

Prerequisites

/setup-matt-pocock-skills: run before the first engineering workflow to configure the issue tracker, triage labels, and documentation layout that other skills depend on. A custom issue tracker also works.