Produces a production-ready release specification document (Full or Lean format) including current-state audit, technical architecture with code examples, implementation plan, and risk assessment. Use when 'write a release spec', 'create a release specification for vX.X.X', or 'ground this spec in the codebase'.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Produces a production-ready release specification document (Full or Lean format) including current-state audit, technical architecture with code examples, implementation plan, and risk assessment. Use when 'write a release spec', 'create a release specification for vX.X.X', or 'ground this spec in the codebase'.
category
specification-driven-development
triggers
["write a release spec","create a release specification","ground this spec in the codebase"]
tier
1
agents
["primary"]
tool_dependencies
["file_system","bash"]
inputs
[{"name":"release_context","type":"string","description":"Description of what the release should accomplish (version, goals, scope)","required":true},{"name":"format","type":"string","description":"Specification format — Full, Lean, or Minimal","required":false}]
outputs
[{"name":"release_spec","type":"ref","format":"cas-ref","description":"Production-ready release specification document with current-state audit, architecture, implementation plan, and risk assessment"}]
Write Release Specification Skill
Version: 2.1 Created: 2026-02-02 Updated: 2026-02-07 Author: Manus AI Purpose: Write production-ready, A+ quality specifications for software releases
I. The Philosophy: Specification as Contract
A specification is not documentation—it is a contract. A vague specification invites confusion, rework, and failure. A rigorous specification is an act of respect for the builder's time.
Specifications created with this skill are:
Comprehensive: Every question the builder might have is answered
Precise: Technical details are specific, not hand-wavy
Actionable: The path from specification to implementation is clear
Testable: Success criteria are binary and measurable
The standard: 111/100 (A+). Good enough is not good enough.
II. When to Use This Skill
Use when:
Planning a new software version or release with multiple features
Designing a complex system architecture requiring detailed documentation
Commissioning work to an autonomous agent (Claude Code, etc.) that needs complete context
Coordinating parallel development tracks
Do not use for:
Small bug fixes or minor tweaks (use a simple task description)
Exploratory prototypes (use scouting first)
Features still being actively designed (finish scouting first)
III. The Workflow
Decision Point: Full Template or Lean Format?
Use the Full Template (Section IV) when: System is new, audience includes stakeholders, multiple teams implement, risk is high.
Use the Lean Format when: Architecture is established, audience is the implementing agent, scope is well-defined.
Lean Format structure: Route layouts, component tables, behavior lists. No preamble. "Sonnet level chunks" — direct, precise, implementable.
Rule: Match format to scope. Don't default to full template when lean will do.
Step 1: Gather Context and Inspiration
Read previous specifications — Study 2-3 recent specs for pattern and quality bar
Review the codebase — Use to understand current architecture
/repo-context-sync
Identify the problem — What pain point or strategic goal is this release addressing?
Scout alternatives — Use /strategic-scout if choosing between approaches
Step 1.5: Run Current State Audit
Specs describe the delta from measured reality, not from assumptions. Run before writing.
CREATE TABLE [table_name] (
id TEXT PRIMARY KEY,
field1 TEXT NOT NULL,
created_at TIMESTAMPDEFAULTCURRENT_TIMESTAMP
);
CREATE INDEX idx_[field] ON [table_name]([field]);
Integration Points:
Integrates with [existing component] via [method]
Extends [existing pattern] from v[X.X.X]
Performance Considerations:
[Caching strategy or database indexing]
[Expected latency or throughput]
3.3 [Feature/Component 2] - Detailed Design
[Repeat structure for each major component]
4. Implementation Plan
4.1 Phased Approach
Phase
Duration
Focus
Deliverables
1
Week 1-2
[Focus area]
[Specific deliverables]
2
Week 3-4
[Focus area]
[Specific deliverables]
4.2 Week-by-Week Breakdown
Week 1: [Focus]
Task 1: [Specific, actionable task]
Task 2: [Specific, actionable task]
Success Criteria: [What "done" looks like for this week]
[Continue for all weeks]
4.3 Dependencies & Prerequisites
Required Before Starting: ✅ [Prerequisite 1] Parallel Work: [What can be developed simultaneously] Blocking: [What must complete before other work starts]
4.4 Testing Strategy
Unit: [Component to test] — Target coverage: [X]% Integration: [Integration point to test] E2E: [User flow to test] Performance: [Metric] — Target: [Number] Manual QA: [Scenario] — [Edge cases]
Monitoring & Alerts: [Metric]: Alert if [condition]
7. Documentation & Communication
Update user guide with [new feature]
Update API documentation
Prepare changelog with breaking changes and migration guide (if needed)
8. Appendices
8.1 Future Considerations
v[X+1] Candidates: [Features deferred to next release]
8.2 Open Questions
[Question needing resolution before or during implementation]
8.3 References
[Link to related spec]
[Link to GitHub issue or discussion]
---
## V. Best Practices
| Practice | Why | How |
|----------|-----|-----|
| Start with vision, not features | Features without vision are a list of tasks | Write the vision statement first — if you can't state why in one sentence, you're not ready |
| Write production-ready code examples | Pseudocode leaves room for misinterpretation | Code that could be committed; include types and error handling |
| Use realistic timelines | Underestimating leads to rushed work and debt | Use past releases as benchmarks; 1,000-line feature = 1-2 weeks |
| Document integration points explicitly | Most bugs happen at system boundaries | For every component, document how it connects to existing systems |
| Include risk mitigation from the start | Identifying risks after implementation is too late | Ask "What could go wrong?" during architecture phase |
| Make success criteria binary and testable | Ambiguous criteria lead to scope creep | "User can create a project" ✅ vs. "UI is intuitive" ❌ |
| Reference existing patterns | Consistency reduces cognitive load | "Follow the structure of `ComponentX`" |
---
## VI. Quality Checklist
Before finalizing a specification, verify:
**Vision & Goals**
- [ ] Vision statement is a single, compelling sentence
- [ ] Goals are specific, measurable, and achievable
- [ ] Non-goals explicitly stated to prevent scope creep
**Technical Architecture**
- [ ] Every major component has detailed design with code examples
- [ ] All API endpoints fully specified (method, path, request, response)
- [ ] Integration points with existing systems documented
- [ ] Performance considerations addressed
**Implementation Plan**
- [ ] Timeline is realistic based on complexity
- [ ] Week-by-week breakdown has specific, actionable tasks
- [ ] Testing strategy is comprehensive (unit, integration, E2E, performance)
**Risk & Documentation**
- [ ] Major risks identified with mitigation strategies
- [ ] Rollback procedure defined
- [ ] User and developer documentation needs documented
**If you cannot answer "yes" to all 13 questions, the specification is not ready.**
---
## VII. Common Pitfalls to Avoid
❌ **Vague Goals:** "Improve user experience" → ✅ "Reduce context loading time by 50%"
❌ **Missing Code Examples:** High-level description only → ✅ Complete, runnable code
❌ **Unrealistic Timelines:** "2 days for full backend" → ✅ "2 weeks with phased approach"
❌ **No Risk Assessment:** Assumes everything will work → ✅ Identifies risks and mitigations
❌ **Incomplete Testing:** "We'll test it" → ✅ Specific test cases and coverage targets
❌ **No Integration Points:** Treats feature as isolated → ✅ Documents how it connects to existing system
---
## VIII. Related Skills
- **`strategic-to-tactical-workflow`** — Complete workflow from scouting to implementation (this skill is Phase 6)
- **`frontend-from-backend`** — For frontend specs needing deep backend grounding
- **`implementation-prompt`** — For converting this spec into implementation prompts
- **`parallel-tracks`** — For splitting large specs into parallel execution tracks
- **`repo-context-sync`** — For gathering codebase context before writing specs
- **`memory-garden`** — For documenting learnings from implementation
---
**Last Updated:** 2026-02-07
**Maintained By:** Manus AI
**Status:** Active
---
## Output
- A release specification document saved to `docs/vX.X.X/[release]_specification.md`
- Includes a "Current State (Audit Results)" section with measured counts, not estimates
- Technical architecture section with production-ready Go and TypeScript code examples, API endpoint tables, and database schema
- A complete quality checklist appended confirming all 13 readiness criteria are met before commissioning
## Examples
**Scenario 1:** "Write a spec for DojoGenesis v0.2.5 adding the channel bridge and WebSocket hub." → A Full-format spec with a current-state audit measuring existing test files and API endpoints, detailed design sections for each new component with Go struct definitions and TypeScript interfaces, a two-week phased implementation plan, and a risk table covering WebSocket connection stability.
**Scenario 2:** "Spec the new entity CRUD feature for the v0.3.0 release." → A Lean-format spec with a route layout table (GET/POST/PUT/DELETE for `/api/v1/entities`), a component table mapping each UI widget to its handler, behavior list, test cases, and rollout notes — no preamble, ready to commission.
## Edge Cases
- When scouting is not complete and the architecture is still undecided, stop and complete the scout before writing the spec — a spec written from open architecture questions will need to be substantially rewritten
- When the spec covers work for parallel tracks, write a master release spec first and then use `spec-constellation-to-prompt-suite` to derive the per-track prompts
- When the codebase has changed since the previous spec, run Step 1.5 (current state audit) against the latest main branch — stale metrics produce grounding errors
## Anti-Patterns
- Writing the spec from memory of the codebase instead of running the actual audit commands — even a 5-day-old mental model will have drifted; always run the grep commands
- Skipping "Non-Goals" — implementation agents will fill undefined scope with adjacent features; explicit non-goals prevent this
- Marking a spec "Final" before running the 13-item quality checklist — the checklist exists precisely because authors miss items when reviewing their own work
