zhongwei/gh-ninthspace-claude-code-marketplace-sdd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d97a70be331ab765e3a939a4d772797f37f783bc
gh-ninthspace-claude-code-m…/commands/story-document.md
Zhongwei Li d97a70be33 Initial commit
2025-11-30 08:44:27 +08:00

17 KiB
Raw Blame History

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

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

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

[Code example]

Configuration

Available Options

Option Type Default Description
[option] [type] [default] [what it does]

Configuration Example

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

[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]

[Full signature]

Parameters:

  • param1 ([type]): [Description]
  • param2 ([type]): [Description]

Returns: [Return type and description]

Throws: [Exceptions that can be thrown]

Example:

[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

[Command to run unit tests]

Integration Tests

[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

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

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
Reference in New Issue View Git Blame Copy Permalink