Smart Update Docs

Synchronize project documentation with current implementation status, updating completion percentages and recording new best practices.

When to Use This Command

Run this command when you need to:

• Update documentation after completing a development phase or sprint
• Synchronize implementation status documents with actual code state
• Record new best practices, lessons learned, and troubleshooting tips discovered during development

Consider alternatives when:

• You need to create new documentation files rather than update existing ones
• The documentation update is a single typo fix or minor wording change

Quick Start

Configuration

Copy
name: smart-update-docs
type: command
category: documentation

Example Invocation

Copy
claude command:run smart-update-docs --scope phase-3 --update-status

Example Output

Documentation Scan:
  specs/implementation_status.md: found
  specs/phase3_implementation_plan.md: found
  CLAUDE.md: found
  README.md: found

Recent Changes (last 7 days):
  23 commits affecting 47 files
  4 new test files added
  2 new modules implemented

Updates Applied:
  [+] specs/phase3_implementation_plan.md
      - Task 3.1: 60% -> 100% (marked complete)
      - Task 3.2: 0% -> 75% (in progress)
      - Added implementation notes for auth module
  [+] specs/implementation_status.md
      - Phase 3 overall: 45% -> 72%
      - Added 3 new component entries
  [+] CLAUDE.md
      - Added 2 new best practices
      - Updated troubleshooting section
  [+] specs/testing_plan.md
      - Updated test coverage: 67% -> 78%
      - Added 4 new test file references

Summary: 4 files updated, 12 sections modified

Core Concepts

Documentation Sync Overview

Aspect	Details
Status Tracking	Updates completion percentages based on code and test analysis
Git History Mining	Extracts recent changes to identify what documentation needs updating
Best Practices	Captures lessons learned during implementation into documentation
Cross-Reference	Ensures spec documents reference actual implemented file paths
Testing Status	Synchronizes test coverage data with testing plan documents

Documentation Update Workflow

  Trigger Update
       |
       v
  +--------------------+
  | Scan Documentation |---> Find all spec and status files
  +--------------------+
       |
       v
  +--------------------+
  | Analyze Git History|---> Recent commits, changed files
  +--------------------+
       |
       v
  +--------------------+
  | Compare Status     |---> Doc says 60%, code shows 100%
  +--------------------+
       |
       v
  +--------------------+
  | Apply Updates      |---> Percentages, notes, references
  +--------------------+
       |
       v
  +--------------------+
  | Generate Summary   |---> Files changed, sections modified
  +--------------------+

Configuration

Parameter	Type	Default	Description
scope	string	all	Update scope: all, phase-N, readme, testing, or status
update_status	boolean	true	Update completion percentages in status documents
add_practices	boolean	true	Append new best practices discovered during development
since	string	1 week	Time window for git history analysis
dry_run	boolean	false	Show what would be updated without modifying files

Best Practices

1. Update After Every Phase Completion - Run documentation updates at the end of each development phase or sprint. Waiting too long causes documentation to drift so far from reality that updating becomes a major effort.

2. Preserve Original Requirements - When marking spec items as complete, add status indicators but do not delete the original requirement text. The original specification provides context for future maintenance and auditing.

3. Use Consistent Status Indicators - Adopt a standard set of markers across all documents. Using checkmarks, percentages, and status labels consistently makes it easy to scan documents for incomplete work.

4. Cross-Reference Implementation Files - When updating a spec to show a task is complete, add the file path where the implementation lives. This creates a traceable link from requirement to code.

5. Include What Did Not Work - Document failed approaches and their reasons alongside successful implementations. Future developers benefit from knowing why alternative solutions were rejected.

Common Issues

1. Percentage Calculation Inaccurate - The tool counts completed tasks but does not account for task complexity. Weight tasks by estimated effort or use sub-task completion ratios for more accurate progress reporting.

2. Git History Missing Context - Commit messages are too vague to determine which spec items were addressed. Use conventional commit messages with issue references so the tool can map commits to documentation sections.

3. Conflicting Updates Across Branches - Multiple team members update documentation on different branches. Merge documentation updates frequently and use line-level changes rather than full-section rewrites to minimize merge conflicts.