gh-ninthspace-claude-code-marketplace-sdd/commands/story-document.md

# /sdd:story-document

## Meta
- Version: 2.0
- Category: story-management
- Complexity: medium
- Purpose: Generate comprehensive documentation for implemented story features

## Definition
**Purpose**: Analyze story implementation and generate user, technical, and testing documentation with examples and inline code comments.

**Syntax**: `/sdd:story-document [story_id]`

## Parameters
| Parameter | Type | Required | Default | Description | Validation |
|-----------|------|----------|---------|-------------|------------|
| story_id | string | No | current active | Story ID to document (format: STORY-YYYY-NNN) | Must be valid story ID |

## INSTRUCTION: Generate Story Documentation

### INPUTS
- story_id: Story to document (defaults to current active story)
- Story file from `/docs/stories/development/` or `/docs/stories/review/`
- Implemented code files referenced in story
- Project context from `/docs/project-context/`

### PROCESS

#### Phase 1: Story Location and Validation
1. **DETERMINE** which story to document:
   - IF story_id provided: USE specified story
   - IF no story_id: FIND current active story in `/docs/stories/development/`
2. **LOCATE** story file:
   - CHECK `/docs/stories/development/[story-id].md`
   - CHECK `/docs/stories/review/[story-id].md`
   - CHECK `/docs/stories/qa/[story-id].md`
3. IF story not found:
   - EXIT with error message
   - SUGGEST using `/sdd:project-status` to find valid story IDs

#### Phase 2: Story Analysis
1. **READ** story file to extract:
   - Feature title and description (from "What & Why" section)
   - Implementation details (from "Technical Notes")
   - Success criteria (acceptance criteria)
   - Test cases defined
   - UI/UX considerations
   - Integration points

2. **SCAN** codebase to identify implementation:
   - LOCATE files referenced in progress log
   - IDENTIFY new/modified components, functions, classes
   - EXTRACT public APIs and interfaces
   - MAP dependencies and imports
   - NOTE configuration files affected

3. **LOAD** project context:
   - `/docs/project-context/technical-stack.md` - Framework conventions
   - `/docs/project-context/coding-standards.md` - Documentation style
   - `/docs/project-context/development-process.md` - Doc requirements

#### Phase 3: Documentation Generation

**Generate Multiple Documentation Types:**

1. **USER DOCUMENTATION** (if user-facing feature):
   - CREATE `/docs/features/[feature-name].md`
   - INCLUDE:
     * Feature overview and purpose
     * How to use the feature (step-by-step)
     * Common use cases with examples
     * Troubleshooting guide
     * Screenshots or diagrams (note if needed)

2. **TECHNICAL DOCUMENTATION**:
   - CREATE `/docs/technical/[feature-name].md`
   - INCLUDE:
     * Architecture overview
     * Component/module descriptions
     * API reference (if applicable)
     * Configuration options
     * Integration guide
     * Data flow diagrams (note if needed)

3. **TESTING DOCUMENTATION**:
   - CREATE `/docs/testing/[feature-name].md`
   - INCLUDE:
     * How to test the feature
     * Test scenarios covered
     * Known edge cases
     * Performance benchmarks (if applicable)
     * Manual testing checklist

4. **INLINE CODE DOCUMENTATION**:
   - ADD framework-appropriate comments:
     * PHP: PHPDoc blocks
     * JavaScript/TypeScript: JSDoc/TSDoc
     * Python: Docstrings
     * [DISCOVERED language]: Appropriate style
   - DOCUMENT:
     * Public functions and methods
     * Component props/parameters
     * Complex logic explanations
     * Configuration constants
     * Event handlers and callbacks

5. **CODE EXAMPLES**:
   - CREATE `/docs/examples/[feature-name]/`
   - INCLUDE:
     * Basic usage snippets
     * Configuration examples
     * Integration examples
     * Common patterns
     * Copy-paste ready code

#### Phase 4: Update Existing Documentation
1. **UPDATE** project-level docs:
   - `/README.md` - Add feature to feature list (if user-facing)
   - `/docs/api.md` - Add API endpoints (if applicable)
   - `/docs/configuration.md` - Add new config options
   - `/CHANGELOG.md` - Document changes
   - `/docs/migration.md` - Add migration guide (if breaking changes)

