create-tickets

Create Tickets Skill

Generate engineering tickets from PRDs, feature specs, or task lists. Supports direct creation via Linear MCP or formatted text output.

REQUIRED: every generated ticket must follow the /catalyst-dev:gherkin-ticket standard.

Outcome-first title (<actor> should <outcome> [so that <benefit>], no internal-mechanism jargon,

component as a label not a title prefix) + a body that opens with a plain-English use case

followed by tiered Gherkin acceptance criteria. The legacy [Component] Action: title format below

is superseded — see the updated Title Format and Ticket Body sections.

Quick Start

1. Point me to the source: PRD, feature spec, meeting action items, or describe the work
2. I break it down into well-structured tickets with acceptance criteria
3. Each ticket gets an effort estimate, dependencies, and component label
4. If Linear MCP is connected, I create tickets directly; otherwise, I generate copy-paste text
5. I provide a dependency summary and sprint assignment suggestion

Example: "Create tickets from thoughts/shared/pm/prds/checkout-redesign.md targeting a March 15 launch"

Output: Tickets created in Linear, or saved to thoughts/shared/pm/analyses/[feature]-tickets.md

Time: 15-30 minutes depending on PRD complexity

When to Use This Skill

• Breaking down PRDs into implementation tickets
• Converting feature specs into actionable tasks
• Batch ticket creation from roadmap items
• Generating ticket text for manual entry

Prerequisites

Optional but Recommended:

• Linear MCP configured (for direct ticket creation)

Fallback:

• Generates formatted ticket text for manual copy-paste

Workflow

Step 1: Gather Context

Ask the PM:

1. Source document: PRD, feature spec, or task list?
2. Target system: Linear, or text output?
3. Project/Team: Which project/team should receive tickets?
4. Ticket type: Story, Task, Bug, Epic?
5. Priority level: High, Medium, Low?

Step 2: Analyze Source Material

Read the source document and identify:

• User-facing features (frontend work)
• API/Backend work (backend work)
• Data migrations (data engineering)
• Infrastructure changes (DevOps)
• Testing requirements (QA)
• Documentation needs (docs)

Step 3: Create Ticket Structure

For each ticket, generate:

Title Format (per /catalyst-dev:gherkin-ticket — outcome-first, no [Component] prefix):

<actor> should <outcome> [when <condition>] [so that <benefit>]

The actor is whoever benefits (a user, an operator, the API, the scheduler). The component goes in a Linear label, not the title. Examples:

• Users should be able to save and reload their preferences so settings persist across sessions
• The preferences API should reject an unknown user with a 404 rather than a 500
• Operators should see a preference-selection screen so they can configure defaults without code

Ticket Body (use case first, then tiered Gherkin, then technical detail):

[Short plain-English use case — who benefits and why — so a reader who didn't write it gets oriented.]

​```gherkin
Scenario: <one specific behavior>
  Given <minimum starting state>
  When <the single action>
  Then <observable outcome>
​```
(Tier A = features/bugs full scenarios; Tier B = bugs, `Then` states correct behavior + `# CURRENTLY:`;
Tier C = pure chores, Context/Motivation/Outcome prose instead of a vacuous scenario.)

## Technical notes

[API contracts, data schemas, edge cases — preserved, but BELOW the use case]

## Dependencies

<!-- Documentation only. A real prerequisite MUST also be set as a formal Linear
     blocked_by LINK (see Bulk Creation step 5) — Catalyst does not infer
     dependencies from this prose (CTL-838). -->
- Blocked by: [Other ticket]
- Blocks: [Other ticket]

## Testing Requirements

- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual QA steps

## Resources

- Design: [design link]
- API Spec: [Swagger/OpenAPI]
- Related PRD: [Link]

Step 4: Create or Output Tickets

If Linear MCP available:

Use Linear MCP to create issues directly
Set project, team, priority, labels
Link parent issues and sub-issues
Add components and labels

Fallback - Text Output:

Generate formatted ticket text
Number tickets sequentially
Provide copy-paste instructions

Bulk Creation

When creating 5+ tickets:

1. Create Epic first (if applicable)
2. Group by component (Frontend, Backend, Data, etc.)
3. Order by dependency (foundation tickets first)
4. Add estimates (if PM provides sizing)
5. Link tickets as formal Linear blockers — linearis issues update <ticket> --blocked-by <prereq>

for each TRUE prerequisite (see /catalyst-dev:linearis). Set real blocked_by LINKS; do NOT rely on naming the dependency in the description. Catalyst does not infer dependencies from prose (CTL-838) — a "Blocked by: X" line in the body is documentation only and is never turned into a blocker. Link only genuine must-finish-first work; never link across teams for auto-sequencing (the daemon only works its own team, so a cross-team blocker deadlocks).

Effort Estimation Framework

For each ticket, include an effort estimate using T-shirt sizing:

| Size | Time | Description | Example | | ------ | --------- | ----------------------------------------- | ----------------------------------- | | XS | <2 hours | Config change, copy update, simple fix | Update error message text | | S | Half day | Single-file change, straightforward logic | Add input validation to a form | | M | 1-2 days | Multi-file change, moderate complexity | Build a new API endpoint with tests | | L | 3-5 days | Cross-component work, integration needed | Build complete CRUD feature with UI | | XL | 1-2 weeks | Large scope, multiple systems involved | New authentication system |

Estimation rules:

• If the PM provides estimates, use them. If not, suggest one based on typical complexity for the work type.
• Always flag XL tickets as candidates for splitting. Suggest how to break them down: "This XL ticket could be split into [DB migration (M)] + [API layer (M)] + [Frontend (L)]."
• Include estimate in the ticket metadata, not buried in the body.
• When in doubt, round up. Underestimates erode trust; overestimates create buffer.

Alternative: Story Points

Some teams prefer story points over T-shirt sizes. If the team uses story points:

| Points | Complexity | Roughly Equivalent To | | ------ | ------------------------------------- | --------------------- | | 1 | Trivial change, well-understood | XS (few hours) | | 2 | Small change, minimal unknowns | S (half day - 1 day) | | 3 | Medium change, some unknowns | M (1-2 days) | | 5 | Significant change, moderate unknowns | L (3-5 days) | | 8 | Large change, many unknowns | XL (1-2 weeks) | | 13 | Very large, high uncertainty | Split this ticket |

Which to use: Ask the PM or check existing tickets in the project management tool. Default to T-shirt sizes if unknown -- they're more intuitive for non-engineers.

Ticket format with estimate:

=== TICKET 1 ===
Title: [API] Add CRUD endpoints for user preferences
Estimate: M (1-2 days)
...

Sprint/Milestone Assignment

If the PM has a target launch date, work backwards from the deadline to suggest sprint assignments.

Sprint grouping logic:

Sprint 1 (Foundation & Blockers):
- Database migrations
- API contracts and core endpoints
- Infrastructure/DevOps setup
- Tickets that block everything else

Sprint 2 (Core Functionality):
- Frontend components
- Business logic implementation
- Integration between frontend and backend
- C