# Sdd Render

> Render JSON specs to human-readable markdown with AI-enhanced insights, visualizations, and progressive disclosure

- Skill: `majiayu000/sdd-render` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/sdd-render`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/sdd-render/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/sdd-render

---


# Spec Rendering Skill

## Overview

Transform JSON specification files into beautifully formatted, human-readable markdown documentation. The sdd-render skill bridges the gap between machine-readable specs and human comprehension, making it easy to review progress, share status, and understand project structure at a glance.

**Features:**
- **Markdown generation** - Convert JSON specs to formatted markdown with progress tracking
- **Visual progress indicators** - Status icons and percentage completion for phases/tasks
- **Dependency visualization** - Show task dependencies and blockers
- **Hierarchical structure** - Phases, groups, tasks, and subtasks clearly organized
- **Metadata display** - Estimates, complexity, reasoning, and file paths
- **Multiple output destinations** - Default location or custom paths via --output flag

## Core Workflow

**⚠️ CRITICAL REQUIREMENT: MANDATORY PRE-EXECUTION CHECKLIST ⚠️**

Before executing ANY `sdd render` command, you MUST complete this validation:

```
┌─────────────────────────────────────────────────────────────┐
│ PRE-EXECUTION DECISION TREE (MANDATORY)                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ ❓ Has user EXPLICITLY specified a rendering mode?         │
│    (e.g., "use basic mode", "render with full AI")         │
│                                                             │
│         YES ─────────┐              NO                      │
│                      │               │                      │
│                      │               ▼                      │
│                      │      ✋ STOP - DO NOT RENDER YET     │
│                      │               │                      │
│                      │               ▼                      │
│                      │      🔴 REQUIRED ACTION:            │
│                      │         Use AskUserQuestion tool     │
│                      │         to ask for mode preference   │
│                      │               │                      │
│                      │               ▼                      │
│                      └──────────► ✅ Proceed with render    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**CRITICAL: Always Ask User for Rendering Mode**

Unless the user has explicitly specified a rendering mode in their request, you MUST use the AskUserQuestion tool to ask which mode they want:

**Example Usage:**
```
AskUserQuestion(
  questions: [{
    question: "Which rendering mode would you like to use?",
    header: "Render Mode",
    multiSelect: false,
    options: [
      {
        label: "Basic (fast, no AI)",
        description: "Quick rendering without AI features (< 2 seconds)"
      },
      {
        label: "Enhanced - Summary",
        description: "Executive summary with AI (~1-2 minutes)"
      },
      {
        label: "Enhanced - Standard (recommended)",
        description: "Balanced AI features (~3-5 minutes) [DEFAULT]"
      },
      {
        label: "Enhanced - Full",
        description: "Complete AI analysis (~5-8 minutes)"
      },
      {
        label: "Generate all versions for comparison",
        description: "Creates basic, standard, and full versions"
      }
    ]
  }]
)
```

**When to skip asking:**
- User explicitly requested a mode: "render with basic mode", "use full AI enhancement"
- User requested multiple versions: "generate all three versions", "compare enhancement levels"
- User is batch rendering multiple specs (use default enhanced standard)

**After getting the answer:**
- Map user's choice to the appropriate CLI flags
- Execute sdd render with the selected mode
- Report the rendering time and output location

---

### ❌ ANTI-PATTERNS: What NOT to Do

**WRONG APPROACH #1: Immediate execution without asking**

```
User: "Let's call the sdd-render skill for /path/to/spec.json"

❌ Assistant: I'll render the specification file for you.
   [Immediately executes: sdd render /path/to/spec.json]

   PROBLEM: Skipped asking about rendering mode preference
```

**CORRECT APPROACH #1: Ask first, then execute**

```
User: "Let's call the sdd-render skill for /path/to/spec.json"

✅ Assistant: I'll help you render that specification. First, let me ask
   which rendering mode you'd like to use.
   [Uses AskUserQuestion tool to present mode options]
   [After user answers, executes with chosen mode]
```

---

**WRONG APPROACH #2: Assuming default is okay**

```
User: "Can you render this spec?"

❌ Assistant: I'll use the default enhanced standard mode.
   [Executes without asking]

   PROBLEM: Assumed user wants default without confirming
```

**CORRECT APPROACH #2: Explicit confirmation**

```
User: "Can you render this spec?"

✅ Assistant: Which rendering mode would you prefer?
   [Presents options with AskUserQuestion]
   [User selects mode]
   [Executes with selected mode]
```

---

**ONLY ACCEPTABLE: User explicitly specifies mode**

```
User: "Render this spec with basic mode for speed"

✅ Assistant: I'll render using basic mode as you requested.
   [Executes: sdd render <spec-id> --mode basic]

   REASON: User explicitly specified "basic mode" - no need to ask
```

**3-Phase Process:**

1. **Prepare** - Ask user for mode (unless explicit), locate spec file, verify output destination
2. **Render** - Execute sdd render with appropriate flags based on user choice
3. **Review/Share** - View output and distribute as needed