2. **PRESERVE** existing content:
   - APPEND new sections rather than replace
   - MAINTAIN existing formatting style
   - KEEP version history intact

#### Phase 5: Story Documentation Update
1. **UPDATE** story file with documentation summary:
   ```markdown
   ## Documentation

   ### Generated Documentation
   - User Guide: /docs/features/[feature-name].md
   - Technical: /docs/technical/[feature-name].md
   - Testing: /docs/testing/[feature-name].md
   - Examples: /docs/examples/[feature-name]/

   ### Updated Documentation
   - README.md: Added feature to feature list
   - CHANGELOG.md: Documented changes for v[version]

   ### Inline Documentation
   - Added PHPDoc blocks to [count] functions
   - Documented [count] component props
   - Added complex logic comments in [file:line]

   ### Documentation Status
   - [x] User documentation complete
   - [x] Technical documentation complete
   - [x] Testing documentation complete
   - [x] Inline code comments added
   - [x] Examples created
   - [ ] Screenshots needed (optional)
   - [ ] Diagrams needed (optional)
   ```

2. **CHECK** documentation completion criteria:
   - [ ] All public APIs documented
   - [ ] User-facing features have user guide
   - [ ] Complex logic has inline comments
   - [ ] Examples demonstrate key use cases
   - [ ] Configuration options documented
   - [ ] Breaking changes documented in migration guide

#### Phase 6: Completion Summary
1. **DISPLAY** documentation summary:
   ```
   ✅ Documentation Generated
   ═══════════════════════════════════

   Story: [STORY-YYYY-NNN] - [Title]

   DOCUMENTATION CREATED:
   ✓ User Guide: /docs/features/[feature-name].md
   ✓ Technical: /docs/technical/[feature-name].md
   ✓ Testing: /docs/testing/[feature-name].md
   ✓ Examples: /docs/examples/[feature-name]/

   DOCUMENTATION UPDATED:
   ✓ README.md (feature list)
   ✓ CHANGELOG.md (version notes)
   [✓ Migration guide (if breaking changes)]

   INLINE DOCUMENTATION:
   ✓ [count] functions documented
   ✓ [count] components documented
   ✓ [count] complex logic comments

   DOCUMENTATION DEBT:
   [- Screenshots recommended for user guide]
   [- Sequence diagram would help explain flow]

   Story Updated: Documentation section added
   ```

2. **SUGGEST** next steps:
   ```
   💡 NEXT STEPS:
   1. Review generated documentation for accuracy
   2. Add screenshots/diagrams if noted
   3. /sdd:story-review [story-id]    # Move to code review
   4. Share docs with team for feedback
   ```

### OUTPUTS
- `/docs/features/[feature-name].md` - User-facing documentation
- `/docs/technical/[feature-name].md` - Technical documentation
- `/docs/testing/[feature-name].md` - Testing documentation
- `/docs/examples/[feature-name]/` - Code examples
- Updated project documentation (README, CHANGELOG, etc.)
- Inline code comments in implementation files
- Updated story file with documentation summary

### RULES
- MUST analyze story to understand what was built
- MUST generate appropriate doc types based on feature type
- MUST use framework-appropriate inline documentation style
- MUST update story file with documentation summary
- SHOULD create user docs for user-facing features
- SHOULD include code examples for all public APIs
- SHOULD update project README and CHANGELOG
- NEVER remove existing documentation
- ALWAYS preserve existing formatting style
- MUST check all public APIs are documented

## Documentation Templates

### User Documentation Template
```markdown
# [Feature Name]

## Overview
[What the feature does and why it exists]

## Prerequisites
[What user needs before using this feature]

## Getting Started

### Quick Start
[Simplest possible example to get started]

### Step-by-Step Guide
1. [First step with clear instructions]
2. [Second step]
3. [Continue...]

## Usage Examples

### Example 1: [Common Use Case]
[Description of scenario]

```[language]
[Code example]
```

[Expected result]

### Example 2: [Another Use Case]
[Description]

```[language]
[Code example]
```

## Configuration

### Available Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| [option] | [type] | [default] | [what it does] |

### Configuration Example
```[format]
[Example configuration]
```

## Troubleshooting

### Common Issues

#### [Issue 1]
**Problem**: [Description]
**Solution**: [How to fix]

#### [Issue 2]
**Problem**: [Description]
**Solution**: [How to fix]

## Related Features
- [Related feature 1]
- [Related feature 2]

## Additional Resources
- [Link to technical docs]
- [Link to API reference]
```

