71eb50346f
Every docs page opened with a [Source](github.com/...) link, and .agents/writing-docs.md told agents to add one to each new page. Remove the line from all 25 pages, rewrite the one inline use in ask-matt.md, and drop the rule from the page template, the fixed frame list, and the "Done when" list so the links do not come back. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.0 KiB
What it does
ask-matt is the router over the skills in this repo. You describe the situation you're in; it tells you which skill or flow fits and in what order to run them.
It does no work itself. It doesn't grill, write a spec, or fix anything — it only orients. It exists for the user-invoked skills above all: nothing fires those for you, so you have to remember they exist, and ask-matt is the memory you offload that to. It also points at the model-invoked skills you'd reach for by name — /tdd, /diagnosing-bugs, /prototype, /code-review, and the two vocabulary references, /domain-modeling and /codebase-design. It answers "which one, and when", then hands you off to the skill that actually does the job.
When to reach for it
You invoke this by typing /ask-matt — the agent won't reach for it on its own.
Reach for it whenever you're unsure which skill or flow a situation calls for: you have an idea and don't know where to start, a pile of bug reports and don't know if they're for /triage, or two skills that look interchangeable and you can't tell them apart. If you already know the skill you want, skip the router and invoke it directly.
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 → spec → tickets → 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.
Phase boundaries
The other idea it hands you is the phase boundary. A phase is a chunk of work inside a session — the grilling, the implementation, the QA — and the boundary between two of them is where you decide what to do with the context you've built up. You have five options: continue, /clear, /handoff, a subagent, or /compact. ask-matt carries the decision tree that orders them, and the two corrections most people need: /handoff is narrow — it earns its keep only when something has to travel (a new harness, a new directory, a colleague, a side task forked mid-phase) — and /compact is the tree's default at the bottom, not its first reach. Reach for the tree at a boundary; mid-phase there's nothing to decide.
Where it fits
ask-matt is the router — the standalone map that sits over the whole set. It is the node every other docs page links back to as ask-matt, so it never sits in a chain; it points into every chain. From here you'll most often land on grill-with-docs, the head of the main flow, or triage, the on-ramp for work you didn't create. When even the router's own picture is stale, the skill itself is the map of record.