Issue Writing Skill

Issue Writing Skill

This skill guides the creation of well-structured, actionable Jira issues that any developer or AI can pick up and execute independently.

When to Use

Apply this skill when:

• Writing or drafting issue descriptions
• Defining acceptance criteria for tasks
• Breaking down features into Subtasks
• Reviewing existing issues for clarity
• Users ask how to document requirements

Issue Structure: Parent Stories

h2. IMPORTANT: Jira Issue Discipline
[Standard discipline rules]

---

h2. Problem
[1-2 sentences: Why does this feature need to exist?]

h2. Solution
[1-2 sentences: What are we building to solve this?]

h2. High-Level Implementation
[Bullet points: Key technical decisions, patterns]

h2. Codebase Investigation Findings
[What patterns to follow, similar features, code locations]

h2. Out of Scope / Deferred
[Explicitly list what we're NOT doing]

Issue Structure: Subtasks

h2. Objective
[1-2 sentences: What specific thing needs to be done?]

h2. Acceptance Criteria
* [Specific, testable criterion 1]
* [Specific, testable criterion 2]
* [Specific, testable criterion 3]

h2. Implementation Notes
* Relevant files: [paths]
* Patterns to follow: [reference]
* Dependencies: [other Subtasks]

Writing Good Acceptance Criteria (SMART)

• Specific: Clear about what exactly needs to happen
• Measurable: Can objectively verify if it's done
• Achievable: Within scope of this single Subtask
• Relevant: Directly related to the objective
• Testable: Can be validated by running/​checking

Jira Formatting Notes

Jira uses Wiki markup, not Markdown:

• Headers: h1., h2., h3.
• Bold: *bold*
• Bullets: * or -
• Numbered list: #
• Code: {{inline}} or {code}block{code}
• Links: [title|url]

Anti-Patterns to Avoid

• Vague objectives: "Improve the dashboard"
• Missing acceptance criteria: Assuming it's obvious
• Implementation prescription: Over-specifying the how
• Hidden dependencies: Not mentioning blockers
• Scope creep: Adding "nice to haves"

Remember: A good issue can be executed by anyone who reads it.