# Refine Ticket

> Iteratively harden a Jira automation ticket against a "bulletproof" rubric — grounded in existing automation, app docs, and user-supplied sources — then write the refined acceptance criteria back to the ticket on approval, so /from-issue has nothing left to guess.

- Skill: `diegocortes15/refine-ticket` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add diegocortes15/refine-ticket`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegocortes15/refine-ticket/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Diegocortes15 (https://skillmd.com/u/diegocortes15)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/diegocortes15/refine-ticket

---


# refine-ticket

Given a Jira issue key (e.g. `SW-123`), this skill reads the ticket via the Atlassian MCP, scores it against the refinement rubric, and loops — auto-resolving gaps from existing automation + docs and asking you (or a source you point it at) for the rest — until the ticket is unambiguous. On your approval it writes a `## Refined Acceptance Criteria` block back to the ticket. It does NOT generate tests; run `/from-issue` after. See ADR-0013.

## How to use it

Tell Claude what you want:

> Use the refine-ticket skill on SW-123.

Or to preview without writing to Jira:

> Use the refine-ticket skill on SW-123 with dry-run.

During the loop, when asked about a gap you can either answer directly or point the skill at a source ("it's in Confluence page X", a URL, a doc path). The skill ingests it and continues. It does NOT inspect a running app — it's shift-left, so it works even before the feature is built. It stops when the ticket has no open gaps, then asks before writing anything back.

## Workflow

The full procedural workflow is in [`references/workflow.md`](references/workflow.md). Read that file before executing the skill.

> **Setup note:** the Atlassian MCP must be connected (OAuth) with **write** scope for the Step 7 description update — defined at project scope in `.mcp.json`. Its read + write tools are pre-authorized in `allowed-tools` above so the loop doesn't prompt each call. Write-back happens only on your explicit approval (per ADR-0013).

## References

- [`references/workflow.md`](references/workflow.md) — the procedural loop
- [`references/rubric.md`](references/rubric.md) — the "bulletproof" checklist (definition of done)
- [`references/sources.md`](references/sources.md) — source catalog + user-supplied-source protocol
- [`references/writeback-template.md`](references/writeback-template.md) — the `## Refined Acceptance Criteria` block + idempotent-update rule

## Composition

This skill pairs with `/from-issue`: refine first, then generate. It reuses the `/from-issue` skill's `references/bucket-classification.md` and `references/qa-analysis.md` for the rubric's coverage/automatable judgment.

## See also

- `docs/refine-ticket.md` — learning guide with a worked example
- ADR-0008 — why custom skills follow this layout
- [ADR index (origin repo)](https://github.com/Diegocortes15/playwright-ai-framework/tree/main/docs/adr) — rationale for every `ADR-NNNN` cited above. Paths like `docs/…` and `src/…` are relative to that repo, not to this skill.