Jira ticket readyup

jira-ticket-readyup

Turn a sparse Jira backlog ticket into a fully-structured "ready for refinement" document by gathering incident context, applying the standard template, and validating the output.

When to Use This Skill

Use jira-ticket-readyup when:

• User asks to "ready up" or "prepare for refinement" one or more Jira tickets
• A ticket exists but lacks Context, Conditions of Satisfaction, or Acceptance Criteria
• User wants to promote a follow-up ticket (spawned from an incident) into a proper backlog item

Do NOT use for:

• Creating new Jira tickets from scratch (use Jira MCP tools directly)
• Tickets that are already in "Ready for Refinement" status with full descriptions

What a Good Ticket Looks Like

A ticket is "ready for refinement" when it has all four sections:

Section	Purpose
Context	Background on the service, current behaviour, and why it matters
Conditions of Satisfaction	MUST / SHOULD / COULD requirements
Acceptance Criteria	Specific, testable conditions that define "done"
Supporting Information	Links to repos, files, and related tickets

The reference example ticket should be supplied by the user when invoking this skill (a ticket already in "Ready for Refinement" status in their Jira project).

Step-by-Step Workflow

Step 1 — Read the YAML template

MANDATORY before generating any output:

# Always read this first — it defines the required fields and comments
skills/project-mgmt/issue-tracker-toolkit/jira-ticket-readyup/assets/templates/ready-for-refinement.yaml

Do NOT generate a ticket data file without loading this template.

Step 2 — Gather context from Jira

For each ticket to ready up:

1. Fetch the ticket itself:

   jira_get_issue(issue_key="PROJ-NNN", fields="summary,description,status,issuetype,issuelinks")
   

2. Fetch every linked incident (look for issuelinks with type "Follow-up"):

   jira_get_issue(issue_key="INC-NNN", fields="summary,description,comment")
   

   Comments on the incident ticket contain the investigation findings — read them all.

3. Extract from the incident:

   • Root cause
   • Service/component affected
   • Evidence (CloudWatch alarms, log errors, X-Ray traces)
   • Who investigated and what they concluded
   • Any proposed solution or follow-up actions already noted

Step 3 — Populate the YAML data file

Create a data file at the output path using the template. The output path convention is:

<journal-dir>/YYYY/MM/YYYY-MM-DD-PROJ-NNN-ready-for-refinement.yaml

Use your judgment to synthesise context from all available sources — the ticket description, linked incident comments, and any other information gathered in Step 2. The goal is a coherent narrative that lets a developer pick up the ticket cold and understand what needs to be done and why.

Key constraints:

• Never leave a required field empty or as the placeholder ""
• conditions_of_satisfaction.must must have at least one item
• acceptance_criteria must have at least two specific, testable items
• If no incident is linked, derive all context from the ticket description alone

Step 4 — Validate the YAML

bun run skills/project-mgmt/issue-tracker-toolkit/jira-ticket-readyup/scripts/validate-ticket.ts \
  <path-to-ticket-data.yaml>

Fix any reported errors before proceeding to markdown generation.

Prerequisite: bun must be available (which bun).

Step 5 — Generate the markdown output

Create the markdown file at:

<journal-dir>/YYYY/MM/YYYY-MM-DD-PROJ-NNN-ready-for-refinement.md

Use this structure exactly:

# <Summary> — <Ticket Key>

**Type:** <Bug|Feature|Maintenance|Investigation>
**Linked Incident:** [<INC-NNN>](<jira-url>)  *(omit if none)*

## Context

<background paragraph>

<current behaviour paragraph>

**Key implications:**

- <implication 1>
- <implication 2>

## Conditions of Satisfaction

- [ ] **MUST** <requirement>
- [ ] **MUST** <requirement>
- [ ] **SHOULD** <requirement>
- [ ] **COULD** <requirement>

## Acceptance Criteria

- <criterion 1>
- <criterion 2>

## Supporting Information

- [<Repo name>](<url>)
- [<File path>](<url>) — <description>
- [<INC-NNN>](<url>) — <incident summary>

Step 6 — Validate the markdown

bun run skills/project-mgmt/issue-tracker-toolkit/jira-ticket-readyup/scripts/validate-ticket.ts \
  <path-to-ticket-data.yaml> \
  --markdown <path-to-ticket-output.md>

Step 7 — Report to user

When complete, report:

• Path to the YAML data file
• Path to the markdown output file
• Validation result (OK or errors)
• A one-paragraph summary of what the ticket is about

Output File Location

Store outputs in the journal directory:

<journal-dir>/YYYY/MM/
  YYYY-MM-DD-PROJ-NNN-ready-for-refinement.yaml   ← data file (validated source)
  YYYY-MM-DD-PROJ-NNN-ready-for-refinement.md     ← markdown output

Use today's date for YYYY-MM-DD. The journal-dir is the current project root.

Template Schema Reference

The canonical template is at:

skills/project-mgmt/issue-tracker-toolkit/jira-ticket-readyup/assets/templates/ready-for-refinement.yaml

The JSON schema is at:

skills/project-mgmt/issue-tracker-toolkit/jira-ticket-readyup/assets/schemas/ready-for-refinement.schema.json

Anti-Patterns

NEVER generate the ticket data file without reading the YAML template first

WHY: The template defines required fields and their expected format. Skipping it produces output that fails schema validation or omits required sections. ❌ BAD: Writing context.background directly without consulting the template structure. ✅ GOOD: Run Step 1 (read template) every time, even for the second ticket in a session.

NEVER skip fetching incident comments

WHY: The root cause, evidence, and proposed fix almost always appear in comments, not in the incident description. Skipping comments produces shallow context and vague acceptance criteria. ❌ BAD: Fetching only INC-NNN description, ignoring comments. ✅ GOOD: Fetch all comments via jira_get_issue(fields="comment") and read every one.

NEVER proceed to markdown generation if YAML validation fails

WHY: A broken YAML file silently propagates errors into the markdown and downstream tooling. The validate-ticket.ts script exists precisely to catch these before they spread. ❌ BAD: Continuing to generate markdown after a schema validation error, assuming it "looks fine". ✅ GOOD: Fix every validation error reported by validate-ticket.ts before calling Step 5.

NEVER write conditions of satisfaction as vague aspirations

WHY: "Improve reliability" is untestable. Refinement sessions get blocked when teams cannot determine whether a requirement is met. ❌ BAD: MUST make the service more robust. ✅ GOOD: MUST return HTTP 400 with error code INVALID_POSTAL_CODE when input fails the expected validation pattern.

References

Topic	Reference	When to Use
YAML field guide	references/yaml-field-guide.md	When unsure what a template field expects
YAML template	assets/templates/ready-for-refinement.yaml	Step 1 of every workflow run
JSON schema	assets/schemas/ready-for-refinement.schema.json	Understand validation rules
Validation script	scripts/validate-ticket.ts	Steps 4 and 6 of the workflow