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

Output Destination Decision

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:

# 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)":

   sdd render {spec-id} --mode basic
   # ~2 seconds
   

   If user chose "Enhanced - Summary":

   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):

   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":

   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":

   # 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:

See the 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:

**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:

sdd render my-spec-001
# Creates: specs/.human-readable/my-spec-001.md

Custom Output Path:

sdd render my-spec-001 --output docs/current-project.md
# Creates: docs/current-project.md

Specify Specs Directory:

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:

Feature Comparison

Usage Examples

Default Rendering (Enhanced Standard):

# 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):

# 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:

# 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:

# 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:

#!/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

# 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

## 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

#### 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:

#### ✅ 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):

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):

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:

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:

sdd render {spec-id} --output {path}
sdd render {spec-id} -o {path}

Specify where to save the rendered markdown file

Specify Specs Directory:

sdd render {spec-id} --path {specs-dir}

Use when specs are not in the default location

Render from File Path:

sdd render /path/to/spec-file.json

Directly render a JSON file by providing its full path

Command Options

Available Options:

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):

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

Fast render without AI (basic mode):

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:

sdd render user-auth-2025-10-24-001 --enhancement-level summary
# Automatically enables enhanced mode (~1-2 minutes)

Full AI analysis:

sdd render user-auth-2025-10-24-001 --enhancement-level full
# Automatically enables enhanced mode (~5-8 minutes)

Render to custom location:

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):

sdd render user-auth-2025-10-24-001 --mode basic --output /tmp/quick-status.md
# Speed-optimized with custom output

Render with verbose output:

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

Render from specific specs directory:

sdd render my-spec-001 --path /projects/myapp/specifications

Render and view immediately:

sdd render my-spec-001 && less specs/.human-readable/my-spec-001.md

Generate multiple versions for comparison:

# 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:

sdd render user-auth-2025-10-24-001 -o reports/week-$(date +%Y-%m-%d).md

2. Review the output:

less reports/week-2025-10-24.md

3. Share with team:

# 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:

sdd render mobile-app-2025-09-15-001 --output client/project-status-$(date +%B).md

2. Convert to PDF (optional, requires pandoc):

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:

for spec in specs/active/*.json; do
  spec_id=$(basename $spec .json)
  sdd render $spec_id
done

2. Create index document:

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:

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

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:

sdd render user-dashboard-2025-08-01-001 --output archive/user-dashboard-final-$(date +%Y-%m-%d).md

2. Create summary document:

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:

#!/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:

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:

# 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:

# Compare basic vs standard
diff specs/.human-readable/${SPEC_ID}-basic.md \
     sp

…(truncated)