Spec Writing

What It Does

1. Loads requirements, visuals, product context
2. Searches codebase for reusable patterns
3. Presents spec in sections (150-200 words each)
4. Validates each section before continuing
5. 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:

1. File names:

find . -name "*[keyword]*" -type f | head -20

1. Content:

grep -r "[keyword]" --include="*.js" --include="*.ts" -l | head -20

1. 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:

1. Present (150-200 words max)
2. Ask validation question
3. WAIT for response
4. Adjust if needed
5. 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.md
• planning/requirements.md
• planning/visuals/* (if exists)

Next phase uses:

• spec.md for tasks breakdown