/refine-ticket

name: refine-ticket
description: Refine a development ticket — or brainstorm a raw idea — into a validated, self-contained REQUIREMENTS document — the "what", verified against the codebase. Invoke manually only.
license: MIT
metadata:
  version: "1.22"

Refine ticket

The **Refine** phase of Refine → Plan → Act: turn a raw ticket — or an idea to brainstorm — into a validated requirements document a fresh session can plan from. Analysis only — it defines **what** must be true when the work is done, never **how** to build it, and never touches code.

An idea is a ticket that doesn't exist yet: treat the user's words as the ticket text, and grill to shape the idea itself — goal, in vs out of scope — before closing the branches that block implementation.

Input

A `.TICKET.md` path, a ticket URL or bare id, or an idea in words. When the harness has subagents and fetch-ticket is available (`../fetch-ticket/SKILL.md` beside this skill), a URL or id is fetched first by a subagent per fetch-ticket's [delegate.md](../fetch-ticket/delegate.md) — one ticket per run; several → point at a fetch session instead, which handles sets. A non-empty warn list stops for one question: supply the files now (`/attach-to-ticket` when available; answered by running it → resume with the supplied files once it reports) or refine without them. The fetched file is then the local ticket file. No subagents, or fetch-ticket not available → read the ticket from its tracker and refine with no local ticket file.

An existing `.REQUIREMENTS.md` (a re-run, e.g. once a blocking answer is in): read it and its ticket file (`.REQUIREMENTS` → `.TICKET`, or its latest `-vN` re-fetch, file or directory) first — none for a tracker ticket → re-read it there, asking for its URL or id when the file doesn't name it; grill only on what changed since, and update it in place.

What, not how — but verified against the code

You cannot define the "what" in a vacuum. Every requirement must be checked against the **actual code, config, and design** — a ticket may be stale, ambiguous, contradicted by the codebase, or depend on upstream work that isn't implemented yet (e.g. a prerequisite ticket still open). Reading the code here is for *validating* requirements, not for designing the solution.

Golden rule: never guess — ask

• Anything determinable by reading the code, resolve by reading the code — never ask the user about

it.

• Anything *not* determinable from ticket + code, ask — never fill the gap with a plausible

assumption.

• Local environment state (config files, DB contents, env vars) describes only the machine it's on

— never assume it matches the environment where the reported behaviour occurred; ask the user to confirm such values.

• Treat "this probably works like X" as a question, not a fact. Keep "I confirmed X", "the ticket

claims X", and "I assume X" distinct; the latter two never become the first without evidence. A decision marked settled by a ticket or design carries the quote that settles it; no quote, still open.

• Before declaring something missing, unique or unhandled ("no X does Y", "X's only user", "the

existing ones don't cover Z"), search every repo the feature spans for the concept — "not found under the name the ticket used" is not "not present".

• Verify both sides of an integration: if a requirement relies on another layer behaving a certain

way, open that layer and confirm it.

Reconcile against the design when one is referenced

When a ticket points at a design (mockup, screenshot, prototype, design-tool link), that design is part of the spec. Visual decisions made without seeing it lock in wrong defaults.

• If you cannot actually see the referenced design, ask for it before proceeding. A link you can't

render is not a design you've read. Prefer a copy already saved with the ticket over re-fetching.

• Once you can see it, treat visual specifics as contract-level: currency, date, and number

formatting, empty and error states, label wording, spacing, alignment, iconography. The default for "is this in the design?" is match the design, not do the minimum.

• Any visual choice you'd otherwise make blind is an Open question, never silently defaulted.

Read relevant related tickets — context, not scope

When the ticket references others that matter to it (BE/FE counterparts, dependencies, follow-ups), read them too — they complete the picture and sharpen how this ticket's requirements are meant. A `## Ticket set` section in the ticket file lists locally fetched siblings: read every linked `.TICKET.md` before grilling; for tracker-only references, judge relevance before fetching, then fetch one the way Input does. What a sibling supplies — execution order, contracts it owns, superseded-spec notes — is context only, never requirements: scope stays this ticket's, and anything a sibling suggests changing is a question for the user, never a silent scope change.

A prior ticket review is leads, never facts

Unless one was passed in, look for a `.TICKET-REVIEW.md` next to the ticket or in its set directory, preferring the one whose base matches the ticket file's `-vN` base — an earlier session's triage; say which one you use, or that none exists. Challenge and re-verify everything in it before relying on it (its citations make that cheap). Its shipped questions are blocking items: grill first whether the owner answered. The defaults it assumed for dropped cheap details are decisions to close here — grilled or recorded as Open questions, never adopted silently. Handoffs are out-of-scope dependencies; verdict and walkthrough are context only. The ticket file and the code always win; a review older than the ticket file has likely been overtaken — say so.

Existing requirements

Before the first grill question, look for this ticket's requirements: the `.REQUIREMENTS.md` at the target path (Location below) or, for a ticket with `-vN` versions and none under its own base, th