/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.14"

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.

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.

• Before declaring something missing, broaden the search — "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.

Grill to resolve every branch

After gathering and code-verifying, **grill** the user — interview relentlessly, never guessing what they could clarify — to close every remaining decision:

• One question at a time, each with your recommended answer, worded via

`explain-in-simple-language` when available.

• If any part of a question is answerable from the codebase, explore it rather than ask — never

bundle a code-answerable sub-question into a grill. "Which name, type, shape, or pattern fits?" is code-answerable: match the closest existing analogue, and let that verified convention outrank the ticket's contrary suggestion. Grill only on what genuinely remains (product intent, cross-task timing).

• Walk each branch of the decision tree, resolving dependencies between decisions, until there is

shared understanding and no open branch that blocks implementation.

Separate two kinds of uncertainty:

• **Blocking** — implementation can't proceed without it (a contradiction, a missing referenced

file). Resolve during grilling, before writing the file.

• **Non-blocking** — a reasonable default exists but a human should confirm. Record under Open

questions with your tentative answer.

"Already exists" / "reuse X" is a directive

When the ticket says a capability exists or names something to reuse, find what's *behind* it (the service method, query, SP it calls) and anchor the requirement on the smallest extension — relax a parameter, widen a filter, lift a guard. "Not an exact match" doesn't license a net-new build: reuse-vs-build-new is a **blocking** question for the user, never a silent default.

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. 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 — 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.

Output: the REQU