| name | ticket-refiner |
| description | Assess whether a Jira ticket is READY for team refinement and estimation, producing a READY / NEEDS WORK / SPIKE REQUIRED verdict in ~/git/defra/trade-imports-animals-workspace/workareas/ticket-refinement/EUDPA-X/review.md. Use when the user asks to validate a ticket's description, AC, repos, dependencies and sizing BEFORE refinement (triggers: "is ticket EUDPA-X ready", "pre-refinement", "refine EUDPA-X", "refinement check"). NOT for authoring brand-new tickets (use the ticket-creator skill: "assess existing ticket readiness" vs "create new"). NOT for planning or implementing an already-refined ticket (use the ticket skill: "assess readiness" vs "plan/implement"). |
| context | fork |
| allowed-tools | ["Bash","Read","Glob","Edit","Write"] |
| argument-hint | EUDPA-XXXXX |
Role: Review tickets before refinement to assess readiness for team
estimation. Verdict is one of READY, NEEDS WORK, or SPIKE REQUIRED.
Works in complement with the ticket-creator skill — tickets created
there flow into refinement here. Both skills share a single source of
truth for "what makes a good EUDPA ticket":
~/git/defra/trade-imports-animals-workspace/docs/best-practices/jira/ticket-conventions.md — EUDPA ticket conventions (description structure, AC quality, parent/epic, labels).~/git/defra/trade-imports-animals-workspace/docs/best-practices/gds/writing.md — GDS plain-English writing standard.
Read both at session start; assess against the same standards
ticket-creator authors to.
Path conventions
Cross-workspace paths use the literal home-relative form —
~/git/defra/trade-imports-animals-workspace/tools/<domain>/,
~/git/defra/trade-imports-animals-workspace/docs/best-practices/,
~/git/defra/trade-imports-animals-workspace/workareas/. Bash expands ~ to
your home directory automatically. Scripts under tools/ hardcode the workspace path as
$HOME/git/defra/trade-imports-animals-workspace/... — no env var needed.
Skill-internal references stay relative
(references/<NAME>.md, assets/<NAME>.md); subagents are addressed
by name via the Task tool.
Bash call hygiene — one command per Bash call. Full rule table: docs/agent-skills.md → "Bash call hygiene".
When to use
Triggers: "is ticket EUDPA-X ready", "pre-refinement", "refine EUDPA-X",
"refinement check". NOT for authoring brand-new tickets — use the
ticket-creator skill. NOT for planning/implementing an already-refined
ticket — use the ticket skill.
Subagents
This skill spawns no subagents and has no references/. The full flow is
in this file.
Prerequisites
Authenticate to Jira before fetching tickets:
~/git/defra/trade-imports-animals-workspace/tools/jira/auth.sh
(Or the umbrella ~/git/defra/trade-imports-animals-workspace/tools/auth.sh covering Jira +
Confluence + GitHub.)
Ready When Team Can
- Understand what needs to be done
- Identify repos and components
- Estimate effort
- Identify risks and dependencies
Workflow
- Prepare workspace (one helper call — fetches Jira ticket + comments + Confluence links, seeds meta JSON, stubs
review.md)
- Explore codebase (read directly from
~/git/defra/trade-imports-animals-workspace/repos/<repo>/)
- Assess readiness
- Write review
- Finalise verdict
Step 1: Prepare Workspace
Read the shared conventions docs once at session start — they are the
standards you assess against:
- Read
~/git/defra/trade-imports-animals-workspace/docs/best-practices/jira/ticket-conventions.md — these are the standards you assess against.
- Read
~/git/defra/trade-imports-animals-workspace/docs/best-practices/gds/writing.md — GDS plain-English writing rules.
Then prepare the workarea:
~/git/defra/trade-imports-animals-workspace/tools/refine/prepare-refinement.sh EUDPA-XXXXX
This produces, under ~/git/defra/trade-imports-animals-workspace/workareas/ticket-refinement/EUDPA-XXXXX/:
ticket.md — summary, description, AC, comments, Confluence references (from Jira JSON).refinement-meta.json — ticket fields + verdict: null (finalised in Step 5)review.md — pre-populated stub from assets/refinement-template.md
Read ticket.md to internalise the summary, AC and comments. The helper has already substituted [Date], [Ticket summary], type and priority into the review stub.
Step 2: Explore Codebase
The workspace already has the canonical clones at
~/git/defra/trade-imports-animals-workspace/repos/<repo>/. Read directly from those
working trees when you need to peek at code — do not clone anywhere.
See the workspace CLAUDE.md repo map for the authoritative repo list
(trade-imports-animals-frontend, -backend, -admin, -tests,
trade-imports-stub, trade-imports-reference-data).
Investigate
Features: Where does it fit? Patterns to follow? Similar features?
Bugs: Locate code? Current behaviour? Cause?
Technical: Current state? What changes? Dependencies?
Step 3: Assess Readiness
Judge each check below against the conventions read in Step 1:
description structure, AC quality, parent/epic, label conformance
(ticket-conventions.md) and GDS writing style (gds/writing.md).
Description Clarity
| Check | Question |
|---|
| Context | Is the "why" explained? |
| Scope | In/out of scope clear? |
| Specificity | Concrete details? |
Acceptance Criteria
| Check | Question |
|---|
| Present | Are there AC? |
| Testable | Can each be verified? |
| Complete | Cover full scope? |
| Unambiguous | One interpretation? |
Technical Clarity
| Check | Question |
|---|
| Repos | Affected repos identified? |
| Approach | Implementation understood? |
| Dependencies | Blockers identified? |
| Risks | Technical risks called out? |
Estimability
| Check | Question |
|---|
| Sized | Fits in a sprint? |
| Unknowns | Too many to estimate? |
| Spike | Investigation first? |
Step 4: Write Review
prepare-refinement.sh already stubbed
~/git/defra/trade-imports-animals-workspace/workareas/ticket-refinement/EUDPA-XXXXX/review.md
from assets/refinement-template.md. Fill each section in place from
Steps 1-3 — ## Description Summary, ## Acceptance Criteria,
## Codebase Investigation, ## Readiness Assessment,
## Questions for Refinement, ## Suggested Improvements, and the
trailing ## Verdict block.
Step 5: Finalise Verdict
After filling review.md, record the verdict on the meta JSON:
~/git/defra/trade-imports-animals-workspace/tools/refine/refine-finalize.sh EUDPA-XXXXX --verdict READY --reason "Clear AC, repos identified"
Verdict must be one of READY, NEEDS WORK, SPIKE REQUIRED (the
helper rejects anything else). The --reason is optional but
recommended.
Verdict Guidelines
| Verdict | Criteria |
|---|
| READY | Clear description, testable AC, team can estimate |
| NEEDS WORK | Missing info needed before refinement |
| SPIKE REQUIRED | Too many unknowns - needs investigation first |
Next-step prose by verdict:
READY — completion output should explicitly state
"next: plan EUDPA-XXXXX via the ticket skill" so the user
knows where to take the now-refined ticket.NEEDS WORK — if the ticket was freshly created via
ticket-creator, point the user back at the relevant section of
docs/best-practices/jira/ticket-conventions.md (or gds/writing.md)
that explains what's missing. Treat the conventions doc as the
single source of truth — don't invent ad-hoc rules.SPIKE REQUIRED — name the specific unknowns the spike should
investigate; do not just say "unknowns".
Completion Output
Refinement review complete for EUDPA-XXXXX.
Verdict: [VERDICT]
Key findings:
- [Finding]
Questions for refinement:
- [Question]
Review available at: ~/git/defra/trade-imports-animals-workspace/workareas/ticket-refinement/EUDPA-XXXXX/review.md
