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.4---56**Language: Always interact with the user in 日本語.**78# doc-drift-git-en910**Cross-reference changes within the diff only.** Does not scan all project docs.11Ideal for checking doc update omissions before PR creation.1213## Prerequisites1415- Claude Code environment16- `git`, `gh` CLI1718## Arguments1920- No arguments: Diff between current branch and `origin/develop`21- Branch specified: Compare against specified remote branch (e.g., `origin/main`)2223## Phase 1: Diff Retrieval and Classification24251. `git fetch origin`262. Determine comparison branch (argument provided -> use it / none -> `origin/develop`)273. Get merge base (`git merge-base <comparison-branch> HEAD`)284. Diff file list (`git diff --name-status <merge-base>...HEAD`)295. Commit list (`git log --oneline <merge-base>..HEAD`)306. Classify diff files:31 - **Docs**: `.md`, `.rst`, `.txt` (README, docs/, spec/, etc.)32 - **Code**: Source code, config, migrations, dependency definitions33 - **Other**: Images, binaries, etc. (out of scope)347. Check if both docs and code are included in the diff358. Create tasks with TaskCreate3637## Phase 2: Doc Diff Analysis3839Retrieve diffs for each document, extract added/changed/deleted statements. Identify what they relate to (API, config, structure, etc.).4041## Phase 3: Code Diff Analysis4243Identify code changes that need doc updates. Check criteria in `references/check-criteria.md`.4445## Phase 4: Cross-reference and Drift Detection4647| Pattern | State | Typical severity |48|---------|-------|-----------------|49| Code changed, no doc update | Missing update | Critical to Suggestion depending on impact |50| Doc changed, no code change | Advance update or unnecessary change | Suggestion to Minor |51| Both changed, contradictory | Inconsistency | Critical to Important |52| Both changed, consistent | Normal | — |5354#### Steps551. For each "needs doc update" code change, check if corresponding doc update exists in diff562. For each doc change, check if corresponding code change exists in diff573. For changes in both, verify consistency584. Record drift with specific locations (code file:line and doc file:line)5960## Phase 5: Report Generation61621. Confirm output destination with `AskUserQuestion`:63 - **GitHub Issue** (recommended): `review: Doc drift report (<branch> -> <comparison>, <YYYY-MM-DD>)`64 - **Local MD**: `doc-drift-git-report.md`65 - **Console output**: Print the report directly in the conversation662. Use report format from `templates/report.md`673. Report summary to user6869## Severity Criteria7071| Severity | Criteria |72|----------|----------|73| Critical | API/data model/auth changes without doc updates, or clear contradictions |74| Important | Config/dependency/setup changes without doc updates |75| Suggestion | Minor feature change omissions, doc supplements that improve UX |76| Minor | Wording inconsistencies, outdated version numbers, trivial inaccuracies |7778## Rules7980- **Focus on diff.** Docs and code not in the diff are out of scope81- Never report drift based on guesses. Verify against actual diff82- Show both code-side and doc-side locations for each drift83- Report facts only. Leave fix decisions to the user84- Check surrounding context (full function, callers, etc.) for accuracy85- Always include Critical/Important findings. Include Suggestion/Minor only if clear benefit86- Code comments and docstrings are out of scope87- Track progress with TaskCreate/TaskUpdate
ousiass