design-to-spec

---

description: Transform human design documents into AI-optimized spec.md files tags: [project-init, design, spec, planning, transformation] techStack: [all] appliesTo: ["projects//design.md", "projects//design.docx", "transform spec", "design to spec"] alwaysApply: false

Prerequisites

Claude Code Extended Context Configuration

IMPORTANT: Before running this skill, ensure Claude Code is configured with extended context settings:

MAX_THINKING_TOKENS=50000
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Why Extended Context is Required:

• This skill ingests verbose design documents (often 2000-5000 words)
• Performs preliminary resource discovery (ADR constraints for spec enrichment)
• Generates structured spec.md with technical context
• Chains into

  project-pipeline

  which performs comprehensive resource discovery

Verify settings before proceeding:

# Windows PowerShell
echo $env:MAX_THINKING_TOKENS
echo $env:CLAUDE_CODE_MAX_OUTPUT_TOKENS

# Should output: 50000 and 64000

If not set, see root CLAUDE.md for setup instructions.

Permission Mode: Plan Mode (RECOMMENDED)

This skill analyzes design documents. Use Plan Mode for safe exploration.

⏸ PLAN MODE RECOMMENDED

Before starting this skill:
  1. Press Shift+Tab twice to enter Plan Mode
  2. Look for indicator: "⏸ plan mode on"
  3. Plan Mode ensures read-only operations during analysis

WHY: This skill reads and analyzes design documents, discovers ADR constraints,
     and extracts requirements. Plan Mode prevents accidental edits.

OUTPUT: When analysis is complete, Claude will generate spec.md.
        Switch to Auto-Accept Mode (Shift+Tab) when ready to write the file.

---

Purpose

Tier 1 Component Skill - Transforms verbose human design documents into structured, AI-optimized

spec.md

files that the

project-pipeline

skill can consume.

Key Features:

• Ingests various design document formats (markdown, Word, PDF, rough notes)
• Extracts and structures requirements, scope, and acceptance criteria
• Enriches with ADR references, file paths, and technical constraints
• Flags ambiguities for human resolution
• Outputs standardized spec.md for project-pipeline consumption

Why This Skill Exists:

• Human design docs are narrative-heavy, missing AI-needed context
• AI agents need: explicit constraints, file paths, ADR references, scope boundaries
• Manual spec.md creation is error-prone and time-consuming

When to Use

• User says "transform spec", "design to spec", or "create AI spec"
• Explicitly invoked with

  /design-to-spec {project-path}

• A design document exists at

  projects/{project-name}/design.md

  (or

  .docx

  ,

  .pdf

  )
• Before running

  project-pipeline

  (this skill feeds into that workflow)

Input/Output

Input (one of):

• projects/{project-name}/design.md

  - Markdown design doc

• projects/{project-name}/design.docx

  - Word document

• projects/{project-name}/design.pdf

  - PDF document
• User-provided text/notes (via conversation)

Output:

• projects/{project-name}/spec.md

  - AI-optimized spec file
• Both files kept as project artifacts

Workflow Position

Human Design Document
    │
    ▼
┌──────────────────┐
│  design-to-spec  │  ← THIS SKILL
│  (Tier 1)        │
└──────────────────┘
    │
    ▼
projects/{name}/spec.md (AI-optimized)
    │
    ▼
┌──────────────────┐
│ project-pipeline │  ← NEXT SKILL
│ (Tier 2)         │
└──────────────────┘
    │
    ▼
README.md, PLAN.md, tasks/, etc.

---

Steps

Step 1: Locate Design Document

Action:

SEARCH for design document at:
  1. projects/{project-name}/design.md
  2. projects/{project-name}/design.docx
  3. projects/{project-name}/design.pdf
  4. projects/{project-name}/*.md (if only one non-spec markdown)

IF not found:
  → ASK user: "Where is your design document?"
  → Accept: file path, pasted text, or description

IF found:
  → READ document content
  → Report: "Found design document: {filename} ({word-count} words)"

---

Step 2: Extract Core Elements

Action:

EXTRACT from design document:

1. PURPOSE
   - What problem does this solve?
   - What is the business value?
   - Who are the users/stakeholders?

2. SCOPE
   - What's IN scope (explicit features/changes)
   - What's OUT of scope (explicit exclusions)
   - System boundaries

3. REQUIREMENTS
   - Functional requirements (what it must do)
   - Non-functional requirements (performance, security, etc.)
   - Technical constraints

4. SUCCESS CRITERIA
   - How do we know it's done?
   - Acceptance criteria
   - Quality gates

5. TECHNICAL APPROACH (if present)
   - Architecture decisions
   - Technology choices
   - Integration points

FLAG any missing elements for human input

Output to User:

📋 Extracted from design document:

✅ Found:
   - Purpose: [summary]
   - Scope: {X} features in scope
   - Requirements: {Y} functional, {Z} non-functional
   - Success criteria: {N} criteria identified

⚠️ Gaps identified - proceeding to targeted clarification...

---

Step 2.5: Gap-Targeted Clarification Interview

Purpose: Ask specific, actionable questions derived from gaps discovered in THIS design document. Each question must directly impact implementation decisions.

Principle: Questions are NOT generic checklists. They are intelligent probes based on:

• Undefined terms found in the design
• Implicit assumptions that need validation
• Missing behavior specifications
• Conflicting or ambiguous requirements
• Scope boundaries that are unclear

Action:

ANALYZE extracted content for specific gaps:

FOR EACH gap discovered, generate a TARGETED question that:
  ✅ References the EXACT text or concept that's unclear
  ✅ Explains WHY the answer matters (implementation impact)
  ✅ Offers concrete options where applicable
  ✅ Can be answered in 1-2 sentences

GAP TYPES → QUESTION PATTERNS:

1. UNDEFINED TERMS
   Gap: Design uses "{term}" without defining it
   Question: "You mention '{term}' - what's the specific threshold/value?
             This determines [implementation choice]."

   Example:
   - Gap: Design says "handle large files"
   - Question: "What file size is 'large'? >10MB? >100MB?
               This determines if we need chunked uploads or streaming."

2. IMPLICIT ASSUMPTIONS
   Gap: Design assumes {behavior} without stating it
   Question: "The design seems to assume {assumption}. Is this correct?
             If not, [alternative approach] would be needed."

   Example:
   - Gap: Design assumes users are authenticated
   - Question: "Should anonymous users see the document list (read-only)?
               Currently assuming authenticated-only access."

3. UNSPECIFIED BEHAVIOR
   Gap: Design mentions {feature} but not how it works
   Question: "When {specific scenario}, what should happen?
             Options: [A] {option} or [B] {option}"

   Example:
   - Gap: "Export to PDF" mentioned but no details
   - Question: "When exporting to PDF, should it include comments/annotations?
               This affects the export library choice."

4. MISSING ERROR HANDLING
   Gap: Happy path only for {feature}
   Question: "What should happen when {specific failure scenario}?
             Options: [A] Show error, [B] Retry, [C] Fallback to {alternative}"

   Example:
   - Gap: Document upload flow, no failure handling
   - Question: "If upload fails mid-stream (network error), should we:
               [A] Auto-retry 3x, [B] Save partial and resume, [C] Fail and delete?"

5. CONFLICTING REQUIREMENTS
   Gap: {Requirement A} conflicts with {Requirement B}
   Question: "'{Requirement A}' and '{Requirement B}' seem to conflict.
             Which takes priority? This affects [implementation]."

   Example:
   - Gap: "Real-time sync" vs "Offline support"
   - Question: "Real-time sync conflicts with offline-first. Priority?
               This determines the sync architecture."

6. SCOPE BOUNDARY UNCLEAR
   Gap: Unclear if {capability} is in/out of scope
   Question: "Is {specific capability} in scope for this release?
             The design mentions it but doesn't explicitly include it."

   Example:
   - Gap: Design mentions "mobile users" but scope is unclear
   - Question: "Is mobile-responsive UI in scope, or desktop-only?
               This affects component library choices."

7. MISSING QUANTITATIVE REQUIREMENTS
   Gap: No numbers for {performance/scale requirement}
   Question: "What's the expected {metric}? (e.g., concurrent users, data volume)
             This determines [architectural choice]."

   Example:
   - Gap: No concurrent user expectations
   - Question: "Expected concurrent users? <100 (simple), <1000 (caching needed),
               >1000 (requires scaling strategy)?"

PRESENT questions grouped by impact:

🔴 BLOCKING (must answer before spec):
   {Questions where wrong assumption = wrong implementation}

🟡 IMPORTANT (should answer, can proceed with noted assumptions):
   {Questions that affect approach but have reasonable defaults}

FORMAT each question:
  📍 Context: "{exact quote or reference from design}"
  ❓ Question: "{specific question}"
  💡 Impact: "{why this matters for implementation}"
  🔘 Options: [A] {option} [B] {option} (if applicable)

Output to User:

🎯 Targeted Clarification Questions

Based on gaps in the design document, I need your input on these specific items:

🔴 BLOCKING (need answers to proceed):

1. 📍 Context: "The design mentions 'batch processing for large document sets'"
   ❓ Question: What defines a 'large' set? 10 docs? 100? 1000?
   💡 Impact: Determines if we need background job queuing or can process inline.
   🔘 Options: [A] <50 inline [B] <500 queue [C] >500 chunked batches

2. 📍 Context: "Users can share documents with external parties"
   ❓ Question: External = any email, or only pre-approved domains?
   💡 Impact: Affects auth flow and security review requirements.

🟡 IMPORTANT (proceeding with assumptions if not answered):

3. 📍 Context: "Support for common document formats"
   ❓ Question: Which formats exactly? PDF, DOCX, XLSX, PPTX? Images?
   💡 Impact: Determines preview/conversion libraries needed.
   ⚠️ Assuming: PDF, DOCX, XLSX, PPTX only

Please answer the BLOCKING questions. For IMPORTANT, reply with answers or 'ok' to accept assumptions.

Wait for User: Answers to blocking questions (required), optional answers to important questions

Incorporate Answers:

FOR EACH answer received:
  → Update extracted requirements with concrete values
  → Note source: "Per owner clarification: {answer}"
  → Remove from gaps list
  → Add to spec.md requirements section

IF user skips IMPORTANT questions:
  → Proceed with stated assumptions
  → Flag assumptions in spec.md "Questions/Clarifications" section

---

Step 3: Preliminary Technical Context Discovery

Purpose: Enrich spec.md with architectural constraints only (not detailed implementation patterns).

Action:

IDENTIFY resource types from extracted content:

1. RESOURCE TYPES → ADR CONSTRAINTS
   - API endpoints → Reference ADR-001, ADR-008, ADR-010, ADR-019 (constraints only)
   - PCF controls → Reference ADR-006, ADR-011, ADR-012, ADR-021 (constraints only)
   - Plugins → Reference ADR-002 (constraints only)
   - Storage → Reference ADR-005, ADR-007, ADR-009 (constraints only)
   - AI features → Reference ADR-013, ADR-014, ADR-015, ADR-016 (constraints only)
   - Background jobs → Reference ADR-004, ADR-017 (constraints only)

2. EXTRACT KEY CONSTRAINTS
   - Read applicable ADRs for MUST/MUST NOT rules
   - Identify architectural boundaries
   - Note technology choices

OUTPUT: List of applicable ADRs and key constraints for spec.md

⚠️ **SCOPE LIMITATION**:
This is PRELIMINARY discovery for spec.md enrichment only.
- ✅ DO: Identify which ADRs apply
- ✅ DO: Extract key constraints (MUST/MUST NOT)
- ❌ DON'T: Search codebase for implementation patterns
- ❌ DON'T: Load detailed knowledge docs or guides
- ❌ DON'T: Find existing code examples

Comprehensive resource discovery happens in project-pipeline Step 2.

---

Step 4: Generate Structured spec.md

Action:

CREATE: projects/{project-name}/spec.md

FOLLOW template structure:

# {Project Name} - AI Implementation Specification

> **Status**: Ready for Implementation
> **Created**: {date}
> **Source**: {design-document-filename}

## Executive Summary

{2-3 sentences from extracted PURPOSE}

## Scope

### In Scope
{Bulleted list of features/changes}

### Out of Scope
{Explicit exclusions - ASK if not in design doc}

### Affected Areas
{List of code areas, with file paths where known}
- `src/server/api/...` - {description}
- `src/client/pcf/...` - {description}

## Requirements

### Functional Requirements
{Numbered list with clear acceptance criteria}
1. **FR-01**: {requirement} - Acceptance: {criteria}
2. **FR-02**: {requirement} - Acceptance: {criteria}

### Non-Functional Requirements
{Performance, security, accessibility, etc.}
- **NFR-01**: {requirement}

## Technical Constraints

### Applicable ADRs
{List ADRs that MUST be followed}
- **ADR-001**: Minimal API pattern required
- **ADR-008**: Use endpoint filters for authorization

### MUST Rules (from ADRs)
{Extracted key constraints}
- ✅ MUST use...
- ✅ MUST NOT...

### Existing Patterns to Follow
{Reference to canonical implementations}
- See `src/server/api/.../ExampleEndpoints.cs` for endpoint pattern
- See `.claude/patterns/api/` for detailed patterns

## Success Criteria

{Numbered list with verification method}
1. [ ] {criterion} - Verify by: {method}
2. [ ] {criterion} - Verify by: {method}

## Dependencies

### Prerequisites
{What must exist/be done first}

### External Dependencies
{APIs, services, approvals needed}

## Owner Clarifications

{Answers captured from Step 2.5 interview - CRITICAL for implementation}

| Topic | Question | Answer | Impact |
|-------|----------|--------|--------|
| {topic} | {question asked} | {owner's response} | {implementation decision made} |

## Assumptions

{Items where owner did not specify - proceeding with stated assumptions}

- **{topic}**: Assuming {value/behavior} - affects {component/decision}

## Unresolved Questions

{Still blocking or need answers during implementation}
- [ ] {question} - Blocks: {what this blocks}

---

*AI-optimized specification. Original design: {filename}*

---

Step 5: Present for Review

Action:

OUTPUT spec.md content to user

SHOW summary:
  - Word count
  - Number of requirements
  - Number of ADRs referenced
  - Number of unresolved questions

ASK for review:
  "Please review the spec.md. Any changes needed before proceeding to project-pipeline?"

Output to User:

✅ spec.md generated:
   - {X} words
   - {Y} functional requirements
   - {Z} ADRs referenced
   - {N} unresolved questions flagged

📄 File created: projects/{project-name}/spec.md

📋 Next Steps:
   1. Review spec.md for accuracy
   2. Resolve any flagged questions
   3. Run: /project-pipeline {project-name}

[Y to proceed to project-pipeline / edit to make changes / done to finish]

Wait for User:

y

(proceed to pipeline) |

edit

(make changes) |

done

(stop here)

---

Next Steps After This Skill

✅ CORRECT: Proceed to Full Pipeline

After spec.md is reviewed and approved:

/project-pipeline projects/{project-name}

This performs:

• ✅ Comprehensive resource discovery (ADRs, skills, knowledge docs, code patterns)
• ✅ Artifact generation (README, PLAN, CLAUDE.md)
• ✅ Task decomposition (50-200+ task files)
• ✅ Feature branch creation
• ✅ Ready to execute task 001

❌ INCORRECT: Call Component Skills Directly

DO NOT run these after design-to-spec:

# ❌ WRONG - Missing resource discovery and tasks
/project-setup projects/{project-name}

# ❌ WRONG - Can't create tasks without plan.md
/task-create projects/{project-name}

Why? Component skills are called BY project-pipeline, not by developers.

---

Step 6: Handoff to project-pipeline (Optional)

Action:

IF user said 'y':
  → INVOKE project-pipeline projects/{project-name}
  → Handoff message: "Starting project-pipeline with generated spec.md..."

IF user said 'done':
  → OUTPUT: "spec.md ready at projects/{project-name}/spec.md
             Run /project-pipeline {project-name} when ready."

---

spec.md Template

The generated spec.md follows this structure (also saved at

docs/ai-knowledge/templates/spec.template.md

):

# {Project Name} - AI Implementation Specification

> **Status**: Ready for Implementation
> **Created**: {YYYY-MM-DD}
> **Source**: {original-design-document}

## Executive Summary

{Brief description of what this project delivers and why}

## Scope

### In Scope
- {Feature/change 1}
- {Feature/change 2}

### Out of Scope
- {Explicit exclusion 1}
- {Explicit exclusion 2}

### Affected Areas
- `{path}` - {description}

## Requirements

### Functional Requirements
1. **FR-01**: {Requirement} - Acceptance: {Criteria}

### Non-Functional Requirements
- **NFR-01**: {Requirement}

## Technical Constraints

### Applicable ADRs
- **ADR-XXX**: {Brief relevance}

### MUST Rules
- ✅ MUST {constraint}
- ❌ MUST NOT {constraint}

### Existing Patterns
- See `{path}` for {pattern}

## Success Criteria
1. [ ] {Criterion} - Verify: {method}

## Dependencies

### Prerequisites
- {Prerequisite}

### External
- {External dependency}

## Owner Clarifications

*Answers captured during design-to-spec interview:*

| Topic | Question | Answer | Impact |
|-------|----------|--------|--------|
| {topic} | {question asked} | {owner's answer} | {how this affects implementation} |

## Assumptions

*Proceeding with these assumptions (owner did not specify):*

- **{topic}**: Assuming {value/behavior} - will affect {component}

## Unresolved Questions

*Still need answers before implementation:*

- [ ] {Unresolved question} - Blocks: {what this blocks}

---
*AI-optimized specification. Original: {filename}*

---

Error Handling

If design document not found:

❌ No design document found at projects/{project-name}/

Looking for: design.md, design.docx, design.pdf

Options:
1. Provide file path: "the design is at {path}"
2. Paste content: "here's the design: ..."
3. Create interactively: "help me write the design"

If design doc too vague:

⚠️ Design document lacks sufficient detail for AI implementation.

Missing critical elements:
- [ ] Concrete requirements (what specifically to build)
- [ ] Success criteria (how to verify completion)
- [ ] Scope boundaries (what's NOT included)

Options:
1. 'clarify' - Answer questions to fill gaps
2. 'proceed' - Generate spec.md with assumptions noted
3. 'stop' - Exit and improve design document

---

Integration with Other Skills

This skill feeds into the project lifecycle:

design-to-spec (THIS SKILL)
    │
    └─→ Generates spec.md
           │
           ▼
    project-pipeline
           │
           ├─→ project-setup (README, PLAN, CLAUDE.md)
           └─→ task-create (task files)

Skills this skill may invoke:

• adr-aware

  (implicit) - For ADR discovery during context gathering

Skills that depend on this skill's output:

• project-pipeline

  - Consumes spec.md

• project-setup

  - Consumes spec.md (if called directly)

---

Success Criteria

Skill successful when:

• Design document ingested and parsed
• Core elements extracted (purpose, scope, requirements, criteria)
• Gap-targeted interview conducted (specific questions asked for discovered gaps)
• Owner clarifications captured (answers recorded in spec.md)
• Assumptions documented (for unanswered questions)
• Technical context discovered (ADRs, patterns, file paths)
• spec.md generated with all required sections
• Unresolved questions clearly flagged with blocking impact
• User reviewed and approved spec.md
• Original design document preserved alongside spec.md

---

For Claude Code: This skill transforms human design documents into structured specs optimized for AI-driven implementation. Always preserve the original design document as a project artifact.