**Key principles:**
- **Rendering is read-only** - Never modifies source JSON specs
- **Output customization** - Use --output for specific destinations
- **Batch operations** - Process multiple specs when needed
- **Always render AFTER updates** - Let other skills modify specs first, then render
- **Always ask for mode** - Unless explicitly specified by user

**Quick decision guide:**
- ✅ Need quick status check? → Ask user, they might want basic mode for speed
- ✅ Sharing with team? → Ask user, they might want enhanced standard
- ✅ Multiple specs? → Use default enhanced standard for batch operations
- ❌ Need to modify spec? → Use `Skill(sdd-toolkit:sdd-plan)` instead
- ❌ Need to update tasks? → Use sdd-update-subagent first, then render

## Skill Family

This skill is part of the **Spec-Driven Development** family:
- **Skill(sdd-toolkit:sdd-plan)** - Creates specifications and task hierarchies
- **Skill(sdd-toolkit:sdd-next)** - Identifies next tasks and creates execution plans
- **Skill(sdd-toolkit:sdd-render)** (this skill) - Renders JSON specs to human-readable formats
- **sdd-update-subagent** - Updates task and spec progress

## Use This Skill When

**Reporting and Communication:**
- Need to review a spec's overall structure and progress quickly
- Want to share spec status with team members or stakeholders
- Creating documentation for project planning meetings
- Generating weekly/monthly progress reports
- Onboarding new developers to understand project scope

**Analysis and Planning:**
- Analyzing task dependencies visually before starting work
- Identifying blockers across multiple phases
- Understanding critical path and task relationships
- Reviewing spec structure for completeness
- Validating phase organization and task breakdown

**Documentation:**
- Creating permanent records of project plans
- Archiving completed specifications for reference
- Generating proposals or estimates from specs
- Producing client-facing project timelines

## Decision Matrix

### Rendering Scope Decision

| Scenario | Action | Why |
|----------|--------|-----|
| Single active spec review | `sdd render {spec-id}` | Quick status check |
| All active specs status | Batch render all active specs | Comprehensive project overview |
| Client presentation | `sdd render {spec-id} --output client/report.md` | Professional delivery |
| Debugging spec structure | `sdd render {spec-id} --verbose` | Detailed diagnostics |
| Daily standup prep | Render + grep for progress | Extract quick metrics |
| Post-update verification | Render after sdd-update | Visualize changes |

### Output Destination Decision

| Audience | Destination | Format Considerations |
|----------|------------|----------------------|
| Development team | `specs/.human-readable/` (default) | Version controlled, easy access |
| Stakeholders | `docs/reports/` or `docs/status/` | Permanent documentation location |
| Clients | Custom path + PDF conversion | Professional presentation format |
| CI/CD pipelines | stdout (`--output -`) | Pipeline integration, no file I/O |
| Archive | `docs/archive/` with timestamp | Historical record keeping |

### Troubleshooting Decision Tree

**When rendering fails, check in order:**

1. **Spec file exists?**
   - ❌ No → Use `sdd find-specs --verbose` to locate
   - ✅ Yes → Continue to step 2

2. **JSON is valid?**
   - Test: `python3 -m json.tool <spec-file>.json`
   - ❌ Invalid → Fix JSON syntax or regenerate with sdd-plan
   - ✅ Valid → Continue to step 3

3. **Output directory writable?**
   - Test: `ls -la $(dirname <output-path>)`
   - ❌ No permission → Create directory or use default location
   - ✅ Writable → Continue to step 4

4. **Still failing?**
   - Run with `--debug` flag for detailed error messages
   - Check Troubleshooting section (line 799) for specific errors
   - Verify sdd CLI is properly installed: `sdd render --help`

## Do NOT Use For

**Spec Modification:**
- Creating new specifications (use `Skill(sdd-toolkit:sdd-plan)`)
- Updating task status or progress (use sdd-update-subagent)
- Modifying spec structure or metadata (use `Skill(sdd-toolkit:sdd-plan)`)
- Adding or removing tasks (use `Skill(sdd-toolkit:sdd-plan)`)

**Task Execution:**
- Finding next tasks to work on (use `Skill(sdd-toolkit:sdd-next)`)
- Creating execution plans (use `Skill(sdd-toolkit:sdd-next)`)
- Actually implementing code (use appropriate coding tools)
- Running tests or verification (use `Skill(sdd-toolkit:run-tests)`)

**Other:**
- Writing conceptual documentation (tutorials, guides)
- Generating code or test files
- Real-time collaboration (this creates static snapshots)

## Tool Verification

**Before using this skill**, verify the required tools are available:

```bash
# Verify sdd render command is installed
sdd render --help
```

**Expected output**: Help text showing available options for the render command

**IMPORTANT - CLI Usage Only**:
- ✅ **DO**: Use `sdd render` CLI command (e.g., `sdd render {spec-id}`)
- ❌ **DO NOT**: Execute Python scripts directly (e.g., `python cli.py`, `python renderer.py`)

