refine-ticket
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.
eai-org · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add eai-org/agent-toolkit --skill refine-ticketAbout this skill
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.13"
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.
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 REQUIREMENTS file
Must stand alone for a fresh session wi
Read the complete source ↗