Progress Documentation Skill

Generate comprehensive progress documentation files with tiered detail levels for work sessions, implementations, and project milestones.

Usage

/progress-documentation                    # Document current session to ~/user_docs
/progress-documentation "Feature X"        # Document specific work
/progress-documentation --output ./docs    # Custom output directory (override)

Default Output Location

All progress documentation is saved to ~/user_docs/ - a centralized, device-wide location that persists across projects.

~/user_docs/
├── trophy-testing-infrastructure-setup_2026-02-03_1115.md
├── auth-system-implementation_2026-02-03_1430.md
└── database-migration-postgres-to-mysql_2026-02-03_0900.md

Why centralized?

• Documentation persists even if project directories are deleted
• Easy to search across all work sessions
• Single location for all progress reports
• Works across different projects and codebases

Document Structure

The generated documentation follows a tiered detail approach:

┌─────────────────────────────────────┐
│       EXECUTIVE SUMMARY             │  ← High Level (30 seconds)
│   Key outcomes, status, usage       │
├─────────────────────────────────────┤
│       MEDIUM-LEVEL DETAIL           │  ← Medium Level (5 minutes)
│   What was built, components,       │
│   files changed, methods used       │
├─────────────────────────────────────┤
│       LOW-LEVEL DETAIL              │  ← Low Level (deep dive)
│   Architecture, code examples,      │
│   configs, troubleshooting          │
└─────────────────────────────────────┘

Output Format

Filename Convention

{descriptive-name}_{YYYY-MM-DD}_{HHMM}.md

Examples:

• trophy-testing-infrastructure-setup_2026-02-03_1115.md
• auth-system-implementation_2026-02-03_1430.md
• database-migration-postgres-to-mysql_2026-02-03_0900.md

Document Template

# {Project/Feature Name}

**Date:** {Month Day, Year} | {Time}
**Project:** {Project context}
**Status:** {Complete | In Progress | Blocked}

---

## Executive Summary

{2-3 sentence overview of what was accomplished}

### Key Outcomes

| Component | Status | Location |
|-----------|--------|----------|
| {Item 1}  | {Status} | {Path/URL} |
| {Item 2}  | {Status} | {Path/URL} |

### Immediate Usage

\`\`\`bash
# Quick start commands
{command 1}
{command 2}
\`\`\`

---

## Medium-Level Detail

### What Was Built

{Paragraph describing the implementation}

### Components Created

| Component | Purpose |
|-----------|---------|
| {Name}    | {Description} |

### Files Modified/Created

**Created:**
- `path/to/file.ext` - Description

**Modified:**
- `path/to/file.ext` - What changed

**Deleted:**
- `path/to/file.ext` - Why removed

### Installation/Setup Method

{Step-by-step installation or setup process}

---

## Low-Level Detail

### Architecture

\`\`\`
directory/
├── file1.ext
├── file2.ext
└── subdirectory/
    └── file3.ext
\`\`\`

### Code Examples

{Language-specific code snippets with explanations}

### Configuration Files

{Full config file contents with annotations}

### Verification Commands

\`\`\`bash
# How to verify the work
{verification command}
\`\`\`

### Troubleshooting

| Issue | Solution |
|-------|----------|
| {Problem} | {Fix} |

---

## References

- **Repo/Location**: {path}
- **Documentation**: {path}
- **Related Work**: {links}

---

## Next Steps

1. {Action item 1}
2. {Action item 2}
3. {Action item 3}

---

*Document generated by Claude Code session on {Date}*

Workflow Steps

Step 1: Gather Session Context

Collect information about the work performed:

• What was the goal?
• What components were created/modified?
• What was the outcome?
• What commands/tools were used?

Step 2: Determine Output Location

Default: Use centralized ~/user_docs/

# Ensure centralized directory exists
mkdir -p ~/user_docs

# Verify location
ls -la ~/user_docs/

Override with --output flag for project-specific docs if needed:

/progress-documentation --output ./docs/progress

Step 3: Generate Timestamp

date "+%Y-%m-%d_%H%M"
# Output: 2026-02-03_1115

Step 4: Write Document

Structure content in three tiers:

1. Executive Summary (High Level)
   • Status table with key outcomes
   • Immediate usage commands
   • 30-second overview
2. Medium-Level Detail
   • What was built (prose description)
   • Component tables
   • File change lists
   • Installation method
3. Low-Level Detail
   • Full architecture diagrams
   • Code examples with syntax highlighting
   • Complete configuration files
   • Troubleshooting tables
   • Verification commands

Step 5: Verify and Confirm

# Check file was created
ls -la {output_path}

# Show line count
wc -l {output_path}

Best Practices

Content Guidelines

Writing Tips

1. Executive Summary
   • Lead with outcomes, not process
   • Use tables for scannable status
   • Include copy-paste commands
2. Medium Detail
   • Explain the "what" and "why"
   • List all files touched
   • Show installation/setup steps
3. Low Detail
   • Include full code snippets
   • Document all configuration
   • Add troubleshooting for known issues
   • Include verification steps

File Organization

Centralized Location (Default):

~/user_docs/                              # Device-wide progress docs
├── trophy-testing-infrastructure-setup_2026-02-03_1115.md
├── auth-system-implementation_2026-02-03_1430.md
├── database-migration_2026-02-02_0900.md
└── feature-x-implementation_2026-02-01_1400.md

Project-Specific (Optional Override):

project/docs/
├── progress/                    # Project progress documentation
├── architecture/                # System design docs
└── guides/                      # How-to guides

Example: Infrastructure Setup Documentation

This skill was created from documenting the Trophy Testing Infrastructure setup:

Session Goal: Install MCP tree-sitter server and everything-claude-code plugin

Document Created: trophy-testing-infrastructure-setup_2026-02-03_1115.md

Structure:

• Executive Summary: Plugin status, MCP server status, usage commands
• Medium Detail: Components built, files created/modified/deleted, installation method
• Low Detail: Full architecture, parser dataclasses, workflow phases, language-specific examples, troubleshooting table

Integration with Other Skills

• /codemap-template - Generate CODEMAP.md for architecture documentation
• /trophy-workflow - Document trophy testing implementations
• /checkpoint - Save verification state for later reference

Part of Everything Claude Code