The CLI provides proper error handling, validation, argument parsing, and interface consistency. Direct script execution bypasses these safeguards and may fail.

If the verification command fails, ensure the SDD toolkit is properly installed and accessible in your environment.

## Agent Boundaries

**CRITICAL: This skill is READ-ONLY**

This skill transforms JSON specs into markdown. It NEVER modifies the source specification files or any code.

**MANDATORY: Pre-Execution Mode Selection**

Before executing ANY render command, you MUST ask the user for their preferred rendering mode using the AskUserQuestion tool (unless the user explicitly specified a mode in their request). This is a non-negotiable requirement of the skill contract. See the Pre-Execution Decision Tree in the Core Workflow section above.

**What this skill does:**
- ✅ Reads JSON spec files from specs/active, specs/completed, specs/archived
- ✅ Generates markdown output files
- ✅ Writes to specs/.human-readable/ or custom --output path
- ✅ Displays progress, dependencies, and task metadata

**What this skill NEVER does:**
- ❌ Modifies source JSON spec files
- ❌ Updates task status or completion timestamps
- ❌ Creates or modifies code files
- ❌ Changes spec metadata or structure
- ❌ Executes tests or verification steps

**Handoff Points - When to Use Other Skills:**

**After successful rendering:**

1. **Spec structure looks wrong?**
   - → Hand off to `Skill(sdd-toolkit:sdd-plan)` to modify spec structure
   - Example: Missing phases, incorrect task organization

2. **Task status needs updating?**
   - → Hand off to sdd-update-subagent to update progress
   - Example: Mark tasks as completed, update timestamps
   - **IMPORTANT:** Update first, THEN render to visualize changes

3. **Ready to implement tasks?**
   - → Hand off to `Skill(sdd-toolkit:sdd-next)` to identify next task
   - Example: Need execution plan with gathered context

4. **Need to verify implementation?**
   - → Hand off to `Skill(sdd-toolkit:run-tests)` to run tests
   - Example: Run verification steps from spec

5. **Output is satisfactory?**
   - → Done, no further action needed
   - Share the rendered markdown as needed

**Never chain this skill with spec modification:**
- ❌ **Wrong:** Update task status → Render (race condition risk)
- ✅ **Correct:** Use sdd-update-subagent → Then render separately

**Always render AFTER making changes:**
- Create new spec with sdd-plan → Render to review
- Complete tasks with sdd-update → Render to visualize progress
- Major spec updates → Render to verify changes

**Consultation is never required for rendering:**
- Rendering is a deterministic transformation (JSON → Markdown)
- If rendering fails, use Troubleshooting Decision Tree (line 102)
- No external tool consultation needed for render operations

---

## Quick Start

**Execution Workflow:**

1. **Ask user for mode preference** (unless they explicitly specified):
   - Use AskUserQuestion tool (see example in Core Workflow section above)
   - Present the 5 mode options

