resolve

# doc-sentinel:resolve Process accumulated drift warnings from `.doc-sentinel-drift.json`. For each warning, verify whether the doc actually drifted, fix it if so, or dismiss if it is a false positive. ## Phase 1: Load Drift Queue ```bash cat .doc-sentinel-drift.json 2>/dev/null || echo "No drift warnings pending" ``` If the file is empty or missing, report "No drift warnings to resolve" and exit. ## Phase 2: Deduplicate and Group Group warnings by doc file. Multiple source changes may affect the same doc — process them together for coherent updates. Example grouping: ``` ARCHITECTURE.md - src/routes/auth.ts changed (commit abc123) - src/routes/users.ts changed (commit def456) docs/api.md - src/controllers/payments.ts changed (commit abc123) ``` Present the grouped summary and total count before proceeding. ## Phase 3: Triage Each Group For each doc file with drift warnings: ### 3a: Read Current State Read the doc file and the changed source files to understand what actually changed. ### 3b: Classify the Drift Determine what kind of drift occurred: | Classification | Description | Action | |---------------|-------------|--------| | **Path moved** | Source file was renamed or moved | Update path references in doc | | **API changed** | Function signatures, endpoints, or interfaces changed | Update API documentation | | **Config changed** | Env vars, ports, or settings changed | Update config references | | **Structure changed** | Directories added/removed, module reorganized | Update codemap/architecture sections | | **Behavioral change** | Logic changed but interface stayed the same | Update descriptions if they mention specific behavior | | **False positive** | Doc references the file but the relevant content did not change | Dismiss | ### 3c: Apply Fix or Dismiss **For real drift:** - Read the doc section that references the changed code - Read the new state of the source code - Update the doc to reflect the current reality - Keep the same writing style and level of detail as the surrounding content - If unsure about intent, add a `<!-- TODO: verify -->` comment rather than guessing **For false positives:** - Record as dismissed (remove from queue) - No changes needed ## Phase 4: Commit Fixes After processing all groups: ```bash # Stage only modified doc files git add <fixed-doc-files> git commit -m "docs: resolve documentation drift from recent changes Updated docs to reflect code changes detected by doc-sentinel: - <brief summary of fixes>" ``` Use the `docs:` commit prefix to prevent the post-commit hook from re-triggering on this commit. ## Phase 5: Clear Drift Queue ```bash # Remove the drift file — it is session-scoped rm -f .doc-sentinel-drift.json ``` ## Phase 6: Report Print resolution summary: ``` doc-sentinel: resolved N drift warning(s) Fixed: - ARCHITECTURE.md — updated 2 path references - docs/api.md — updated endpoint documentation Dismissed (false positives): - README.md — logo path unchanged despite src/ changes Remaining: - None (all warnings resolved) ``` If any warnings could not be resolved automatically (require human judgment about intent), list them separately under "Needs Review" with specific questions. ## Rules - Always read both the doc and the source before making changes - Preserve the existing writing style — match tone, detail level, and formatting - Never remove documentation sections wholesale — update them - Use `docs:` commit prefix to avoid hook feedback loops - If a doc file has >5 drift warnings from a single commit, consider whether the doc needs a broader rewrite rather than point fixes — dispatch a `drift-resolver` agent for complex cases - Delete `.doc-sentinel-drift.json` after processing, even if some warnings were dismissed - If doc-sync or inkwell is also installed, do not duplicate their work — sentinel fixes references and accuracy, not content generation