Refine Ticket

---
name: refine-ticket
description: Create or refine a Linear ticket until it has clearly defined test cases and a concrete implementation plan. Prepares tickets so an agent can implement them independently.
---

Refine a Linear ticket so it is unambiguous and ready for autonomous implementation and testing.

## Input

The user may provide:
- A ticket ID (e.g. `OPE-12`) — load that existing ticket
- No ID — create a new ticket (ask the user for a title and one-sentence description first)

---

## Step 1 — Load or create the ticket

**If a ticket ID was provided:**
- Use the Linear MCP to fetch the issue: title, description, status, labels, priority, comments
- Print a one-paragraph summary of what was found and what is currently missing

**If no ticket ID was provided:**
- Ask the user for: title and a short description
- Use the Linear MCP to create a draft issue in the OMC project
- Treat it as an existing ticket from this point forward

---

## Step 2 — Evaluate completeness

Score the ticket against this checklist. A ticket is **ready** only when every item is satisfied:

**Context & Goal**
- [ ] Clear problem statement or user story ("As X, I want Y so that Z" — or equivalent)
- [ ] Explicit acceptance criteria

**Implementation Plan**
- [ ] Approach described: which files/modules/components change, and how
- [ ] Key design decisions called out (e.g. new abstraction vs. extend existing)
- [ ] Dependencies or blockers identified
- [ ] Edge cases and error handling noted

**Test Cases**
- [ ] At least one happy-path test with concrete input → expected output
- [ ] At least one edge-case or error-path test
- [ ] Testing level noted: unit, integration, or e2e — whichever applies

Print the checklist with checkmarks for what is present and gaps clearly flagged.

---

## Step 3 — Enter plan mode to design the implementation

Use `EnterPlanMode` to think through the full implementation before writing anything:

1. Read `CLAUDE.md` for project conventions and architecture
2. Explore relevant existing code (use Glob/Grep/Read as needed)
3. Design the implementation:
   - Which files to create or modify
   - What the public interface / API looks like
   - How data flows through the system
   - What can go wrong and how errors are handled
4. Design the test suite:
   - Write out each test case with explicit setup, inputs, and expected outputs
   - Cover the happy path, edge cases, and error conditions
   - Note which test framework and style matches the existing codebase

Stay in plan mode until you have a complete, concrete, unambiguous plan with no open questions.

Exit plan mode (`ExitPlanMode`) once the plan is approved.

---

## Step 4 — Rewrite the ticket description

Update the ticket in Linear with the following structured description. Replace every placeholder with real, specific content — no vague language.

Goal

<One-paragraph problem statement. What is broken or missing, why it matters, and what success looks like.>

Acceptance Criteria

• <specific, verifiable criterion>
• <specific, verifiable criterion>
• ...

Implementation Plan

Approach

---

## Step 5 — Validate and iterate

Re-run the checklist from Step 2 against the updated description. If any item is still unmet:
- Identify specifically what is still missing
- Return to Step 3 (plan mode) to fill the gap
- Update the ticket again

Repeat until every checklist item passes.

---

## Step 6 — Final report

Print:
- The Linear ticket URL
- A brief diff of what was added or changed vs. the original
- Confirmation: "This ticket is ready for autonomous implementation."