# What each skill is for 22 procedures ship into an adopted repo, and their names are terse on purpose. This page says what each one is for, grouped by **the moment it fires** rather than by what it writes - because a reader arrives with a situation, not with an artifact name. Every description below is the skill's own, verbatim from its frontmatter, which is what an agent reads when deciding whether to run it. If a description here does not match what the skill does, the skill is wrong, not this page. The folder itself, and the rule that decides whether a new skill earns its place, are in [`.claude/skills/`](tree/claude-skills.md). ## Deciding what to build Before anything is specified. These turn scattered material - a meeting, a hunch, an argument about who the product serves - into something the rest of the loop can read. | Skill | When to reach for it | |---|---| | `product-write` | Use when the repo needs to state what it is building and for whom - starting a product, "we never wrote down what this app actually does", a PRODUCT.md that is stale or empty, or an argument about scope that keeps recurring because nothing settles it. Interviews for the frame, drafts it, and marks what is still unknown rather than inventing it. | | `personas-write` | Use when the repo needs to name who it is for - "we don't have personas", specs written against "the user", an existing roster that no longer matches reality, or an argument about what a feature should do that keeps stalling on who it serves. Interviews for real users, or reconstructs candidates from the code when nobody remembers. | | `idea-write` | Use when someone floats something that might never ship - "what if we let hosts pre-approve repeat guests", "should we offer a paid tier", "I wonder whether we need multi-currency". Captures it end-to-end (including its provisional technical/business shape) in docs/ideas/ without minting a record or a spec, and moves it through idea -> exploring -> approved \| parked \| dropped as it firms up. | | `discovery-digest` | Use when someone hands over raw material rather than a request - meeting notes, a mail thread, a transcript, "here's what they said on the call", a half-decision nobody wrote down. Files it into the topic's dossier with its provenance, flags where it contradicts what is already recorded, and says whether the topic is ready to be specced. Never writes specs itself. | | `adr-write` | Use when a technical choice gets made that someone will argue about again - "we went with Postgres over Mongo", "we're dropping the queue", "let's use Fastify", "why did we do it this way?". Drafts the decision record from what you say plus what the code and discovery notes already show, then asks only what neither can answer. | | `bdr-write` | Use when a product or business call gets made - "we're charging per seat, not per user", "we're not supporting self-hosting", "this launches to the agency segment first", "we decided to drop the free tier". Drafts the record from what you say plus the product frame and discovery notes, then asks what neither can answer. | ## Specifying a capability Turning a decision into a spec that can be built from, and keeping that spec true as the world moves. `spec-update` is the one to reach for when the work has already started - going back to a spec mid-flight is normal, not a failure. | Skill | When to reach for it | |---|---| | `spec-specify` | Use when someone describes a feature, a behaviour, or something the product should do - "we need refunds", "users should be able to reset their password", "add a way to export bookings". Turns it into that capability's living spec and goes straight into the clarify questions. Reach for this before writing the code, not after it. | | `spec-clarify` | Use right after a spec is drafted, or whenever one still has open questions in it - "let's clarify this spec", "answer the open questions before we plan it". Asks one question at a time, each leading with a recommended answer you can accept by saying yes, and writes every answer into the spec - including a deliberate "decide that later", which is an answer and gets recorded as one. Planning and building refuse to start until this reaches zero open questions. | | `spec-impact` | Use before changing how something already works - "what breaks if we change the refund window?", "who else depends on this before I touch it?". Finds everything the change ripples to across other capability specs, decision records and code, so the change does not land having updated only the obvious file. | | `spec-update` | Use when behaviour is about to change and the spec needs to say how it will work afterwards, before the code moves - "we're changing how cancellations work, spec it first", "this branch changes X, make the spec match". On a branch the spec is the target and the git diff is the delta; updates every affected spec, not only the one that came to mind. | ## Planning and doing the work The scaffolding between a settled spec and merged code. Everything these produce is deliberately temporary and removed when the work closes. | Skill | When to reach for it | |---|---| | `spec-plan` | Use when a spec is settled and the question becomes how to build it - "how would we do this?", "what is the approach?". Produces the implementation plan, and refuses a spec that still has open questions rather than planning around them. | | `spec-tasks` | Use once a plan exists and it is time to turn it into ordered, checkable steps - "break the plan into tasks", "what do we build first, and in what order?". Groups tasks by requirement so each slice can be built and tested on its own, with the tests the repo's testing decision calls for. | | `spec-implement` | Use when the tasks exist and it is time to build - "go ahead", "start on it", "implement this". Executes them in order, tests before the code they cover, one phase at a time. | ## Closing the work The step most loops skip. What was learned goes back into the documents before it is lost, rather than into a summary nobody reads again. | Skill | When to reach for it | |---|---| | `spec-reconcile` | Use when a change is finished, before opening the pull request - "I think that's done". Makes the spec, the code and the tests agree, resolves any drift rather than merging around it, and deletes the plan and task scaffolding the work no longer needs. | | `pre-pr-review` | Use before pushing a branch or opening a pull request - "is this ready?", "can I push?". Runs the repo's local checks, then reads the diff as if someone else wrote it, and fixes what it finds first. A review after the push is a review of something already published. | | `add-to-backlog` | Use when work surfaces that does not belong to this change - a bug mentioned in passing ("btw the export is broken"), "we should fix that too", "park it", "not now but do not lose it". Files one well-formed row with its source, the role that must act and what done looks like, ordered against what is already there, without interrupting what you were doing. This adds to the backlog and never reads it back: "show me the backlog" is `show-backlog`. | | `record-run` | Use at the end of an align-to-standards run, success or failure - offers to record the session as validation evidence for the human-prompting corpus (prompts.md + a scored runs/*.json file), at one of two consent levels, never sent without a per-item yes. | ## Running the cadence For a team that commits to work in periods and has to answer when things will land. Optional - a solo repo can run the whole loop above without ever opening a sprint. | Skill | When to reach for it | |---|---| | `sprint-open` | Use when a team is picking up work for the next stretch - "let's start a sprint", "what are we doing this month", "pull the top three payment items into a sprint". Creates the sprint with its goal and agreed end date, and moves the chosen intents out of the backlog pool so each one lives in exactly one place. Also owns reading an open sprint back as a status board ("how is the dispatch sprint going?") and mid-sprint edits - moving a status, reassigning a holder - that happen between opening and closing. | | `sprint-close` | Use when a stretch of work ends - "close the sprint", "the sprint is over", "we shipped what we were going to". Checks each intent against its definition of done, returns what did not finish to the backlog, and records the one measurement of the sprint that cannot be recovered afterwards. | | `timeline-update` | Use when someone asks when work will land - "when does billing ship?", "are we on track?", "what does the next quarter look like?", "update the timeline". Reads every sprint, derives throughput from the closed ones, and projects the open sprints and the backlog - labelling every number as measured or estimated, and giving no date at all when the evidence supports none. | ## Seeing where things stand Reading the state the repository already records, rather than summarising it again by hand. Nothing here writes anything. | Skill | When to reach for it | |---|---| | `show-backlog` | Use when someone asks what the work state IS rather than asking to change it - "show me the backlog", "what is in the pool", "what are we working on", "where do things stand", "what is left" - in whatever language they ask it. Builds the repository's dashboard and hands back the page and the headline numbers, instead of retyping the backlog file into chat. Filing new work is not this - `add-to-backlog` owns that. | ## Staying on the standard The standard is living, so a repo that adopted it once has to be able to move with it. | Skill | When to reach for it | |---|---| | `update-to-latest` | Use when someone wants to move to a newer version of the standard - "update me to the latest", "bump the standard", "what changed since we adopted?". Applies only the delta between the tree this repo last aligned to and latest, adapted to this repo and preserving its recorded deviations - never a re-scaffold. | ## Moving a repo onto the standard These live in this repository and are **never** copied into an adopted repo - they run *from* here, against somebody else's tree, and one of them runs before the target repo exists. Finding one inside an adopted repo is a hand-copy mistake, and `self-verify` warns about it. | Skill | When to reach for it | |---|---| | `align-to-standards` | The single entry point for moving any repo onto the standard. Opens with an intake (step 0) - measure the repo's state, then one short question round (intent, technology + Layer 2 consent, appetite, plan-only vs execute) - then routes by target state - an empty repo to the greenfield phase, an existing unpinned repo to assessment-first onboarding, a pinned repo to update-to-latest or a stack add - and reconciles the repo against the shipped tree in payoff-ordered waves until drift 0. Never blind-copy; reconcile - copy-class artifacts land verbatim, merge/fill-class are adapted (the manifest's adapt classes). | ## If your agent is not Claude Code The procedures are markdown, not a Claude feature. `.claude/skills/` is where Claude Code looks; another agent reads the same files from wherever it looks. The port is a path, not a rewrite - see [`.claude/skills/`](tree/claude-skills.md).