spec-writing
Use during Phase 3 of spec creation to create specification document - searches codebase for reusable patterns, presents spec in validated 150-200 word sections, and saves complete specification following template structure
When & Why to Use This Skill
This Claude skill streamlines the software development lifecycle by generating structured, validated technical specifications. By analyzing the existing codebase for reusable patterns and following a rigorous section-by-section validation process, it ensures that every spec is concise, actionable, and perfectly aligned with both project requirements and the current tech stack. It bridges the gap between initial product requirements and technical execution, reducing ambiguity and preventing scope creep.
Use Cases
- Transforming initial product requirements and visual mockups into a comprehensive, developer-ready spec.md file.
- Conducting automated codebase audits to identify existing components, hooks, or services that can be leveraged for new features to ensure architectural consistency.
- Maintaining documentation quality across large teams by enforcing standardized templates and word-count constraints for technical sections.
- Defining clear project boundaries by explicitly documenting in-scope requirements and out-of-scope exclusions to prevent scope creep before development begins.
| name | spec-writing |
|---|---|
| description | Use during Phase 3 of spec creation to create specification document - searches codebase for reusable patterns, presents spec in validated 150-200 word sections, and saves complete specification following template structure |
Spec Writing
What It Does
- Loads requirements, visuals, product context
- Searches codebase for reusable patterns
- Presents spec in sections (150-200 words each)
- Validates each section before continuing
- Saves complete spec.md following template
No code in spec - descriptions only.
The Process
Step 1: Load Requirements
SPEC="[provided by workflow]"
cat "$SPEC/planning/initialization.md"
cat "$SPEC/planning/requirements.md"
ls -la "$SPEC/planning/visuals/"
cat specs/product/tech-stack.md
Analyze:
- Feature requirements and scope
- Visual design elements
- Reusability opportunities from user
- Tech stack for search strategy
Step 2: Search Codebase
Search for patterns to reuse based on requirements.
Search by tech stack:
React/Vue:
find src/components -name "*[keyword]*"
grep -r "similar-pattern" src/pages/
find src/hooks src/composables -name "*[keyword]*"
Backend:
find app/models src/models -name "*[keyword]*"
grep -r "similar-endpoint" app/controllers/ src/routes/
find app/services src/services -name "*[keyword]*"
Database:
ls db/migrate/ | grep -i "[keyword]"
grep -A 10 "create_table.*[keyword]" db/schema.rb
Document findings:
- Component/file paths
- What they do
- How to reuse/extend
- Patterns to follow
Step 3: Present Spec Sections
Announce:
Based on requirements and codebase search,
I'll present the spec section by section.
Let me know if each section looks right.
Section 1: Goal & User Stories (150-200 words)
# Specification: [Feature Name]
## Goal
[1-2 sentences from requirements]
## User Stories
- As a [user], I want to [action] so that [benefit]
- [1-2 more stories]
Capture the purpose?
WAIT. Adjust if needed.
Section 2: Specific Requirements (200-250 words)
## Specific Requirements
**[Category 1]**
- [Sub-requirement with approach]
- [Sub-requirement with approach]
- [Up to 8 concise points]
**[Category 2]**
- [Sub-requirement with approach]
- [Up to 8 concise points]
[Up to 10 categories total]
Match your vision?
WAIT. Adjust if needed.
Section 3: Visual Design (if visuals exist) (150-200 words)
## Visual Design
**`planning/visuals/homepage-mockup.png`**
- [Layout structure]
- [Key UI components]
- [Colors/typography if high-fi]
- [Interactive elements]
- [Up to 8 bullets]
**`planning/visuals/form-wireframe.jpg`**
- Fidelity: Low-fi wireframe - structure focus
- [Layout and placement]
- [Up to 8 bullets]
Match how you want to interpret visuals?
WAIT. Adjust if needed.
Section 4: Existing Code (150-200 words)
## Existing Code to Leverage
[From user-provided reusability notes:]
**[Feature user mentioned]**
- Path: `[path]`
- What it does: [description]
- How to reuse: [approach]
[From codebase search:]
**[Component found]**
- Path: `[path from search]`
- What it does: [description]
- How to reuse: [approach]
- Pattern: [architectural pattern]
[Up to 5 existing code areas]
Capture reusability opportunities?
WAIT. Adjust if needed.
Section 5: Out of Scope (100-150 words)
## Out of Scope
[From requirements - what NOT to include:]
- [Feature/capability]
- [Feature/capability]
- [Up to 10 items]
[Inferred from discussion:]
- [Related but future work]
- [Would over-complicate MVP]
Scope boundary correct?
WAIT. Adjust if needed.
Step 4: Save Complete Spec
cat > "$SPEC/spec.md" <<'EOF'
# Specification: [Feature Name]
## Goal
[Approved content]
## User Stories
[Approved content]
## Specific Requirements
[All approved categories]
## Visual Design
[If visuals - approved descriptions]
## Existing Code to Leverage
[All approved reusability notes]
## Out of Scope
[All approved exclusions]
EOF
Step 5: Report Completion
✅ Spec complete!
Created: spec.md
Summary:
- Goal and [X] user stories
- [Y] requirement categories
- [Z] visual designs ([or] No visuals)
- [A] existing patterns to leverage
- [B] items scoped out
Spec is:
- Concise (skimmable)
- Actionable (clear requirements)
- Reusability-focused
- Scope-bounded
Ready for Phase 4: Tasks planning
Return to workflow.
Search Strategy
Smart keywords from requirements:
- Nouns: user, post, comment, payment
- Verbs: create, update, delete, validate
- Concepts: auth, authorization, notification
Multi-strategy search:
- File names:
find . -name "*[keyword]*" -type f | head -20
- Content:
grep -r "[keyword]" --include="*.js" --include="*.ts" -l | head -20
- Patterns:
# React components
grep -r "export.*function [Keyword]" src/
# Classes
grep -r "class [Keyword]" app/models/
Too many results? Narrow:
grep -r "User.*authentication" src/
find src/features/auth -name "*.ts"
find . -name "*[keyword]*" -mtime -30
No results? Broaden:
- Related terms (auth → authentication → login)
- Parent concepts (UserProfile → User)
- Different directories
Validation Pattern
For each section:
- Present (150-200 words max)
- Ask validation question
- WAIT for response
- Adjust if needed
- Continue only when approved
If major revision:
Let me rethink this section.
[Ask clarifying question]
Revised version:
[Present revision]
Better?
Red Flags
Never:
- Write code in spec (descriptions only)
- Present entire spec at once
- Skip codebase search
- Add sections not in template
- Proceed without validation
Always:
- Search before writing spec
- Present in small sections
- Wait for validation after each
- Reference existing code when found
- Keep requirements concise
Integration
Called by:
spec-creation-workflow(Phase 3)
Returns to:
spec-creation-workflow
Creates:
[spec]/spec.md
Uses:
planning/initialization.mdplanning/requirements.mdplanning/visuals/*(if exists)
Next phase uses:
spec.mdfor tasks breakdown