Matt Pocock’s Three Skills: Four Core Terms and a Decision Table to Prompt Agents to Ask the Right Questions

1. Skills and problem shapes

Repository mattpocock/skills defines three SKILL.md files— codebase-design, prototype, and improve-codebase-architecture —each addressing a distinct class of issues. codebase-design: provides shared vocabulary and judgment principles; does not give concrete solutions or run scans. prototype: validates a concrete question with throwaway code; does not perform architecture refactoring, add tests, or ship code. improve-codebase-architecture: for mature modules, proposes candidates for deepening or cleanup; does not design final interfaces, only lists candidates.

2. Core vocabulary

codebase-design

enforces exact use of four terms: module , interface , seam , adapter .

deep module : a module whose interface is small and stable but hides large implementation complexity (John Ousterhout, *A Philosophy of Software Design*).

seam : a location where behavior can be changed without modifying the code (Michael Feathers, *Working Effectively with Legacy Code*). One adapter = hypothetical seam; two adapters = real seam.

locality : number of files touched by a change; higher locality means fewer files.

leverage : number of callers depending on a module; high leverage amplifies impact.

Testability chapter adds three hidden principles: accept dependencies instead of new, return results instead of side effects, keep surface area small.

3. Prototype skill

A prototype is throwaway code that answers a question. The question decides the shape.

Two mandatory keywords: throwaway and a question . LOGIC.md requires the question to be stated up front; answering the wrong question is considered waste.

Anti‑patterns (quoted from LOGIC.md):

Don’t add tests. A prototype that needs tests is no longer a prototype. Don’t wire it to the real database. Don’t generalise. No “what if we wanted to support X later.” Don’t ship the TUI shell into production.

Only the pure module (e.g., (state, action) => state, a state machine, or a set of pure functions) is retained. UI prototypes use a ?variant= query to switch among three structurally different variants, hidden in the production build.

Template for a logic prototype:

# Question
(One sentence that clarifies what the prototype must answer)

# Run
(pnpm run prototype/auth)

# State surface
(How the state is printed/rendered after each action)

4. Improve‑codebase‑architecture skill

When a module is already formed, the skill starts with an Explore phase whose mantra is “Scope before you scan”. The repository advises:

Do not scan the whole repo; first run git log --oneline to find hot spots (areas repeatedly changed).

Hot spots are typically where multiple features intersect (e.g., user permissions, order status, push notifications). After locating them, the codebase-design vocabulary is used to ask reflective questions such as “Is the module a pass‑through?” or “Is it obviously shallow?”.

The core judgment tool is the deletion test :

Imagine deleting the module. If complexity vanishes, it was a pass‑through. If complexity reappears across N callers, it was earning its keep.

Deletion test template:

# Module
(Name and path of the module to test)

# Delete scenario
(Who becomes simpler? Who becomes more complex if the module is removed?)

# Verdict
- pass‑through → delete
- earning its keep → keep / deepen
- unclear → defer decision

The discipline “One adapter means a hypothetical seam. Two adapters means a real one.” is reiterated: only create a seam when a second implementation is truly needed. DEEPENING.md adds that old unit tests on shallow modules must be removed once tests at the deepened module’s interface exist.

5. Report before design

The second stage of improve-codebase-architecture generates an HTML report (written to a temporary OS directory, never committed). Each candidate card contains:

Files involved

Problem (one sentence)

Solution (one sentence)

Benefits (how locality, leverage, and tests improve)

Before/after diagram

Recommendation strength badge (Strong / Worth exploring / Speculative)

The report must not propose concrete interfaces:

Do NOT propose interfaces yet.

Instead the agent asks the user “Which of these would you like to explore?” After selection, a “grilling loop” runs via /grilling and /domain-modeling, keeping CONTEXT.md in sync. Parallel sub‑agents then generate multiple interface candidates (minimal interface, maximal flexibility, common caller optimisation, ports & adapters). The main agent compares depth, locality, and seam placement and issues a strong opinion (“Be opinionated — the user wants a strong read, not a menu”).

6. Decision table

Mapping of current project state to next action, skill to trigger, and what to avoid:

State‑machine bug discovered at runtime → write Question/Run → trigger prototype + LOGIC.md → avoid direct refactoring.

UI design undefined → write ?variant=A to switch three structurally different variants → trigger prototype + UI.md → avoid shipping a single variant.

Module repeatedly changed → run git log → trigger improve-codebase-architecture → avoid scanning the whole repo.

Suspected pass‑through module → run deletion test via codebase-design → avoid deepening before the test.

Only one adapter present → do not create a seam → avoid premature abstraction.

Candidate selected → run DESIGN-IT-TWICE.md to generate parallel interface candidates → avoid letting a single agent self‑evaluate.

Agent attempts large token‑heavy autonomous run → enforce constraints in codebase-design prompt → avoid uncontrolled self‑execution.

7. Common pitfalls

Premature abstraction : creating a seam as soon as a second adapter is imagined violates the “one adapter = hypothetical seam” rule.

Wrong timing for prototype : invoking the prototype skill after a design is already fixed can pull the workflow back to a throwaway path (issue #384).

Replacing judgment with rigid heuristics : the deletion test indicates whether complexity disappears, not whether the module should be removed; architectural intent still requires human judgment.

8. Limitations

Development‑speed gains are not empirically verified (issue #458).

Token‑cost savings are not guaranteed; the workflow itself consumes tokens.

Agent self‑execution risks are real; both codebase-design and prototype can be mis‑invoked without proper prompt constraints.

Switching between Chinese and English prompts can break continuity (issue #640).