diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index fdf6f50..82b7fb3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,7 @@ { "name": "mattpocock-skills", "skills": [ + "./skills/engineering/ask-matt", "./skills/engineering/diagnosing-bugs", "./skills/engineering/grill-with-docs", "./skills/engineering/triage", diff --git a/README.md b/README.md index ba5ea70..147403b 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,7 @@ Skills I use daily for code work. **User-invoked** +- **[ask-matt](./skills/engineering/ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo. - **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./skills/engineering/triage/SKILL.md)** — Move issues through a state machine of triage roles. - **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 444cb43..21bace5 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -6,6 +6,7 @@ Skills I use daily for code work. Reachable only when you type them (`disable-model-invocation: true`). +- **[ask-matt](./ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo. - **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./triage/SKILL.md)** — Move issues through a state machine of triage roles. - **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md new file mode 100644 index 0000000..3d6be69 --- /dev/null +++ b/skills/engineering/ask-matt/SKILL.md @@ -0,0 +1,59 @@ +--- +name: ask-matt +description: Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo. +disable-model-invocation: true +--- + +# Ask Matt + +You don't remember every skill, so ask. Describe where you are — "I've got a vague idea", "bugs are piling up", "this code's a mess" — and this answers with the **flow** to follow and the skill to type next. + +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. + +## 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 when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone.) +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 (see Crossing sessions): + - **`/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-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues) → **`/implement`** the issues one by one, each in its own agent. + - **No** → **`/implement`** right here, in the same context window. + +### 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. + +The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread. + +## 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. + +## 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`. + +## Crossing sessions + +- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**. +- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues. + +## Standalone + +Off the main flow entirely. + +- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo. +- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace. +- **`/writing-great-skills`** — reference for writing and editing skills well. + +## Precondition + +**`/setup-matt-pocock-skills`** — run once per repo before any engineering flow. It configures the issue tracker, triage labels, and doc layout the other skills assume. diff --git a/skills/in-progress/review/SKILL.md b/skills/in-progress/review/SKILL.md index e6c4001..63e71f3 100644 --- a/skills/in-progress/review/SKILL.md +++ b/skills/in-progress/review/SKILL.md @@ -3,8 +3,6 @@ name: 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/PRD 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". --- -# Review - 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? @@ -18,7 +16,7 @@ The issue tracker should have been provided to you — run `/setup-matt-pocock-s ### 1. Pin the fixed point -Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what — a branch, a commit, or `main`?" Don't proceed until you have it. +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 ...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log ..HEAD --oneline`. @@ -57,7 +55,7 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor ### 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*). +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.