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

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

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.
namespec-writing
descriptionUse 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

  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