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/pr-discipline-and-conventions.md
View on GitHub# PR Discipline & Conventions
Reference for PR size, structure, review, and the conventions that make
PRs ship faster with fewer regressions.
## 1. PR size — the single biggest variable
Smaller PRs:
- Get reviewed faster
- Get reviewed better
- Cause fewer regressions
- Merge faster
- Are easier to revert
Larger PRs:
- Get rubber-stamped
- Hide bugs
- Block merges
- Are harder to revert
### Size guidelines
- **< 100 lines:** ideal; review in 5 min
- **100-300 lines:** good; review in 15-30 min
- **300-500 lines:** acceptable; review in 30-45 min
- **500-1000 lines:** large; consider splitting
- **> 1000 lines:** almost always split
### What to count
- Net lines (additions − deletions)
- Exclude generated files (lock files, snapshots, etc.)
- Exclude test data fixtures
### When large is unavoidable
- Major refactors (call it out, find specialized reviewer)
- New file additions (less risky than modifications)
- Generated code
## 2. PR structure
### Title
- Conventional commit style if your team uses it
- Imperative mood: "Add mute-channel feature" not "Added"
- < 70 characters
- Reference ticket: "(PROJ-123)"
### Description (template)
```markdown
## What
Brief description of what changed.
## Why
Link to PRD / ticket; brief context.
## How
High-level approach; non-obvious decisions.
## Testing
- Unit tests added
- Manual test plan
- How to verify in staging
## Risk + rollout
- Feature flag: PROJ_FLAG_X
- Rollout plan: behind flag, internal first
- Rollback: flip flag
## Screenshots / videos
[If UI]
## Checklist
- [ ] Tests added/updated
- [ ] Docs updated
- [ ] Telemetry events added
- [ ] Feature flag configured
- [ ] Accessibility checked
- [ ] Performance considered
```
Templates enforced in the PR creation flow ensure consistency.
## 3. The review SLA
A working review SLA:
- **Initial review:** within 1 business day
- **Re-review:** within 1 business day of changes
- **Approval-or-discussion:** within 2 business days of opening
Track median + P95 PR cycle time. Slow review is a productivity killer.
## 4. Review behaviors
### What to do
- Review for design, correctness, readability
- Be specific in feedback ("Consider extracting line 47-60 to function" not "Refactor")
- Distinguish blocking from optional
- Approve when you'd accept; don't gate on nits
- Use thread-resolution to track follow-ups
- Speak through behavior, not personality
### What to avoid
- Reviewing for style issues a linter catches
- "Looks good" without actually reading
- Stacking required revisions on minor issues
- Reviewing in passive-aggressive mode
- Re-architecting the PR in review comments
### Reviewer responsibilities
- **Code owner:** must approve
- **Domain expert:** may be asked for input
- **General reviewer:** double-checks readability + obvious issues
For sensitive areas (security, data, billing), require specialist review.
## 5. Definition of done (DoD)
A PR is "done" when:
### Always
- Code is written and reviewed
- Required reviewers approved
- All CI checks pass
- Conversations resolved
- Branch up-to-date with main
### When applicable
- Tests added (or explicit "tests deferred to PR-Y")
- Docs updated
- Telemetry events firing in staging
- Feature flag configured
- Migration tested in staging
- Performance benchmarked
- Accessibility reviewed
- Security review done
### Per-team additions
- Code owners listed
- Specific QA acceptance
- Designer sign-off (if UI change)
- Product sign-off (if user-visible change)
## 6. CI checks
Standard set:
- Linter
- Unit tests
- Integration tests
- Build / typecheck
- Security scan (SAST, dependency scan)
- Code coverage report
- Bundle size / perf budget (frontend)
- Visual regression (UI)
- Mobile build + tests (if mobile)
Bad CI tax: slow CI delays every PR. Aim for < 10 min total CI time.
## 7. Auto-merge
Auto-merge ships PRs when criteria are met:
- All required reviews approved
- All CI checks pass
- No outstanding conversations
- Branch up-to-date with main
Useful for:
- Low-risk PRs in heavily-trafficked repos
- Multi-PR sequences where each PR is reviewed
- Out-of-hours work that's safe to merge
Don't use auto-merge for:
- Risky changes
- PRs that touch sensitive areas
- Changes you want a human to make the final call on
## 8. Mergeable types
### Squash and merge
- Single commit on main
- Cleaner history
- Loses commit-level context
Recommended for:
- Most feature PRs
- Most fix PRs
### Rebase and merge
- Original commits preserved
- Linear history
- Forces local rebase before merge
Recommended for:
- Multi-commit PRs where each commit is meaningful
### Merge commit
- Preserves branch structure
- "Merged feature/X" commit appears on main
Use when:
- Long-running branch with intentional structure
- Avoid if team prefers linear history
Pick one as default; enforce in repo settings.
## 9. Reverting
When a merged PR breaks something:
### Option 1: revert PR
- Git revert; create revert PR
- Fast; uncontroversial
- May lose collateral fixes
### Option 2: forward-fix PR
- Fix the breakage with a new PR
- Slower; sometimes inevitable
- Better when revert is destructive
Choose based on: speed needed, how isolated the bug is, whether revert
creates conflicts.
## 10. PR ownership and review load
### Track:
- PRs authored per engineer per week
- Reviews completed per engineer per week
- Review cycle time per engineer
### Common imbalances:
- Senior engineers review more than they author
- New engineers author more than they review
- Specialists become bottlenecks in their domain
Address through:
- Code-ownership rotation
- Pair reviewing for sensitive areas
- "Backup reviewer" for any single-point area
- Tooling-based review routing (CODEOWNERS file)
## 11. Drafts and WIP
Use draft PRs for:
- Early feedback before complete
- Architectural review before deep implementation
- Coordinating with another PR
Drafts shouldn't:
- Be the default state for everything
- Stay drafts for weeks
- Have CI run repeatedly (wastes resources)
## 12. PR labels (useful conventions)
- `type:feature`, `type:fix`, `type:chore`
- `area:backend`, `area:frontend`, `area:infra`
- `risk:low`, `risk:medium`, `risk:high`
- `needs-design-review`, `needs-security-review`
- `do-not-merge` (with reason)
- `breaking-change`
Labels enable filtering + automation.
## 13. PR-to-ticket linkage
Every PR should reference its ticket:
- In the title or body
- Closes / refs syntax that auto-links in the tracker
- Makes it easy to trace code change to product decision
Without linkage, future you can't tell why a change was made.
## 14. Common pitfalls
- **PRs that touch 30 files.** Split.
- **PRs with no description.** Reviewer must reverse-engineer.
- **Style-only review comments.** Lint catches these; don't waste reviewer time.
- **Approve-without-reading.** Trust dies.
- **PRs that languish for weeks.** Author moves on; reviewer forgets context.
- **Auto-merge on risky changes.** Bypass review safeguards.
- **Re-architecting in review.** Should have been a design conversation earlier.
- **No tests in PRs that need them.** "We'll add later" = never.
- **Linked ticket marked done before PR merges.** Loses traceability.
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 |