refine-ticket v1.11A

Immutable. This exact content is served forever at /api/v1/blob/db53964cd19af4fd.

---
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:
  author: Francesco Borzì
  version: "1.11"
---

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

## Output: the REQUIREMENTS file

Must stand alone for a **fresh session** with no memory of this conversation and no access to the
ticket — this is the single most important constraint. No "as discussed", "we agreed", or "see
ticket".

Location:
- If the ticket input is a **local file**, write the REQUIREMENTS file in the **same directory**,
  replacing `.TICKET` with `.REQUIREMENTS` (e.g. `FOO.TICKET.md` → `FOO.REQUIREMENTS.md`); if the
  input doesn't follow that convention, append `.REQUIREMENTS` before `.md`.
- If there is **no local ticket file** (a tracker URL/ID, pasted text), follow the project's
  planning convention for where planning documents live (per the project's or user's rules — don't
  assume a fixed path, ask when not sure). Propose a kebab-case `<slug>` (prefix the tracker id when
  the ticket is bound to one) and the target path, **confirm both with the user**, then write
  `<slug>.REQUIREMENTS.md` there.

Six parts (Verified codebase facts, Overrides, and Open questions may be empty — don't pad):

1. **Context** — 1–3 sentences: the feature, what's in scope, what's out. When the work is only
   a slice of a larger feature, link the big-picture reference (parent story, final-goal/context
   note, design) so the planner sees how it fits; a self-contained task needs none.
2. **Verified codebase facts** — the facts confirmed while validating requirements, recorded so
   the planner builds on them instead of rediscovering: where the relevant code lives, data
   shapes, existing analogues, integration points. Byproduct only — never explore beyond what
   refinement itself needs — and only facts a fresh session would need a search to rediscover.
   Anchor to paths and identifiers; line numbers are hints — they drift. *What is true today*,
   never *how to change it*. When non-empty, open with one line pinning the commit (short hash,
   noting uncommitted changes if the tree is dirty) and absolute date, warning the code may have
   changed since and specifics need re-verifying.
3. **Requirements** — deduplicated functional + technical list. Tag each item with its ticket source
   (e.g. `(Description)`, `(Technical Detail)`, `(AC)`). Group by area when it aids reading. Cite
   the concrete file path / identifier inline wherever a requirement touches code; cite a reused
   pattern as `path:line-range`.
4. **Overrides** — where the ticket says one thing and the requirement says another (ticket is
   stale, wrong, or self-contradictory). Each entry: what the ticket says, what the code/AC shows,
   the resulting requirement.
5. **Open questions** — non-blocking ambiguities, each with your tentative answer and why it's
   non-blocking. Blocking questions never appear here.
6. **Acceptance criteria** — flat, verifiable checklist the implementation must satisfy.

Each requirement is self-contained; user-facing strings that must stay in a given language are
quoted verbatim.

## Boundaries

- Do **not** write an implementation plan or describe "how".
- Do **not** modify any source files. The only file you write is the REQUIREMENTS document.

When done, state — in **project-relative paths** — that the requirements file is ready, then hand
off each next phase as a **single copy-pasteable launch command** — phase-prefixed session name and
prompt combined, so one paste starts the session. Use the launch syntax of the agent tool in use
(vendor-agnostic — `claude` below is only the example), naming the session with the phase prefix
plus the requirements file's slug:

```
claude --name create-manual-test-<slug> "/create-manual-test-instructions <path>.REQUIREMENTS.md"   # QA manual test
claude --name create-plan-<slug> "/create-implementation-plan <path>.REQUIREMENTS.md"               # Plan phase
```

The phase prefix (`create-plan-`, `execute-plan-`, …) keeps the pipeline phases distinguishable in
the session list.

Then offer the plan phase's alternative — clearing the current session instead (vendor-agnostic —
`/clear` below is only the example; use the clear command of the agent tool in use):

OR /clear and run:

```
/create-implementation-plan <path>.REQUIREMENTS.md
```