Derive ADRs, rules, PRDs from git commit history. Use when finding doc gaps, detecting unrecorded decisions, deriving conventions from commits, or generating skeleton docs.
Derive ADRs, rules, PRDs from git commit history. Use when finding doc gaps, detecting unrecorded decisions, deriving conventions from commits, or generating skeleton docs.
name
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
--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_*):
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.
## 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]