### Technical Documentation Template
```markdown
# [Feature Name] - Technical Documentation

## Architecture Overview
[High-level architecture description]

## Components

### [Component 1]
**Purpose**: [What it does]
**Location**: [File path]
**Dependencies**: [What it depends on]

**Public Interface**:
```[language]
[Key methods/functions]
```

**Usage**:
```[language]
[How to use it]
```

### [Component 2]
[Same structure]

## Data Flow
[Description of how data flows through the system]

```
[Diagram or flowchart in text/Mermaid format]
```

## API Reference

### [Function/Method Name]
```[language]
[Full signature]
```

**Parameters**:
- `param1` ([type]): [Description]
- `param2` ([type]): [Description]

**Returns**: [Return type and description]

**Throws**: [Exceptions that can be thrown]

**Example**:
```[language]
[Usage example]
```

## Configuration

### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| [VAR] | [Yes/No] | [default] | [what it does] |

### Configuration Files
[List of config files and their purpose]

## Integration Guide

### Integrating with [System/Feature]
[Step-by-step integration instructions]

### Event Hooks
[Available hooks/events for extending functionality]

## Performance Considerations
- [Performance tip 1]
- [Performance tip 2]

## Security Considerations
- [Security concern 1]
- [Security concern 2]

## Testing
[Link to testing documentation]

## Troubleshooting
[Link to user documentation troubleshooting section]
```

### Testing Documentation Template
```markdown
# Testing: [Feature Name]

## Test Coverage Summary
- Unit Tests: [count] tests, [X]% coverage
- Integration Tests: [count] tests
- E2E Tests: [count] tests
- Manual Tests: [count] scenarios

## Running Tests

### All Tests
```bash
[Command to run all tests]
```

### Unit Tests Only
```bash
[Command to run unit tests]
```

### Integration Tests
```bash
[Command to run integration tests]
```

## Test Scenarios

### Scenario 1: [Happy Path]
**Given**: [Initial state]
**When**: [Action taken]
**Then**: [Expected result]

**Test**: [Test file and function name]

### Scenario 2: [Error Case]
**Given**: [Initial state]
**When**: [Action taken]
**Then**: [Expected error handling]

**Test**: [Test file and function name]

## Edge Cases Tested
1. [Edge case 1] - [How it's tested]
2. [Edge case 2] - [How it's tested]

## Known Limitations
- [Limitation 1]
- [Limitation 2]

## Manual Testing Checklist
- [ ] [Manual test step 1]
- [ ] [Manual test step 2]
- [ ] [Verify on different browsers/devices]

## Performance Benchmarks
[If applicable, performance test results]

## Test Data
[How to set up test data or where test fixtures are located]
```

## Examples

### Example 1: Document Current Active Story
```bash
INPUT:
/sdd:story-document

OUTPUT:
→ Finding active story...
→ Located: STORY-2025-003 in /docs/stories/development/
→ Analyzing implemented features...
→ Scanning codebase for TaskManager component...
→ Generating documentation...

✅ Documentation Generated
═══════════════════════════════════

Story: STORY-2025-003 - Task Management System

DOCUMENTATION CREATED:
✓ User Guide: /docs/features/task-management.md
✓ Technical: /docs/technical/task-management.md
✓ Testing: /docs/testing/task-management.md
✓ Examples: /docs/examples/task-management/

DOCUMENTATION UPDATED:
✓ README.md (added to feature list)
✓ CHANGELOG.md (documented for v1.2.0)

INLINE DOCUMENTATION:
✓ 12 functions documented with PHPDoc
✓ 3 Livewire components documented
✓ 5 complex logic sections commented

DOCUMENTATION DEBT:
- Screenshots recommended for user guide
- Consider adding sequence diagram for task lifecycle

Story Updated: Documentation section added

💡 NEXT STEPS:
1. Review generated documentation for accuracy
2. Add screenshots to user guide
3. /sdd:story-review STORY-2025-003    # Move to code review
4. Share docs with team for feedback
```