2. **Execute the appropriate command** based on user's answer:

   **If user chose "Basic (fast, no AI)":**
   ```bash
   sdd render {spec-id} --mode basic
   # ~2 seconds
   ```

   **If user chose "Enhanced - Summary":**
   ```bash
   sdd render {spec-id} --enhancement-level summary
   # ~1-2 minutes
   # Note: --mode enhanced is implied when --enhancement-level is specified
   ```

   **If user chose "Enhanced - Standard" (or didn't specify):**
   ```bash
   sdd render {spec-id}
   # Default: enhanced mode with standard level (~3-5 minutes)
   # Equivalent to: sdd render {spec-id} --enhancement-level standard
   ```

   **If user chose "Enhanced - Full":**
   ```bash
   sdd render {spec-id} --enhancement-level full
   # ~5-8 minutes
   # Note: --mode enhanced is implied when --enhancement-level is specified
   ```

   **If user chose "Generate all versions for comparison":**
   ```bash
   # Generate all three versions with different output names
   sdd render {spec-id} --mode basic -o specs/.human-readable/{spec-id}-basic.md
   sdd render {spec-id} --enhancement-level standard -o specs/.human-readable/{spec-id}-standard.md
   sdd render {spec-id} --enhancement-level full -o specs/.human-readable/{spec-id}-full.md
   ```

3. **Report results** to the user (output location and any relevant information)

**Output Location:**
By default, rendered markdown is saved to `specs/.human-readable/{spec-id}.md`

**Mode Options for AskUserQuestion:**

Present these 5 options to the user:

| Option Label | CLI Command | Use Case |
|-------------|-------------|----------|
| "Basic (fast, no AI)" | `--mode basic` | Quick status checks (~2s) |
| "Enhanced - Summary" | `--enhancement-level summary` | Executive summaries (~1-2 min) |
| "Enhanced - Standard (recommended)" | (default, no flags needed) | Most use cases (~3-5 min) [DEFAULT] |
| "Enhanced - Full" | `--enhancement-level full` | Comprehensive analysis (~5-8 min) |
| "Generate all versions for comparison" | Multiple commands with different `-o` paths | Side-by-side comparison |

See the [AI Enhancement Modes](#ai-enhancement-modes) section below for detailed feature comparison.

---

## Current Rendering Features

### Basic Markdown Generation

The renderer converts JSON specification files into clean, readable markdown with:

**Header Section:**
- Spec title and ID
- Overall status and progress (X/Y tasks, percentage)
- Estimated effort and complexity
- Description and objectives

**Phase Sections:**
- Phase titles with progress indicators
- Phase-level metadata (purpose, risk level, estimates)
- Phase dependencies (blocked by, depends on)
- Nested task groups

**Task Details:**
- Task title with status icon
- File path being modified
- Estimated hours
- Changes description and reasoning
- Dependencies and blockers
- Subtask hierarchy

**Verification Steps:**
- Verification type (manual, automated, integration)
- Commands to execute
- Expected outcomes

### Status Icons

Visual indicators make progress instantly recognizable:

- ⏳ **Pending** - Task not yet started
- 🔄 **In Progress** - Currently being worked on
- ✅ **Completed** - Successfully finished
- 🚫 **Blocked** - Waiting on dependencies
- ❌ **Failed** - Encountered errors

### Progress Tracking

Progress is calculated and displayed at multiple levels:

**Spec Level:**
```
User Authentication System
Status: in_progress (15/23 tasks, 65%)
```

**Phase Level:**
```
## Phase 2: Authentication Service (5/8 tasks, 62%)
```

**Group Level:**
```
### File Modifications (4/5 tasks)
```

### Dependency Visualization

Dependencies are clearly shown to understand task relationships:

```markdown
**Depends on:** task-1-2, task-1-3
**Blocked by:** task-2-1
**Blocks:** task-3-1, task-3-2, task-3-3
```

This makes it easy to:
- Identify what must be completed before starting a task
- See what's blocking progress
- Understand which tasks depend on the current task

### Output Customization

**Default Output:**
```bash
sdd render my-spec-001
# Creates: specs/.human-readable/my-spec-001.md
```

**Custom Output Path:**
```bash
sdd render my-spec-001 --output docs/current-project.md
# Creates: docs/current-project.md
```

**Specify Specs Directory:**
```bash
sdd render my-spec-001 --path /path/to/specs
# Useful when working with multiple projects
```

---

## AI Enhancement Modes

The sdd-render skill supports multiple rendering modes to balance speed and feature richness. Choose the mode based on your needs for performance versus detailed AI-generated insights.

### Mode Overview

**Default Rendering:**
When you run `sdd render {spec-id}` without any flags, it uses **Enhanced Mode with Standard level** for balanced performance and features (~3-5 minutes).

**Two primary modes:**

1. **Basic Mode** (`--mode basic`)
   - Fast, traditional markdown rendering
   - No AI features
   - Uses SpecRenderer for deterministic output
   - Typical rendering time: < 2 seconds
   - Use when speed is critical or AI features aren't needed
   - **Must be explicitly specified** to override the enhanced default

2. **Enhanced Mode** (default, `--mode enhanced` optional)
   - AI-powered analysis and insights
   - Uses external AI CLI tools (gemini, cursor-agent, codex)
   - Default enhancement level: `standard`
   - Typical rendering time: 1-8 minutes depending on level
   - Automatically falls back to basic mode if AI tools unavailable
   - **The `--mode enhanced` flag is optional** - specifying `--enhancement-level` automatically enables enhanced mode

### Enhancement Levels

When using enhanced mode (the default), you can optionally specify one of three enhancement levels:

| Level | Features | Performance | Best For |
|-------|----------|-------------|----------|
| **summary** | Executive summary only | ~1-2 minutes | Quick AI overview for stakeholders |
| **standard** | Base features + narrative enhancement | ~3-5 minutes | Team reviews and status reports |
| **full** | All AI features (insights, visualizations, analysis) | ~5-8 minutes | Comprehensive documentation and planning |

### Feature Comparison

| Feature | Basic | Enhanced (summary) | Enhanced (standard) | Enhanced (full) |
|---------|-------|-------------------|-------------------|-----------------|
| Markdown generation | ✅ | ✅ | ✅ | ✅ |
| Progress indicators | ✅ | ✅ | ✅ | ✅ |
| Dependency visualization | ✅ | ✅ | ✅ | ✅ |
| Task hierarchies | ✅ | ✅ | ✅ | ✅ |
| Executive summary | ❌ | ✅ | ✅ | ✅ |
| Narrative enhancement | ❌ | ❌ | ✅ | ✅ |
| Priority ranking | ❌ | ❌ | ❌ | ✅ |
| Complexity scoring | ❌ | ❌ | ❌ | ✅ |
| AI insights & recommendations | ❌ | ❌ | ❌ | ✅ |
| Dependency graphs (Mermaid) | ❌ | ❌ | ❌ | ✅ |
| Task grouping suggestions | ❌ | ❌ | ❌ | ✅ |

### Usage Examples

**Default Rendering (Enhanced Standard):**
```bash
# Uses enhanced mode with standard level by default
sdd render my-spec-001

# Equivalent explicit forms
sdd render my-spec-001 --enhancement-level standard
sdd render my-spec-001 --mode enhanced --enhancement-level standard

# With custom output
sdd render my-spec-001 --output docs/team-status.md
```

**Basic Mode (fastest, no AI):**
```bash
# Must explicitly specify --mode basic to override enhanced default
sdd render my-spec-001 --mode basic

# For quick status checks
sdd render my-spec-001 --mode basic --output /tmp/quick-status.md

# When AI features aren't needed
sdd render my-spec-001 --mode basic
```

**Enhanced Mode with Summary:**
```bash
# Specifying --enhancement-level automatically enables enhanced mode
sdd render my-spec-001 --enhancement-level summary

# For stakeholder updates (--mode enhanced is optional, implied by --enhancement-level)
sdd render my-spec-001 --enhancement-level summary --output reports/exec-summary.md
```

**Enhanced Mode with Full Features:**
```bash
# Specifying --enhancement-level automatically enables enhanced mode
sdd render my-spec-001 --enhancement-level full

# Maximum AI analysis with all features (--mode enhanced is implied)
sdd render my-spec-001 --enhancement-level full --output docs/comprehensive-plan.md
```

### Generating Multiple Versions for Comparison

You can generate all three versions to compare outputs:

```bash
#!/bin/bash
SPEC_ID="my-spec-001"

# Generate basic version (fast reference)
sdd render $SPEC_ID --mode basic --output specs/.human-readable/${SPEC_ID}-basic.md

# Generate standard enhanced version (balanced)
sdd render $SPEC_ID --mode enhanced --enhancement-level standard --output specs/.human-readable/${SPEC_ID}-standard.md

# Generate full enhanced version (comprehensive)
sdd render $SPEC_ID --mode enhanced --enhancement-level full --output specs/.human-readable/${SPEC_ID}-full.md

echo "Generated three versions in specs/.human-readable/"
ls -lh specs/.human-readable/${SPEC_ID}-*.md
```

### Choosing the Right Mode

**Use Default (Enhanced Standard) when:**
- ✅ Most common use case - balanced speed and features
- ✅ Team reviews and status reports
- ✅ Narrative flow improves comprehension
- ✅ Weekly/monthly updates
- ✅ Client-facing documentation
- ✅ No special requirements (this is the default!)

**Override to Basic Mode when:**
- You need quick status checks (< 2 seconds)
- Working iteratively with frequent renders (rapid feedback loop)
- AI insights are not needed
- Output will be consumed by automated tools
- CI/CD pipeline integration where speed matters
- Daily standup preparation with time constraints
- Offline environment or AI tools unavailable

**Override to Enhanced Summary when:**
- Stakeholders need high-level AI overview only
- Executive reporting required (lighter than standard)
- Want faster than standard (~1-2 minutes vs ~3-5 minutes)
- AI-generated executive summary is the primary value
- Quick decision-making with AI context

**Override to Enhanced Full when:**
- Comprehensive project planning with deep analysis
- Need AI insights, recommendations, and visualizations
- Visual dependency graphs are valuable
- Archiving/documentation purposes (one-time comprehensive render)
- New team member onboarding (detailed explanations helpful)
- Performance not critical (~5-8 minutes acceptable)
- Maximum information density desired

### Interactive Mode Selection

**When invoked via the sdd-render skill (not direct CLI):**

The skill will proactively ask you which rendering mode you prefer using an interactive question:

```
Which rendering mode would you like to use?
○ Basic (fast, < 2 seconds, no AI)
○ Enhanced - Summary (executive summary, ~1-2 minutes)
○ Enhanced - Standard (recommended, balanced, ~3-5 minutes) ← default
○ Enhanced - Full (comprehensive analysis, ~5-8 minutes)
```

**Benefits of interactive selection:**
- No need to remember command-line flags
- Clear explanation of each option's tradeoffs
- Visual comparison of performance vs features
- Can choose "Other" to specify custom CLI parameters
- Default option clearly marked (Enhanced Standard)

**When to skip the question:**
If you already know which mode you want, you can specify it in your initial request:
- "Render with basic mode"
- "Render with full AI enhancement"
- "Generate all three versions for comparison"

The skill will respect your explicit request and skip the interactive question.

### AI Tooling

Enhanced mode uses external CLI tools for AI processing:

**Tool Priority Order:**
1. **gemini** (pro) - Primary for strategic analysis and summaries
2. **cursor-agent** (composer-1) - Secondary for repository-wide context
3. **codex** (gpt-5-codex) - Tertiary for code-level insights (disabled by default)

**Automatic Fallback:**
- System detects available tools automatically
- Tries tools in priority order
- Falls back to basic rendering if no AI tools available
- Configurable via `.claude/ai_config.yaml` (`sdd-render.tools` and `sdd-render.models`)

### Performance Considerations

**Rendering Times:**
- Basic: < 2 seconds (deterministic, no network calls)
- Enhanced (summary): ~1-2 minutes (one AI call for executive summary)
- Enhanced (standard): ~3-5 minutes (summary + narrative enhancement)
- Enhanced (full): ~5-8 minutes (all AI features, multiple analysis passes)

**Network Requirements:**
- Basic mode: No network required
- Enhanced mode: Requires AI tool availability and API access
- Offline fallback: Enhanced mode falls back to basic if tools unavailable

**Cost Considerations:**
- Basic mode: No API costs
- Enhanced mode: AI tool usage may incur API costs depending on configured tools
- Full enhancement level uses the most AI tokens

---

## Output Samples

### Spec Header

```markdown
# User Authentication System

**Spec ID:** user-auth-2025-10-24-001
**Status:** in_progress (15/23 tasks, 65%)
**Estimated Effort:** 45 hours
**Complexity:** High

## Description

Implement a secure user authentication system with JWT tokens, role-based access control, and session management.

## Objectives

- Secure password hashing with bcrypt
- JWT token generation and validation
- Role-based access control middleware
- Session management and refresh tokens
- Account lockout after failed attempts
```

### Phase with Tasks

```markdown
## Phase 2: Authentication Service (5/8 tasks, 62%)

**Purpose:** Implement core authentication logic
**Risk Level:** Medium
**Estimated Hours:** 18

### Tasks

#### ✅ task-2-1: Create AuthService class
**File:** src/services/authService.ts
**Estimated:** 3 hours
**Status:** completed
**Completed:** 2025-10-24 14:30:15

**Changes:**
Implement user registration with password hashing, add login method with JWT generation, include password validation logic

**Reasoning:** Centralizes authentication logic

**Blocks:** task-2-2, task-2-3

---

#### 🔄 task-2-2: Implement JWT middleware
**File:** src/middleware/auth.ts
**Estimated:** 2 hours
**Status:** in_progress

**Changes:**
Create Express middleware for JWT verification, add token expiration checking, handle invalid token responses

**Reasoning:** Protects API routes

**Depends on:** task-2-1 ✅
**Blocks:** task-2-3, task-2-4, task-2-5

---

#### ⏳ task-2-3: Add role-based authorization
**File:** src/middleware/rbac.ts
**Estimated:** 2.5 hours
**Status:** pending

**Changes:**
Create role checking middleware, define permission mappings, add route-level access control

**Reasoning:** Enables fine-grained access control

**Blocked by:** task-2-2 🔄
```

### Verification Steps

```markdown
#### verify-2-1: Verify authentication flow
**Type:** integration
**Estimated:** 1 hour

**Commands:**
```bash
npm test -- auth.integration.spec.ts
```

**Expected Outcome:**
All authentication tests pass, JWT token format is valid, protected routes reject invalid tokens
```

### Before/After Comparison

**JSON Input:**
```json
{
  "id": "task-2-1",
  "type": "task",
  "title": "Create AuthService class",
  "status": "completed",
  "metadata": {
    "file_path": "src/services/authService.ts",
    "estimated_hours": 3,
    "changes": "Implement user registration with password hashing",
    "reasoning": "Centralizes authentication logic"
  },
  "dependencies": {
    "blocks": ["task-2-2", "task-2-3"]
  }
}
```

**Rendered Output:**
```markdown
#### ✅ task-2-1: Create AuthService class
**File:** src/services/authService.ts
**Estimated:** 3 hours
**Status:** completed

**Changes:**
Implement user registration with password hashing

**Reasoning:** Centralizes authentication logic

**Blocks:** task-2-2, task-2-3
```

---

## CLI Tools Reference

### Core Commands

**Default Rendering (Enhanced Standard):**
```bash
sdd render {spec-id}
```
Renders a JSON spec with AI-enhanced narrative to markdown in the default location (`specs/.human-readable/`). Uses enhanced mode with standard level by default.

**Basic Mode (Fast, No AI):**
```bash
sdd render {spec-id} --mode basic
```
Quick rendering without AI features for speed-critical scenarios. Must explicitly specify `--mode basic` to override the enhanced default.

**Full AI Enhancement:**
```bash
sdd render {spec-id} --enhancement-level full
```
Maximum AI analysis with insights, visualizations, and recommendations. The `--mode enhanced` flag is optional - it's automatically enabled when you specify `--enhancement-level`.

**Custom Output Path:**
```bash
sdd render {spec-id} --output {path}
sdd render {spec-id} -o {path}
```
Specify where to save the rendered markdown file

**Specify Specs Directory:**
```bash
sdd render {spec-id} --path {specs-dir}
```
Use when specs are not in the default location

**Render from File Path:**
```bash
sdd render /path/to/spec-file.json
```
Directly render a JSON file by providing its full path

### Command Options

**Available Options:**

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--mode` | | Rendering mode: `basic` (fast, no AI) or `enhanced` (AI features). Optional - automatically set to `enhanced` when `--enhancement-level` is specified. | `enhanced` (with `standard` level) |
| `--enhancement-level` | | AI enhancement level: `summary`, `standard`, or `full`. Automatically enables `enhanced` mode. | `standard` |
| `--output` | `-o` | Output file path | `specs/.human-readable/{spec-id}.md` |
| `--path` | | Specs directory path | Auto-discovery |
| `--verbose` | `-v` | Show detailed output | Off |
| `--debug` | | Show debug information | Off |

**Key Options Explained:**

- `--mode basic` - Explicitly disables AI features for fast rendering (< 2 seconds). Must be specified to override enhanced default.
- `--mode enhanced` - Enables AI features (default, can be omitted). Automatically enabled when `--enhancement-level` is specified.
- `--enhancement-level summary` - Executive summary only (~1-2 minutes). Automatically enables enhanced mode.
- `--enhancement-level standard` - Balanced AI features (default, ~3-5 minutes). Automatically enables enhanced mode.
- `--enhancement-level full` - All AI features including visualizations (~5-8 minutes). Automatically enables enhanced mode.

### Examples

**Render with default settings (enhanced standard):**
```bash
sdd render user-auth-2025-10-24-001
# Uses: mode=enhanced (default), level=standard (default) (~3-5 minutes)
```

**Fast render without AI (basic mode):**
```bash
sdd render user-auth-2025-10-24-001 --mode basic
# Must explicitly specify --mode basic to override enhanced default
# Quick status check (< 2 seconds)
```

**Executive summary only:**
```bash
sdd render user-auth-2025-10-24-001 --enhancement-level summary
# Automatically enables enhanced mode (~1-2 minutes)
```

**Full AI analysis:**
```bash
sdd render user-auth-2025-10-24-001 --enhancement-level full
# Automatically enables enhanced mode (~5-8 minutes)
```

**Render to custom location:**
```bash
sdd render user-auth-2025-10-24-001 --output docs/auth-plan.md
# Default enhanced standard mode with custom path
```

**Basic mode to custom location (fast):**
```bash
sdd render user-auth-2025-10-24-001 --mode basic --output /tmp/quick-status.md
# Speed-optimized with custom output
```

**Render with verbose output:**
```bash
sdd render user-auth-2025-10-24-001 --verbose
# Shows: Total tasks, output size, processing time, AI tool used
```

**Render from specific specs directory:**
```bash
sdd render my-spec-001 --path /projects/myapp/specifications
```

**Render and view immediately:**
```bash
sdd render my-spec-001 && less specs/.human-readable/my-spec-001.md
```

**Generate multiple versions for comparison:**
```bash
# Basic (fast reference)
sdd render my-spec-001 --mode basic -o specs/.human-readable/my-spec-001-basic.md

# Standard (default, balanced)
sdd render my-spec-001 -o specs/.human-readable/my-spec-001-standard.md

# Full (comprehensive)
sdd render my-spec-001 --enhancement-level full -o specs/.human-readable/my-spec-001-full.md
```

---

## Workflow Examples

### Example 1: Weekly Progress Report

**Situation:** Need to generate a progress report for the weekly team meeting

**When to use this approach:**
- ✓ Regular team meetings require status updates
- ✓ Spec has been updated recently (tasks completed, status changed)
- ✓ Need to track progress over time with dated reports
- ✓ Team members prefer markdown over JSON

**Decision checklist:**
- **Spec updated?** → Yes → Render will show current progress
- **Need comparison?** → Keep previous week's report for comparison
- **Multiple projects?** → Batch render all active specs (see Example 3)
- **Presentation format?** → Consider PDF conversion (see Example 2)

**Steps:**

1. **Render current spec:**
```bash
sdd render user-auth-2025-10-24-001 -o reports/week-$(date +%Y-%m-%d).md
```

2. **Review the output:**
```bash
less reports/week-2025-10-24.md
```

3. **Share with team:**
```bash
# Copy to shared docs folder
cp reports/week-2025-10-24.md /shared/team-docs/

# Or email directly
mail -s "Weekly Progress" team@company.com < reports/week-2025-10-24.md
```

**Output includes:**
- Overall progress percentage
- Completed tasks this week
- Upcoming tasks
- Any blockers

**Why this approach works:**
- Timestamped filenames create historical record
- Custom output path keeps reports organized
- Markdown format is email-friendly and readable in any text editor

### Example 2: Client Status Update

**Situation:** Client wants to see project progress in readable format

**Steps:**

1. **Render spec to client docs:**
```bash
sdd render mobile-app-2025-09-15-001 --output client/project-status-$(date +%B).md
```

2. **Convert to PDF** (optional, requires pandoc):
```bash
pandoc client/project-status-October.md -o client/project-status-October.pdf
```

3. **Send to client:**
- Markdown is readable in email or GitHub
- PDF is professional and printable

### Example 3: Onboarding New Developer

**Situation:** New developer joins and needs to understand project scope

**Steps:**

1. **Render all active specs:**
```bash
for spec in specs/active/*.json; do
  spec_id=$(basename $spec .json)
  sdd render $spec_id
done
```

2. **Create index document:**
```bash
ls specs/.human-readable/ > docs/project-index.txt
```

3. **Point developer to documentation:**
- All specs are now in readable format
- Developer can browse and understand scope
- No need to parse JSON manually

### Example 4: Pre-Planning Review

**Situation:** Before starting implementation, review the spec structure

**When to use this approach:**
- ✓ New spec just created with `Skill(sdd-toolkit:sdd-plan)`
- ✓ Want to verify structure before beginning work
- ✓ Looking for dependency issues or circular references
- ✓ Assessing scope and task breakdown quality

**Decision checklist:**
- **New spec?** → Always review before implementation starts
- **Complex dependencies?** → Look for dependency visualization in output
- **Team review?** → Share rendered version for feedback
- **Issues found?** → Hand off to `Skill(sdd-toolkit:sdd-plan)` to modify

**Steps:**

1. **Render the spec:**
```bash
sdd render api-redesign-2025-10-01-001 --verbose
```

2. **Review for issues:**
- Check dependency chains (look for circular dependencies)
- Verify phase organization (logical progression?)
- Look for missing tasks (gaps in implementation?)
- Identify potential blockers (tasks with no dependencies marked?)

3. **Make adjustments** (if needed):
- Use `Skill(sdd-toolkit:sdd-plan)` to update spec
- Re-render to verify changes
```bash
sdd render api-redesign-2025-10-01-001
```

**Why this approach works:**
- Human-readable format makes structural issues obvious
- Verbose mode shows additional diagnostics
- Iterative review-modify-verify cycle ensures quality
- Catches planning issues before implementation begins

### Example 5: Archiving Completed Project

**Situation:** Project is complete, need permanent documentation

**Steps:**

1. **Render final version:**
```bash
sdd render user-dashboard-2025-08-01-001 --output archive/user-dashboard-final-$(date +%Y-%m-%d).md
```

2. **Create summary document:**
```bash
echo "# User Dashboard Project - Completed $(date +%Y-%m-%d)" > archive/README.md
echo "" >> archive/README.md
echo "See user-dashboard-final-*.md for complete specification" >> archive/README.md
```

3. **Archive the spec:**
- Move JSON to specs/completed/
- Keep markdown in permanent docs
- Commit to git for history

### Example 6: Comparing Enhancement Levels

**Situation:** Evaluating AI enhancement value or choosing the right level for your workflow

**When to use this approach:**
- ✓ First time using AI enhancements (want to see differences)
- ✓ Deciding which level to use for regular workflows
- ✓ Demonstrating AI capabilities to stakeholders
- ✓ Benchmarking rendering performance
- ✓ Creating documentation at multiple detail levels

**Decision checklist:**
- **Evaluating features?** → Generate all three to compare side-by-side
- **Performance testing?** → Time each mode with `time` command
- **Choosing default?** → Try all levels once, then stick with preferred
- **Multiple audiences?** → Keep multiple versions (basic for developers, full for stakeholders)

**Steps:**

1. **Generate all three versions:**
```bash
#!/bin/bash
SPEC_ID="user-auth-2025-10-24-001"

echo "Generating basic version (no AI)..."
time sdd render $SPEC_ID --mode basic \
  --output specs/.human-readable/${SPEC_ID}-basic.md

echo "Generating standard version (default AI)..."
time sdd render $SPEC_ID --enhancement-level standard \
  --output specs/.human-readable/${SPEC_ID}-standard.md

echo "Generating full version (maximum AI)..."
time sdd render $SPEC_ID --enhancement-level full \
  --output specs/.human-readable/${SPEC_ID}-full.md

echo "All versions generated!"
```

2. **Compare file sizes and render times:**
```bash
ls -lh specs/.human-readable/${SPEC_ID}-*.md

# Example output:
# -rw-r--r-- 1 user user  45K Oct 24 10:15 user-auth-2025-10-24-001-basic.md     (1.2s)
# -rw-r--r-- 1 user user  78K Oct 24 10:16 user-auth-2025-10-24-001-standard.md (58s)
# -rw-r--r-- 1 user user 120K Oct 24 10:17 user-auth-2025-10-24-001-full.md     (92s)
```

3. **Review each version:**
```bash
# Quick scan of basic version
less specs/.human-readable/${SPEC_ID}-basic.md

# Review standard enhancements
less specs/.human-readable/${SPEC_ID}-standard.md

# Examine full AI features
less specs/.human-readable/${SPEC_ID}-full.md
```

4. **Compare specific sections using diff:**
```bash
# Compare basic vs standard
diff specs/.human-readable/${SPEC_ID}-basic.md \
     sp

…(truncated)