Brians-brain/claude-skills

Ask Matt

Respond in Traditional Chinese.

You won't remember every skill, so ask.

Before explaining what a skill does, or suggesting skipping a step, read that skill's SKILL.md: the summary here is just for orientation.

A flow is a path through these skills. Most paths follow a main flow, with two on-ramps merging into it. Others are for standalone use, or are vocabulary layers that operate underneath.

Main Flow: Idea → Launch

The route for most work. You have an idea, and you want to build it.

1. /grill-with-docs Sharpens an idea through interviews. As long as you are working in a working directory, start here: it is stateful, keeping learned things in GLOSSARY.md and ADRs. (No working directory? Use /grill-me, see "Standalone Use". Both execute the same /grilling mechanism; grill-with-docs leaves written records, so if you have a repo to leave them in, it's the better choice.)

2. Branch: Can every question be answered in conversation? If a question needs an executable answer (state, business logic, a UI you must see), take the detour through a prototype, using /handoff to connect both directions (the prototype lives in its own directory, which is exactly what /handoff is for; see "Phase Boundaries"):

   • Hand it off with /handoff, then open a new session for that file,
   • Use /prototype to answer the question with throwaway code,
   • Use /handoff to hand the learned lessons back, referencing the original idea thread.

3. Branch: Is this a build that needs multiple sessions?

   • Yes → /to-spec (turn the thread into a spec), then use /to-tickets to break it into tracer-bullet tickets, each marking its blocking edge. Then handle tickets in one of two ways:
     • Use /implement once per ticket, /clear context between each ticket. On a local tracker, that's one file per ticket under .scratch/<feature>/issues/, processed manually in blocking-priority order; on a real tracker, edges become native blocking links, so any ticket whose blockers are all done can be picked up. Each ticket is self-contained, so the previous ticket's context can be discarded.
     • Use /implement-spec to run the entire spec at once. It reads tickets as a task graph, executes implementation sub-agents in parallel on the ready frontier, and lands everything on the same integration branch. Use it when you'd rather orchestrate the whole build instead of manually advancing ticket by ticket.
   • No → Use /implement right here, in the same context window.

   Either way, code is built through /tdd (one red-green slice at a time), and finalized with /code-review-zh, which performs a dual-axis review (Standards + Spec) on the diff. /implement runs both per ticket; /implement-spec's implementors each use /tdd, then runs /code-review-zh on the integration branch once. Use /tdd standalone when you just want to build a concrete behavior test-first without a full spec; use /code-review-zh standalone when you want to review a branch or PR against a fixed reference point.

   When work is ready to be submitted as a pull request, /pr shapes the PR body: minimal visual for the change, before/after evidence proving it works, and one-way/two-way door judgment. It's model-call-based, so the agent uses it every time it writes a PR.

4. /retro closes the loop. After a build—especially one that went wrong—it reviews the session and suggests improvements to the agent's work environment, not the code: navigation cues, automated checks, writing norms enforced by /code-review-zh, guide files, tools. Mechanical errors become deterministic checks; judgment calls become writing norms. The next build starts from a better environment.

Session Hygiene

Keep steps 1–3 in the same uninterrupted context window (don't compact or clear before /to-tickets), so the interrogation, spec, and tickets all build on the same thinking. After that, each /implement starts fresh, working from the ticket. Run /retro in the session it's reviewing, before clearing; if already cleared, point it at that session's logs.

The constraint here is the smart zone: the window within which the model still reasons acutely (~150k tokens on cutting-edge models). If a session approaches this limit before /to-tickets, don't push through in a degraded state; /compact at the nearest phase boundary, then continue (see "Phase Boundaries").

On-Ramps

Starting contexts that generate work before merging into the main flow.

• Bugs and requests piling up → /triage. It moves issues through triage roles, producing agent-ready issues that /implement then picks up.

  Triage is only for issues you didn't create: bug reports, incoming feature requests, anything that arrives unprocessed. Tickets generated by /to-tickets are already agent-ready, so don't triage them.

• Something is broken → /diagnosing-bugs. For the tricky ones: bugs that aren't obvious at first glance, intermittent instability, regressions that sneak in between two known-good states. It refuses to propose a theory until it has a tight feedback loop (a command that already goes red because of this bug), then fixes with a regression test. After fixing, run /retro in the same session, asking what could prevent this bug; if the real finding is that there's no good seam to lock it up, that's a job for /improve-codebase-architecture.

• A large, foggy project: brand-new project or massive feature build that doesn't fit in one session → /wayfinder, the most brain-intensive flow here. When the path from here to the destination isn't visible yet, it draws a shared map of decision tickets on the issue tracker, resolving them one at a time, producing decisions not deliverables, until the fog lifts and the path becomes clear. /grill-with-docs sharpens an idea you can grasp in one session; wayfinder handles ideas you can't, and it's slower and denser, so reserve it for that case and never use it for a well-scoped feature.

  Once the map is clear, it hands off, not builds: it merges into the main flow at /to-spec, which converges the map's connected decisions into a buildable plan, followed by the usual /to-tickets and /implement. Plugging the map directly into /implement skips this convergence, losing the connected details, so only do that if the project turns out to be very small after all.

Code Health

Not feature development, just maintenance.

• /improve-codebase-architecture Run it when you have time, to keep the codebase in an agent-friendly state. It finds deepening opportunities; selecting one generates an idea you can bring to the main flow's /grill-with-docs. It's exploration to find candidates; /codebase-design (see below) is the workbench where you design the selected candidate.

Foundational Vocabulary

Two model-call-based references that operate underneath other skills, each being the single source of truth for its vocabulary. Use them directly when the problem is about terminology rather than process; or let the skills above pull them in.

• /domain-modeling: Sharpens the project's domain language: challenges a fuzzy term, resolves an overloaded word (e.g., "part number" meaning three different things), records a hard-to-undo decision as an ADR. It's the active discipline /grill-with-docs uses to keep GLOSSARY.md clean.
• /codebase-design is the deep module vocabulary (modules, interfaces, depth, seams, adapters, leverage, locality), used to design a module's shape: lots of behavior behind a small interface on clean seams. Both /tdd and /improve-codebase-architecture use it.

Phase Boundaries

A phase is a chunk of work within a session: interrogation, implementation, QA. At the boundary between two phases, you have five options, and choosing between them is the fuzziest decision on the entire map:

• Continue: Stay put. Costs nothing, loses nothing.
• /clear: Clear the window, when nothing here matters for what comes next.
• /handoff Write a portable markdown file. Narrow use only: changing harness, changing directory, handing to a colleague, or forking a side task mid-phase. It trades for portability.
• Sub-agent: Send a well-scoped task to its own window and get back a report.
• /compact Compress this context and use it to start a new session. It is the default, at the bottom of the tree, not the first thing to reach for.

The sequential decision tree is in PHASE-BOUNDARIES.md: five questions, the reasoning behind each branch, and why the cost of first-hand data makes Continue the first option to rule out. Decide at the boundary; mid-phase, either continue or offload the rest to a sub-agent.

Standalone Use

Completely off the main flow.

• /grill-me: Same rigorous interview as /grill-with-docs, but stateless: it saves nothing locally, doesn't create GLOSSARY.md. Use it when you are not working in a working directory (sharpening a plan, a design, an article—anything without a repo underneath). If you are in a working directory, use /grill-with-docs instead: it does the same interview and leaves written records, so it's strictly better.
• /grilling is the interview mechanism itself: rounds, frontier, fact-finding is the agent's job, decision-making is yours. /grill-me and /grill-with-docs are two named entry points, and /triage, /wayfinder, and /improve-codebase-architecture all execute it internally. Use it directly only when you want the bare interview with no wrapper.
• /prototype is a small throwaway program answering a design question: does this state model make sense, 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 gets incorporated into production code, the prototype itself is preserved as first-hand data on a prototype/<name> branch off main, referenced from the implementation ticket. It's the detour in main flow step 2, but usable any time a design question is hard to answer on paper.
• /research: Offloads reading legwork to a background agent: it investigates a question from primary sources, then leaves an attributed markdown file in the repo. While it reads, you keep working. The file it produces is something to take into the main flow's /grill-with-docs, because research feeds thinking, not replaces it.
• /to-questionnaire For when what's blocking you is not in your head or the code, but in someone else's head: it helps you write a questionnaire for them to fill out. It's the flip side of /grill-me: instead of interrogating you about your subject, it interrogates you about the delivery (who to send it to, what you need back), and aims questions at the gap. What you get back is fodder for /grill-with-docs or /to-spec.
• /wizard For steps that only a human can do: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party admin panel, running a one-off migration or switch. It generates an interactive bash script that opens each URL, captures each value, and writes it into .env and GitHub secrets, making the procedure something you no longer have to re-explain to the agent every time. It's model-call-based, so the agent uses it as soon as it hits a wall only you can pass. If the agent could do it itself, it should; this is for cases that genuinely need a human in the loop.
• /wait-what Rescue for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent will fill in the context you missed, re-explaining what it just said in plain language using GLOSSARY.md vocabulary. It's a rescue; /grill-with-docs is the preventative, because shared language established early prevents terminology from being a problem in the first place.
• /teach: Uses the current directory as a stateful workspace to learn a concept across multiple sessions.
• /writing-for-agents Reference for writing documents meant for agents: skills, AGENTS.md/CLAUDE.md, documents that are pointed to.
• /handoff: Compress the current conversation into a handover document for a new session, directory, or colleague (see "Phase Boundaries").
• /git-guardrails-claude-code: Installs a Claude Code hook that blocks dangerous git commands (push, reset --hard, etc.) before they execute. Set up once per machine or per project.

Prerequisites

/setup-matt-pocock-skills: Run before using any engineering flow for the first time. Sets up the issue tracker, triage labels, and file layout that other skills assume. Also supports custom issue trackers.