laurigates/git-derive-docs

When to Use This Skill

| Use this skill when... | Use the alternative when... | |---|---| | Mining git history for undocumented rules, PRDs, ADRs, or PRPs | Use git-cli-agentic for one-shot porcelain queries against the history | | Generating skeleton documentation from commit-message patterns | Use git-commit-workflow to set conventions BEFORE the history accrues | | Detecting architectural decisions or feature work that was never recorded | Use github-issue-writing to file fresh issues from the gaps you find | | Auditing whether .claude/rules/ and docs/{prds,adrs,prps}/ reflect actual practice | Use git-triage to triage the open issues and PRs surfaced during the audit |

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 .claude/rules/ -maxdepth 1 -type f
• Existing docs: !find docs/prds/ docs/adrs/ docs/prps/ -maxdepth 1 -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

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

Set analysis depth:

# Use --since if provided, otherwise --depth (default 200)
git log --format='%H %s' --since="$SINCE" 2>/dev/null || git log --format='%H %s' -$DEPTH

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

Analyze commit patterns for implicit conventions:

# File naming patterns
git log --diff-filter=A --name-only --format='' -$DEPTH | sort | uniq -c | sort -rn | head -20

# Commit message conventions
git log --format='%s' -$DEPTH | grep -oP '^\w+(\([^)]+\))?' | sort | uniq -c | sort -rn

# Tool/config patterns
git log --oneline -$DEPTH -- '*.config.*' 'tsconfig*' 'biome.json' '.eslintrc*' 'pyproject.toml' 'Cargo.toml'

# Test file conventions
git log --diff-filter=A --name-only --format='' -$DEPTH -- '*.test.*' '*.spec.*' '*_test.*' | head -20

Cross-reference with existing .claude/rules/ to avoid duplicates.

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:

# Dependency changes
git log --oneline -$DEPTH -- 'package.json' 'Cargo.toml' 'pyproject.toml' 'go.mod'

# Migration/replacement commits
git log --format='%H %s' -$DEPTH | grep -iE 'migrate|switch|replace|upgrade|from .+ to'

# Infrastructure changes
git log --oneline -$DEPTH -- 'docker*' 'Dockerfile*' '.github/workflows/*' 'terraform/*' 'k8s/*'

# Refactors indicating architectural shifts
git log --format='%H %s' -$DEPTH | grep -iE 'refactor.*to|restructure|reorganize|redesign'

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

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