git-derive-docs

When to Use This Skill

Context

• Current branch: !git branch --show-current
• Commit count: !git rev-list --count HEAD
• Latest commit: !git log --format='%ai' --max-count=1
• Existing rules: !find . -path '*/.claude/rules/*' -maxdepth 3 -type f
• Existing docs: !find . -maxdepth 3 \( -path '*/docs/prds/*' -o -path '*/docs/adrs/*' -o -path '*/docs/prps/*' \) -type f
• Commit conventions sample: !git log --format='%s' --max-count=20

Parameters

• --rules: Derive .claude/rules/ from commit patterns (conventions, naming, tooling)
• --prd: Detect features implemented without requirements documentation
• --adr: Detect architecture decisions made without decision records
• --prp: Detect implementation work done without planning documentation
• --all: Run all detection categories (default if no flags specified)
• --since=<date>: Limit analysis to commits after date (e.g., --since=2025-01-01)
• --depth=<N>: Number of commits to analyze (default: 200)
• --dry-run: Report findings without creating files
• --refinements: Focus on plan refinement detection (approach changes, reverts, rework)

Your task

Analyze git commit history to identify documentation gaps.

Step 1: Determine Scope and gather history signals

Parse flags to determine which categories to analyze. Default to --all if no category flags provided.

Run the data-gathering script once. It aggregates file-naming patterns (top directories + added-file extensions), tallies commit-convention frequency (CONV_<type>=<count>), and detects dependency/migration signals (DEP_MANIFEST_COMMITS, MIGRATION_COMMITS, REFACTOR_COMMITS), plus existing doc coverage (DOCS_*):

bash "${CLAUDE_SKILL_DIR}/scripts/git-derive-docs.sh" --home-dir "$HOME" --project-dir "$(pwd)" --depth "$DEPTH" --since "$SINCE"

Parse STATUS= and ISSUES: from the output. Pass --since (precedence) or --depth (default 200). The structured rollup replaces the raw git log pipes the rest of this skill used to run inline.

Step 2: Rules Detection (if --rules or --all)

The script already aggregated the convention signals: read the CONV_<type> frequency tally (commit-message conventions), the DIR_<n>=<path> / EXT_<name>=<count> entries (file-naming patterns), and DOCS_* (existing coverage). Cross-reference with existing .claude/rules/ to avoid duplicates — the script reports current rule-file counts under DOCS__CLAUDE_RULES.

Step 3: PRD Detection (if --prd or --all)

Find features built without requirements documentation:

# Feature commits without PRD references
git log --format='%H %s' -$DEPTH | grep -iE '^[a-f0-9]+ feat' | head -20

# Large additions (new feature directories)
git log --diff-filter=A --name-only --format='%H---' -$DEPTH | awk '/^[a-f0-9]+---/{hash=$0;next}{if(hash)print hash,$0}'

# Cluster commits by directory to find feature groups
git log --format='' --name-only -$DEPTH | grep -oP '^[^/]+/[^/]+' | sort | uniq -c | sort -rn | head -15

Cross-reference with existing docs/prds/ to avoid duplicates.

Step 4: ADR Detection (if --adr or --all)

Find architecture decisions without documentation. The script already detected the deterministic dependency/migration signals — read DEP_MANIFEST_COMMITS (commits touching dependency manifests), MIGRATION_COMMITS (migrate/switch/ replace/upgrade language), and REFACTOR_COMMITS (restructure/reorganize/ redesign language) from Step 1's output. For the specific commit subjects behind a non-zero count, drill in with a targeted log:

# Infrastructure-change commits (for context behind the signal counts)
git log --oneline -$DEPTH -- 'docker*' 'Dockerfile*' '.github/workflows/*' 'terraform/*' 'k8s/*'

Cross-reference with existing docs/adrs/ (the script reports the count under DOCS__DOCS_ADRS) to avoid duplicates. Judging whether a flagged commit represents a real architectural decision worth an ADR stays with you.

Step 5: PRP Detection (if --prp or --all)

Find implementation work without planning docs:

# Sequential implementation commits
git log --format='%s' -$DEPTH | grep -iE 'step [0-9]|part [0-9]|phase [0-9]|wip'

# Multi-file coordinated changes
git log --format='%H %s' -$DEPTH | while read hash msg; do
  files=$(git diff-tree --no-commit-id --name-only -r "$hash" 2>/dev/null | wc -l)
  [ "$files" -gt 5 ] && echo "$files files: $msg"
done | sort -rn | head -10

# Feature branches
git branch -a --format='%(refname:short)' | grep -iE 'feat|feature|implement'

Cross-reference with existing docs/prps/ to avoid duplicates.

Step 6: Plan Refinement Detection (if --refinements or --all)

Find approach changes not documented:

# Reverts and reworks
git log --format='%H %s' -$DEPTH | grep -iE 'revert|redo|rework|rethink|redesign'

# "Actually" commits (approach corrections)
git log --format='%H %s' -$DEPTH | grep -iE 'actually|instead|better approach|try different'

# High-churn files (approach unclear, iterated heavily)
git log --format='' --name-only -$DEPTH | sort | uniq -c | sort -rn | head -15

# Short-lived implementations (created then significantly changed)
git log --format='%H %ai %s' -$DEPTH | grep -i 'refactor' | head -10

Step 7: Generate Report

Compile findings into a prioritized report:

## Documentation Gaps Report

Generated: <date>
Commits analyzed: <N>
Period: <first> to <last>

### High Priority
[Items with strong evidence and high impact]

### Medium Priority
[Items with moderate evidence]

### Low Priority
[Minor patterns or old history items]

Step 8: Create Documents (unless --dry-run)

For each accepted finding:

Rules: Create/update .claude/rules/<name>.md with:

• Convention description
• Evidence from commits
• Examples

PRD/ADR/PRP: Generate skeleton documents in appropriate directories. If blueprint commands are available, suggest using:

• /blueprint:prd for PRDs
• /blueprint:adr for ADRs
• /blueprint:prp-create for PRPs

Step 9: Summary

Report:

• Number of gaps found per category
• Documents created (if not --dry-run)
• Suggested next steps

See Also

• document-detection skill (blueprint-plugin) for conversation-based detection
• /docs:generate --changelog for changelog generation from commits