ticket-authoring

Files (9)

• SKILL.md
• bug-template.md · references/
• capitalization-guide.md · references/
• definition-of-ready-checklist.md · references/
• epic-template.md · references/
• example-bug-and-story.md · references/
• spike-template.md · references/
• story-template.md · references/
• task-template.md · references/

SKILL.md (first lines)

# Ticket Authoring

Turn specs, bug reports, and loose requests into work items someone can pull and start without asking a question. Tracker-agnostic: works in Jira, Linear, GitHub Issues, or your tracker of choice.

---

## When to use

- Turning a PRD or spec into a set of tickets
- Filing a bug that someone else will fix
- Writing a user story with checkable acceptance criteria
- Scoping a spike so it ends in a decision, not a shrug
- Opening an epic with a goal, a metric, and a way to kill it
- Auditing a backlog for tickets that are not ready to pull
- Tagging work items with a capitalization stage for finance

## When NOT to use

- Writing the PRD or spec itself (use `pm-spec-writing`)
- Deciding what ships this quarter (use `roadmap-planning`)
- Running sprint ceremonies or measuring the team (use `sprint-operations`)
- Writing up what went wrong after the fact (use `after-action-report`)
- Handing a whole plan to a coding agent to execute unattended (use `dispatch-authoring`)

---

## Required inputs

- The source material: a spec, a bug description, a request, or a conversation
- The ticket type, or enough context to pick one
- The tracker's field set, if it has required custom fields
- The parent epic or story, if one exists
- The capitalization policy, if the team capitalizes software development

If the source is vague, ask before writing. A ticket written around a guess becomes a second ticket later.

---

## The framework: five types, one definition of ready each

A ticket is ready when the person who pulls it can start work without a question. Each type has its own required fields, its own attachments, and its own done test. A field left blank is a question someone will ask in the middle of the sprint.

Every type shares a base: title, type, owner, parent link, labels, and capitalization stage.

### Bug

A bug ticket proves the defect exists and defines how to prove it is gone.

- **Title.** `[area] [symptom] when [trigger]`. Example: "Checkout: total shows $0.00 when a promo code is removed."
- **Repro steps.** Numbered. Each step is one action. Someone who has never seen the product can follow them.
- **Environment.** Build or version, browser or device, account type, data state.
- **Observed vs expected.** Two separate lines. Never one sentence with "but."
- **Current test result.** The test that fails today, or "no test covers this."
- **Severity and priority.** Two fields. Severity is how bad the defect is. Priority is when the team fixes it.
- **Regression risk.** What else touches this code path.
- **QA notes.** Edge cases to check beyond the repro.
- **Fix verification method.** The specific test that proves the fix, by name or by steps.
- **Expected test result after fix.** What passing looks like.

Done test: the named verification passes, and the repro steps no longer reproduce.

### Task

A task is a unit of build work with no direct user-facing outcome of its own.

- Task spec: what changes, in plain language
- Parent story link, if any
- **Touches list:** files, services, flags, and tables in scope. This lets an executor scope the change and lets a reviewer spot drift.
- Estimate
- Screenshots of the affected area
- QA notes
- Definition of done

Done test: every item in the definition of done is checked, and nothing outside the touches list changed without a note.

### Story

A story delivers one user-visible outcome.

- User story statement: "As a [user], I want [action], so that [outcome]."
- Link to the PRD or spec. If none exists, write one first with `pm-spec-writing`.
- Acceptance criteria in checkable form (Given, When, Then, or a checkbox list with observable outcomes)
- Explicit non-goals
- Wireframe or mockup screenshots, if any
- Analytics events to emit, with names and properties
- Feature flag, if any
- QA notes

Done test: every acceptance criterion is checked by someone other than the author.

### Spike

A spike buys information with a fixed amount of time.

- The question being answered, as one sentence ending in a question mark
- Timebox, in days
- Exit criteria: what counts as an answer
- Resources, services, and platforms to evaluate
- Competitor examples, if any
- Required output artifact: a decision memo with a recommendation. Never "we looked into it."

Done test: the memo exists, names a recommendation, and lands before the timebox ends. If time runs out, the memo says what is still unknown.

### Epic

An epic groups work toward one outcome and carries the business case.

- Date opened
- Goal, in one sentence
- Success metric, with baseline and target
- Kill criteria: the signal that ends the epic early
- Owner, one name
- Roadmap fitment: which quarter, which objective (see `roadmap-planning` and `okr-design`)
- Notes
- Capitalization stage, if the work is capitalizable

Done test: the success metric is measured, or the kill criteria fired and the epic closed on purpose.

### Severity is not priority

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills