borghei/Claude-Skills / product-team/spec-to-repo
spec-to-repo
FlaggedTranslate product specs (PRDs, user stories) into a ship-ready repo plan: ticket decomposition, branch strategy, and PR sequencing. Use when breaking a PRD into tickets or designing the branch/PR sequence.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.9 KB |
| assets/sample_tracer_tickets.json | config | 2.3 KB |
| references/branch-strategy-for-features.md | markdown | 6.4 KB |
| references/pr-discipline-and-conventions.md | markdown | 7.0 KB |
| references/spec-to-ticket-decomposition.md | markdown | 6.7 KB |
| references/tracer-bullet-slicing.md | markdown | 7.3 KB |
| scripts/branch_naming_validator.py | script | 5.0 KB |
| scripts/pr_scope_analyzer.py | script | 7.1 KB |
| scripts/prd_to_tickets_decomposer.py | script | 10.0 KB |
| scripts/ticket_graph_validator.py | script | 7.2 KB |
references/spec-to-ticket-decomposition.md
View on GitHub# Spec to Ticket Decomposition
Patterns for translating a PRD or feature brief into a clean ticket tree.
## 1. The decomposition order
A useful order for breaking down a spec:
1. **User-facing capabilities** — what can the user do that they couldn't before?
2. **System surfaces** — which APIs, screens, infra change?
3. **Vertical slices** — smallest user-visible improvement end-to-end
4. **Cross-cutting work** — telemetry, docs, accessibility, security review
5. **Rollout work** — feature flag, canary, monitoring, comms
This order keeps the user value visible. Decomposing by tech layer first
produces strange artifacts ("backend can't ship until frontend ships" or
vice versa).
## 2. The vertical-slice principle
Best ticket: ships a small piece of user value end-to-end.
### Why
- Lets you ship even before the full feature is complete
- Real user feedback informs the next slice
- Fewer "stuck waiting" tickets
- PR is reviewable in isolation
### How
- For each user capability, identify BE + FE + tests + telemetry + docs
- Combine into the ticket if it's a single PR's worth (~200-400 lines)
- Split into 2 tickets if PR would exceed 400 lines (e.g., BE PR + FE PR)
- Use feature flags to ship pieces independently
### When vertical slicing doesn't work
- Major schema migrations (do these standalone, ahead of time)
- Cross-cutting refactors (do these in their own epic)
- Brand-new infrastructure (scaffolding ticket comes first)
## 3. Ticket templates
### Story ticket
```
## User capability
[as a {persona}, I can {action} so that {outcome}]
## Acceptance criteria
- [ ] Criterion 1 (testable)
- [ ] Criterion 2
- [ ] Criterion 3
## Out of scope
- Item 1
- Item 2
## Implementation notes
- [link to design]
- [link to API spec]
## Definition of done
- [ ] Code reviewed + merged
- [ ] Tests added
- [ ] Telemetry events firing in staging
- [ ] Docs updated
- [ ] Feature flag configured (if applicable)
```
### Technical ticket
```
## Goal
[what changes; why]
## Approach
[brief; link to design doc if longer]
## Risks
[what could go wrong]
## Definition of done
- [ ] Implemented
- [ ] Tested
- [ ] Migration runbook (if data changes)
- [ ] Rollback plan
```
### Investigation / spike ticket
```
## Question
[what we need to figure out]
## Deliverable
[a doc, a benchmark, a PoC]
## Timebox
[N days]
## Decision needed
[what we'll decide after the spike]
```
## 4. Common decomposition antipatterns
### "Build the system" mega-ticket
A ticket called "Build notifications system" is not a ticket; it's the epic.
Fix: break into user-visible capabilities (each <3 days).
### Backend-first / frontend-second sequential
"Backend ticket (2 days) blocks frontend ticket (3 days)."
Fix: vertical-slice; use feature flag; or design API first so both can
start in parallel.
### "Cleanup ticket" with no scope
"Clean up notifications code."
Fix: specific changes with acceptance criteria. Or scope it as a spike
that produces a decomposition.
### Ticket sized by guess
"This is medium." Without a breakdown, "medium" is wishful thinking.
Fix: bullet the steps; estimate per step; sum + 30% buffer.
### Hidden dependency
"Just need the data team to add a column."
Fix: cross-team dependencies become their own tickets with explicit
coordination. Surface in decomposition, not at sprint planning.
## 5. The "T-shirt size" trap
S/M/L/XL is useful in early estimation but rots without grounding:
- S in your team = how many engineer-days?
- L in your team = how many engineer-days?
- Don't redefine these silently — calibrate quarterly
Better than nothing; not a substitute for breaking down to engineer-days
when uncertainty is high.
## 6. Acceptance criteria — how specific?
Specific enough that an engineer can implement without asking the PM 5 questions.
### Good acceptance criterion
"When a user mutes a channel, no notifications from that channel reach
the user (push, email, in-app) for the duration of the mute period.
Sender sees no indication that the recipient muted."
### Weak acceptance criterion
"Users can mute notifications." (Mute what? For how long? Visible to whom?)
### Acceptance vs detailed design
Acceptance describes the user-visible behavior; the design doc describes
HOW. Don't bury implementation in acceptance criteria; don't bury
user-visible behavior in design.
## 7. Edge cases — surface them upfront
For each ticket, list at least 3 edge cases:
- Empty state
- Error state (timeout, server error, validation error)
- Concurrent action
- Permission edge case
- Localization (text expansion, RTL)
- Accessibility (screen reader, large text, no mouse)
Surfaced edge cases become acceptance criteria; unsurfaced edge cases
become production bugs.
## 8. Telemetry as a first-class deliverable
Every ticket that adds behavior should specify the telemetry:
- What events fire?
- What properties are captured?
- What dashboard / alert is updated?
- How will success be measured?
Skip this and you'll discover, at launch + 7 days, that you can't measure
the impact.
## 9. Tests as a first-class deliverable
For each ticket, specify the tests required:
- Unit (what units; what edge cases)
- Integration (which boundaries)
- E2E (which user journeys)
- Visual regression (if UI)
- Performance (if perf-sensitive)
- Security (if auth / data sensitive)
- Accessibility (if UI)
"We'll add tests later" usually means "we'll add them never."
## 10. Documentation as a first-class deliverable
Per ticket, specify the docs that need updating:
- User-facing docs (help center, in-product)
- API docs (if API changes)
- Internal runbooks (if operational changes)
- Architecture docs (if design changes meaningful)
- Onboarding for new engineers (if new system)
Docs that ship with the code stay accurate. Docs that ship later don't.
## 11. The PRD-to-tickets workshop
A useful 60-90 min session before sprint planning:
### Roles
- PM + lead engineer + designer + tester
### Agenda
1. PM walks through the spec (15 min)
2. Engineer asks clarifying questions (15 min)
3. Designer walks through interactions (10 min)
4. Group decomposes into tickets on a whiteboard (30 min)
5. Group identifies risks + dependencies (10 min)
6. Group commits to definition of done (10 min)
Output:
- Ticket tree in the tracker
- Definition-of-done checklist
- Risk + dependency list
- Estimated rough effort
## 12. Common pitfalls
- **Decomposition that ignores the team's real velocity.** Plan for the team you have.
- **Tickets that don't include tests / docs / telemetry.** They never get done.
- **Cross-team work as a single ticket.** Make the handoff a ticket itself.
- **Acceptance criteria that aren't testable.** "Users like it" isn't.
- **Edge cases discovered in QA.** Surface in decomposition.
- **No rollout plan for risky changes.** Surprise launches surprise on-call.
- **One big PR for the entire feature.** Split.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |