Convert a large draft into individual tickets for isolated implementation sessions
Convert a large draft document into individual tickets for isolated implementation sessions.
.speclet/draft.md and identify discrete work items.speclet/tickets/TICKET-N/.speclet/tickets/TICKET-N/ticket.json.speclet/tickets/TICKET-N/ticket-draft.md.speclet/tickets/index.json for centralized status trackingdraft.md only after ALL tickets are successfully createdUse this when:
Read .speclet/draft.md
Identify discrete work items. Each item that can be implemented independently = 1 ticket.
Splitting Rule: 1 ticket = 1 friction/problem. Maximum atomicity.
If the draft is ambiguous about how to split, ask questions with lettered options.
Example:
1. How should I group these items?
A. One ticket per file mentioned ⭐ Recommended — maximum isolation
B. Group by feature area
C. Group by complexity
D. Keep as single ticket
**Reason for recommendation:** Isolated tickets prevent context bleed and allow
prioritization between sessions.
When asking questions with options, ALWAYS:
**Reason for recommendation:** explaining whyExample format:
1. [Question]?
A. Option A
B. Option B ⭐ Recommended — [brief reason]
C. Option C
**Reason for recommendation:** [Detailed explanation of why B is best]
For each discrete item:
.speclet/tickets/TICKET-N/.speclet/tickets/TICKET-N/ticket-draft.md.speclet/tickets/TICKET-N/ticket.jsonIMPORTANT: Complete ALL tickets before proceeding to Step 4. Do NOT delete draft.md until all tickets exist.
{
"specletVersion": "1.0",
"id": "TICKET-1",
"title": "Short descriptive title",
"description": "2-3 sentences explaining the problem/friction and desired outcome",
"files": ["path/to/likely/affected/file.ts"],
"sourceContext": ".speclet/draft.md",
"preliminaryCriteria": [
"Preliminary acceptance criterion (will be refined in speclet-draft)",
"Another criterion"
],
"priority": 1,
"dependsOn": [],
"retryHints": [],
"status": "pending"
}
| Field | Required | Description |
|---|---|---|
specletVersion | Yes | Always "1.0" — identifies this as a speclet ticket |
id | Yes | Unique identifier (TICKET-1, TICKET-2, etc.) |
title | Yes | Short title (< 80 chars) |
description | Yes | 2-3 sentences explaining the problem and desired outcome |
files | Yes | Array of likely affected files (best guess, refined later) |
sourceContext | Yes | Absolute path to the original source document with optional anchor |
preliminaryCriteria | Yes | Initial acceptance criteria (refined during speclet-draft) |
priority | Yes | Numeric priority (1 = highest) |
dependsOn | No | Array of ticket IDs that must complete first |
retryHints | No | Accumulated hints from failed attempts |
status | Yes | One of: pending, in_progress, done, blocked |
The specletVersion field is mandatory. It serves two purposes:
speclet-draft to recognize this as a speclet-generated ticketIf specletVersion is missing, other skills will NOT recognize this as a speclet ticket.
The sourceContext field must point to the original source of the requirement:
✅ Good sourceContext values:
.speclet/draft.mdGitHub Issue #123Code review comment on PR #456❌ Bad sourceContext values:
TICKET-1.json — Self-referential"From the analysis" — Not traceableCreate or update .speclet/tickets/index.json:
{
"specletVersion": "1.0",
"source": "docs/original-analysis.md",
"createdAt": "2025-01-09T15:30:00Z",
"tickets": [
{
"id": "TICKET-1",
"title": "Fix empty state guidance",
"status": "pending",
"priority": 1
},
{
"id": "TICKET-2",
"title": "Improve serial scanner UX",
"status": "pending",
"priority": 2
}
]
}
Note: The source field in index.json should point to the original source document .speclet/draft.md.
Pre-condition check (MANDATORY):
Before deleting, verify:
.speclet/tickets/TICKET-1/, .speclet/tickets/TICKET-2/, etc.ticket.json and ticket-draft.mdindex.json exists and lists all tickets# Verification command
ls .speclet/tickets/*/ticket.json | wc -l # Should equal number of tickets
ls .speclet/tickets/*/ticket-draft.md | wc -l # Should equal number of tickets
Only if verification passes:
rm .speclet/draft.md
If verification fails: STOP. Do not delete draft.md. Report which tickets are missing.
This ensures:
ticket-draft.md as contextAfter creating tickets, summarize:
✅ Created N tickets from draft.md
| ID | Title | Priority | Dependencies |
|----|-------|----------|--------------|
| TICKET-1 | [title] | 1 | - |
| TICKET-2 | [title] | 2 | TICKET-1 |
📁 Structure created:
.speclet/tickets/
├── index.json
├── TICKET-1/
│ ├── ticket.json
│ └── ticket-draft.md
├── TICKET-2/
│ ├── ticket.json
│ └── ticket-draft.md
🗑️ Deleted: .speclet/draft.md
**Next steps:**
1. Start new session
2. Pick a ticket: "Use speclet-draft for TICKET-1"
3. Complete full cycle: draft → spec → loop
4. Come back for next ticket
PHASE 1: Analysis (this session)
────────────────────────────────
speclet-draft (general analysis)
│
▼
.speclet/draft.md
│
▼
speclet-ticket (this skill)
│
├── Creates .speclet/tickets/TICKET-N/ticket.json
├── Creates .speclet/tickets/TICKET-N/ticket-draft.md
├── Creates .speclet/tickets/index.json
├── Verifies ALL tickets created successfully
├── Deletes .speclet/draft.md (only after verification)
└── END of session
════════════════════════════════════════════════════════════
PHASE 2: Per-ticket work (new session)
──────────────────────────────────────
User: "speclet-draft for TICKET-1"
│
├── Reads .speclet/tickets/TICKET-1/ticket.json (validates specletVersion)
├── Reads .speclet/tickets/TICKET-1/ticket-draft.md
├── Asks clarifying questions
└── Creates .speclet/draft.md (refined)
│
▼
speclet-spec → .speclet/spec.json
│
▼
speclet-loop → implements
│
▼
On completion:
├── Move draft.md → tickets/TICKET-1/draft.md
├── Move spec.json → tickets/TICKET-1/spec.json
├── Update ticket.json status to "done"
└── Ready for next ticket
After completing a ticket with speclet-loop, preserve artifacts:
# Move refined draft (keeps ticket-draft.md as original context)
mv .speclet/draft.md .speclet/tickets/TICKET-1/draft.md
# Move spec
mv .speclet/spec.json .speclet/tickets/TICKET-1/spec.json
# Update ticket status
# Edit .speclet/tickets/TICKET-1/ticket.json: "status": "done"
Final structure for completed ticket:
.speclet/tickets/TICKET-1/
├── ticket.json ← Metadata (status: done)
├── ticket-draft.md ← Original context (from speclet-ticket)
├── draft.md ← Refined draft (from speclet-draft for TICKET-1)
└── spec.json ← Implementation spec (from speclet-spec)
"specletVersion": "1.0".speclet/tickets/TICKET-N/.speclet/tickets/TICKET-N/ticket.json.speclet/tickets/TICKET-N/ticket-draft.md.speclet/tickets/index.jsonWhen complete:
"Tickets created in
.speclet/tickets/. Root draft deleted. Start new session and use: speclet-draft for TICKET-1"