### Example 2: Document Specific Story
```bash
INPUT:
/sdd:story-document STORY-2025-005

OUTPUT:
→ Locating story: STORY-2025-005...
→ Found in /docs/stories/review/
→ Analyzing authentication implementation...
→ Generating documentation...

✅ Documentation Generated
═══════════════════════════════════

Story: STORY-2025-005 - User Authentication

DOCUMENTATION CREATED:
✓ User Guide: /docs/features/authentication.md
✓ Technical: /docs/technical/authentication.md
✓ Testing: /docs/testing/authentication.md
✓ Examples: /docs/examples/authentication/
✓ Migration Guide: /docs/migration-v2.md (breaking changes)

DOCUMENTATION UPDATED:
✓ README.md (security section)
✓ CHANGELOG.md (v2.0.0 breaking changes)
✓ docs/api.md (auth endpoints)

INLINE DOCUMENTATION:
✓ 8 controller methods documented
✓ 4 middleware classes documented
✓ Security notes added to sensitive functions

Story Updated: Documentation section added

💡 NEXT STEPS:
1. Review security documentation carefully
2. /sdd:story-review STORY-2025-005    # Continue review process
```

### Example 3: API Documentation
```bash
INPUT:
/sdd:story-document STORY-2025-007

OUTPUT:
→ Locating story: STORY-2025-007...
→ Found in /docs/stories/development/
→ Analyzing REST API implementation...
→ Extracting API endpoints and schemas...
→ Generating OpenAPI specification...

✅ Documentation Generated
═══════════════════════════════════

Story: STORY-2025-007 - REST API for Tasks

DOCUMENTATION CREATED:
✓ API Reference: /docs/api/tasks.md
✓ Technical: /docs/technical/api-tasks.md
✓ Testing: /docs/testing/api-tasks.md
✓ OpenAPI Spec: /docs/openapi/tasks.yaml
✓ Postman Collection: /docs/examples/tasks.postman.json

DOCUMENTATION UPDATED:
✓ docs/api.md (added tasks endpoints)
✓ README.md (API section)
✓ CHANGELOG.md (new API endpoints)

INLINE DOCUMENTATION:
✓ 6 API endpoints documented
✓ Request/response schemas defined
✓ Error responses documented

Story Updated: Documentation section added

💡 NEXT STEPS:
1. Test with Postman collection
2. Share OpenAPI spec with frontend team
3. /sdd:story-review STORY-2025-007
```

## Edge Cases

### Story Not Found
- DETECT invalid story ID
- SUGGEST using `/sdd:project-status` to list valid stories
- EXIT with helpful error message

### Story Has No Implementation Yet
- DETECT story in backlog with no code
- WARN that documentation requires implemented code
- SUGGEST using `/sdd:story-implement [id]` first
- EXIT gracefully

### No User-Facing Changes
- DETECT backend-only or infrastructure changes
- SKIP user documentation generation
- FOCUS on technical and testing documentation
- NOTE decision in story update

### Documentation Already Exists
- DETECT existing documentation files
- ASK user: Update existing or create new version?
- IF update: Merge new content with existing
- IF new: Create versioned documentation
- PRESERVE all existing content

### Complex API with Many Endpoints
- DETECT large API surface area
- GENERATE comprehensive API reference
- CREATE OpenAPI/Swagger specification
- ORGANIZE by resource/domain
- PROVIDE Postman/Insomnia collections

## Error Handling
- **Story not found**: Show available stories from `/sdd:project-status`
- **No implementation found**: Guide user to implement first
- **Permission errors**: Report specific file/directory issue
- **Documentation write errors**: Log error, continue with other docs

## Performance Considerations
- Documentation generation typically takes 10-30 seconds
- Inline documentation added via file editing (may take longer for many files)
- Show progress indicators for multi-file operations
- Cache story analysis for session

## Related Commands
- `/sdd:story-implement [id]` - Generate implementation first
- `/sdd:story-review [id]` - Move to code review after documentation
- `/sdd:story-test [id]` - Verify tests before documenting
- `/sdd:project-status` - Find stories to document

## Constraints
- ✅ MUST analyze story to understand implementation
- ✅ MUST generate docs appropriate to feature type
- ✅ MUST use framework-appropriate inline doc style
- ✅ MUST update story with documentation summary
- 📋 SHOULD create user docs for user-facing features
- 🔧 SHOULD include code examples for public APIs
- 💾 MUST preserve existing documentation content
- ⚠️ NEVER remove or replace existing docs without confirmation
- 🧪 MUST document all test scenarios covered