Language: Always interact with the user in 日本語.
doc-drift-git-en
Cross-reference changes within the diff only. Does not scan all project docs.
Ideal for checking doc update omissions before PR creation.
Prerequisites
- Claude Code environment
git, gh CLI
Arguments
- No arguments: Diff between current branch and
origin/develop
- Branch specified: Compare against specified remote branch (e.g.,
origin/main)
Phase 1: Diff Retrieval and Classification
git fetch origin- Determine comparison branch (argument provided -> use it / none ->
origin/develop)
- Get merge base (
git merge-base <comparison-branch> HEAD)
- Diff file list (
git diff --name-status <merge-base>...HEAD)
- Commit list (
git log --oneline <merge-base>..HEAD)
- Classify diff files:
- Docs:
.md, .rst, .txt (README, docs/, spec/, etc.)
- Code: Source code, config, migrations, dependency definitions
- Other: Images, binaries, etc. (out of scope)
- Check if both docs and code are included in the diff
- Create tasks with TaskCreate
Phase 2: Doc Diff Analysis
Retrieve diffs for each document, extract added/changed/deleted statements. Identify what they relate to (API, config, structure, etc.).
Phase 3: Code Diff Analysis
Identify code changes that need doc updates. Check criteria in references/check-criteria.md.
Phase 4: Cross-reference and Drift Detection
| Pattern |
State |
Typical severity |
| Code changed, no doc update |
Missing update |
Critical to Suggestion depending on impact |
| Doc changed, no code change |
Advance update or unnecessary change |
Suggestion to Minor |
| Both changed, contradictory |
Inconsistency |
Critical to Important |
| Both changed, consistent |
Normal |
— |
Steps
- For each "needs doc update" code change, check if corresponding doc update exists in diff
- For each doc change, check if corresponding code change exists in diff
- For changes in both, verify consistency
- Record drift with specific locations (code file:line and doc file:line)
Phase 5: Report Generation
- Confirm output destination with
AskUserQuestion:
- GitHub Issue (recommended):
review: Doc drift report (<branch> -> <comparison>, <YYYY-MM-DD>)
- Local MD:
doc-drift-git-report.md
- Console output: Print the report directly in the conversation
- Use report format from
templates/report.md
- Report summary to user
Severity Criteria
| Severity |
Criteria |
| Critical |
API/data model/auth changes without doc updates, or clear contradictions |
| Important |
Config/dependency/setup changes without doc updates |
| Suggestion |
Minor feature change omissions, doc supplements that improve UX |
| Minor |
Wording inconsistencies, outdated version numbers, trivial inaccuracies |
Rules
- Focus on diff. Docs and code not in the diff are out of scope
- Never report drift based on guesses. Verify against actual diff
- Show both code-side and doc-side locations for each drift
- Report facts only. Leave fix decisions to the user
- Check surrounding context (full function, callers, etc.) for accuracy
- Always include Critical/Important findings. Include Suggestion/Minor only if clear benefit
- Code comments and docstrings are out of scope
- Track progress with TaskCreate/TaskUpdate
1---2name: doc-drift-git-en3description: Check doc-code consistency on git diff against remote and generate drift report.4user-invocable: true5---67**Language: Always interact with the user in 日本語.**89# doc-drift-git-en1011**Cross-reference changes within the diff only.** Does not scan all project docs.12Ideal for checking doc update omissions before PR creation.1314## Prerequisites1516- Claude Code environment17- `git`, `gh` CLI1819## Arguments2021- No arguments: Diff between current branch and `origin/develop`22- Branch specified: Compare against specified remote branch (e.g., `origin/main`)2324## Phase 1: Diff Retrieval and Classification25261. `git fetch origin`272. Determine comparison branch (argument provided -> use it / none -> `origin/develop`)283. Get merge base (`git merge-base <comparison-branch> HEAD`)294. Diff file list (`git diff --name-status <merge-base>...HEAD`)305. Commit list (`git log --oneline <merge-base>..HEAD`)316. Classify diff files:32 - **Docs**: `.md`, `.rst`, `.txt` (README, docs/, spec/, etc.)33 - **Code**: Source code, config, migrations, dependency definitions34 - **Other**: Images, binaries, etc. (out of scope)357. Check if both docs and code are included in the diff368. Create tasks with TaskCreate3738## Phase 2: Doc Diff Analysis3940Retrieve diffs for each document, extract added/changed/deleted statements. Identify what they relate to (API, config, structure, etc.).4142## Phase 3: Code Diff Analysis4344Identify code changes that need doc updates. Check criteria in `references/check-criteria.md`.4546## Phase 4: Cross-reference and Drift Detection4748| Pattern | State | Typical severity |49|---------|-------|-----------------|50| Code changed, no doc update | Missing update | Critical to Suggestion depending on impact |51| Doc changed, no code change | Advance update or unnecessary change | Suggestion to Minor |52| Both changed, contradictory | Inconsistency | Critical to Important |53| Both changed, consistent | Normal | — |5455#### Steps561. For each "needs doc update" code change, check if corresponding doc update exists in diff572. For each doc change, check if corresponding code change exists in diff583. For changes in both, verify consistency594. Record drift with specific locations (code file:line and doc file:line)6061## Phase 5: Report Generation62631. Confirm output destination with `AskUserQuestion`:64 - **GitHub Issue** (recommended): `review: Doc drift report (<branch> -> <comparison>, <YYYY-MM-DD>)`65 - **Local MD**: `doc-drift-git-report.md`66 - **Console output**: Print the report directly in the conversation672. Use report format from `templates/report.md`683. Report summary to user6970## Severity Criteria7172| Severity | Criteria |73|----------|----------|74| Critical | API/data model/auth changes without doc updates, or clear contradictions |75| Important | Config/dependency/setup changes without doc updates |76| Suggestion | Minor feature change omissions, doc supplements that improve UX |77| Minor | Wording inconsistencies, outdated version numbers, trivial inaccuracies |7879## Rules8081- **Focus on diff.** Docs and code not in the diff are out of scope82- Never report drift based on guesses. Verify against actual diff83- Show both code-side and doc-side locations for each drift84- Report facts only. Leave fix decisions to the user85- Check surrounding context (full function, callers, etc.) for accuracy86- Always include Critical/Important findings. Include Suggestion/Minor only if clear benefit87- Code comments and docstrings are out of scope88- Track progress with TaskCreate/TaskUpdate
ousiass