# Align Documentation > Align Documentation - Skill: `intense-visions/align-documentation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add intense-visions/align-documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/intense-visions/align-documentation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: Intense-Visions (https://skillmd.com/u/intense-visions) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/intense-visions/align-documentation --- # Align Documentation > Sync documentation with code after implementation changes. Keep AGENTS.md, API docs, and architecture docs accurate by mapping code changes to their documentation impact. ## When to Use - After completing a feature implementation (post-merge or post-commit) - After fixing a bug that changes observable behavior - After a refactoring that renames, moves, or restructures code - When detect-doc-drift reports findings that need fixing - When `on_post_feature` or `on_post_merge` triggers fire - NOT during active development — wait until the code is stable - NOT for creating documentation for a brand-new project (use validate-context-engineering for initial setup) - NOT for fixing code — this skill only changes documentation ## Process ### Phase 1: Detect — Identify What Changed 1. **Run `git diff` against the appropriate baseline.** Choose the baseline based on context: - After a feature: diff against the branch point (`git diff main...HEAD`) - After a bug fix: diff against the commit before the fix - After a refactoring: diff against the commit before refactoring started - Periodic sync: diff against the last documentation sync commit 2. **Extract the list of changed files.** For each changed file, note: - File path (current and previous if renamed/moved) - Nature of change (added, modified, deleted, renamed) - Changed exports (new, removed, renamed, signature changed) - Changed behavior (different return values, new error types, new side effects) 3. **Run `harness check-docs`** to identify any documentation that already has broken references due to the changes. ### Graph-Enhanced Context (when available) When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context: - `query_graph` — find `documents` edges pointing to nodes changed in this diff - `get_impact` — auto-suggest which docs need updating after code changes Replaces manual doc-to-code correlation. Fall back to file-based commands if no graph is available. ### Pipeline Context (when orchestrated) When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`: - If `pipeline` field exists: read `DocPipelineContext` from it - Read `pipeline.driftFindings` to know which fixes to apply (pre-classified by safety) - If `pipeline.fixBatch` is set, apply only those specific fixes rather than running full detection - Write applied fixes as `DocFix[]` back to `pipeline.fixesApplied` - This enables the convergence loop to track fix verification status - If `pipeline` field does not exist: behave exactly as today (standalone mode) No changes to the skill's interface or output format — the pipeline field is purely additive. ### Phase 2: Map — Connect Code Changes to Documentation For each changed file, identify all documentation that references it: **AGENTS.md sections:** - Knowledge map entries that reference the file path - Architecture descriptions that mention the module - Constraint documentation that references the file's layer or patterns - Onboarding guides that walk through the file **API documentation:** - JSDoc/TSDoc comments in the changed files themselves - Generated API doc pages that pull from the changed files - README examples that demonstrate the changed functions - Tutorial or guide pages that use the changed code **Architecture documentation:** - Diagrams that include the changed module - Data flow descriptions that reference the changed functions - Layer descriptions that list the changed file - Dependency documentation that references the changed imports **Inline code comments:** - Comments in OTHER files that reference the changed file or function - TODO comments that reference the changed behavior - Workaround comments that may no longer apply after the change ### Phase 3: Generate — Draft Documentation Updates For each affected documentation location: 1. **Draft the specific text change.** Show the old text and the new text. Keep the existing style and tone — documentation updates should be invisible in terms of voice. 2. **Preserve context.** When updating a section, do not just change the specific reference — read the surrounding paragraph and ensure it still makes sense. A renamed function may require updating the explanatory text around it, not just the function name. 3. **Handle deletions carefully.** When code is deleted, do not just delete the documentation reference. Consider whether the section should be removed entirely, replaced with information about the replacement, or noted as deprecated. 4. **Add new sections when needed.** If a new module was added, draft a complete documentation section following the existing AGENTS.md structure and style. ### Phase 4: Validate — Verify Documentation Accuracy 1. **Run `harness check-docs`** to verify all links and references resolve correctly after the updates. 2. **Cross-check each update against the actual code.** Read the updated documentation and verify every claim by looking at the code. Documentation that is wrong is worse than documentation that is missing. 3. **Verify no orphaned references remain.** Search documentation files for any remaining references to old names, old paths, or deleted features. 4. **Run `harness fix-drift`** to catch any remaining simple drift issues that manual review missed. ### Graph Refresh If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate: ``` harness scan [path] ``` Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results. 5. **Commit the documentation update.** Use a commit message that references the original change: "docs: update AGENTS.md for notification service refactoring" or "docs: sync API docs after auth module rename." ## What to Update ### AGENTS.md Knowledge Map - File paths and module names (renamed or moved files) - Module purpose descriptions (changed responsibilities) - Constraint descriptions (new or changed rules) - Relationship descriptions (new or changed dependencies) - Gotcha sections (resolved gotchas, new gotchas) ### Inline Code Comments - Function/class doc comments in the changed files (JSDoc, TSDoc) - Comments in other files that reference the changed code - TODO comments that reference completed or changed work - Workaround comments for issues that may now be resolved ### Documentation Pages (docs/) - API reference pages that describe changed functions - Architecture pages that diagram changed modules - Tutorial and guide pages that demonstrate changed code - Getting-started guides if entry points changed - Changelog entries for user-facing changes ## Harness Integration - **`harness check-docs`** — Run before and after updates. Identifies broken references and validates that all documentation links resolve. - **`harness fix-drift`** — Auto-fix simple drift issues (broken file paths, renamed references) after manual review confirms correctness. - **`harness fix-drift --json`** — Machine-readable output for tracking what was auto-fixed. - **`harness validate`** — Run after documentation changes to verify overall project health is maintained. ## Success Criteria - `harness check-docs` passes with zero errors after documentation updates - Every code change from the diff has been mapped to its documentation impact - All file paths in documentation match current file locations - All function/class names in documentation match current code - All behavioral descriptions in documentation match current implementation - Documentation updates are committed with clear references to the triggering code change - No orphaned references to old names, paths, or deleted features remain ## Rationalizations to Reject | Rationalization | Why It Is Wrong | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | "The code change is small, so docs probably do not need updating" | A single function signature change changes the contract for every consumer. Map every code change to its documentation impact regardless of diff size. | | "I updated the main reference -- the other mentions can wait" | Orphaned references in AGENTS.md and tutorials actively mislead agents and developers. Phase 4 requires verifying no orphaned references remain. | | "I will match the new documentation to what I think the code does" | Phase 4 requires cross-checking each update against the actual code. Documentation that is wrong is worse than documentation that is missing. | | "The existing doc style is inconsistent, so I will improve it while aligning" | Follow the existing style. Documentation alignment is about accuracy, not style improvement. Style changes should be a separate effort. | ## Examples ### Example: Syncing docs after a module rename **Code change:** `src/services/mailer.ts` renamed to `src/services/email-service.ts`. Functions `sendMail()` and `formatMailBody()` renamed to `sendEmail()` and `formatEmailBody()`. **Documentation impact map:** ``` AGENTS.md:34 — "mailer.ts handles email delivery" → update path and description AGENTS.md:78 — "Use sendMail() for all outbound email" → update function name docs/api.md:156 — sendMail() API reference → update name and import path docs/arch.md:45 — architecture diagram lists "mailer" → update to "email-service" src/controllers/user-controller.ts:12 — comment "// delegates to mailer" → update ``` **Updates applied:** - AGENTS.md: updated two sections with new file path and function names - docs/api.md: updated function reference and import example - docs/arch.md: updated module name in architecture description - src/controllers/user-controller.ts: updated inline comment **Validation:** `harness check-docs` passes. All references resolve. Commit: "docs: sync documentation after mailer rename to email-service" ### Example: Syncing docs after adding error handling **Code change:** `createUser()` in `src/services/user-service.ts` now throws `ValidationError` instead of returning `null` on invalid input. **Documentation impact map:** ``` docs/api.md:89 — "Returns null if validation fails" → update to describe thrown error AGENTS.md:52 — No mention of error handling → add note about ValidationError src/services/user-service.ts:15 — JSDoc @returns tag → update, add @throws tag ``` **Updates applied:** - docs/api.md: replaced "returns null" with "throws ValidationError" and added example - AGENTS.md: added note about error handling pattern in user-service section - JSDoc: updated @returns, added @throws ValidationError **Validation:** `harness check-docs` passes. Commit: "docs: update documentation for createUser error handling change" ## Escalation - **When you cannot determine what documentation is affected:** Run `harness check-docs` for automated detection. For manual analysis, search all `.md` files and code comments for the old name/path. If the change is large, use detect-doc-drift first to get a complete inventory. - **When documentation is in an external system (wiki, Confluence):** Document the needed change and flag it for manual update. Include the specific text that needs changing and the correct replacement. - **When the code change is so large that documentation needs a rewrite:** Break the documentation update into sections. Update one section at a time, validating after each. Do not attempt a full rewrite in one pass. - **When you disagree with the existing documentation style:** Follow the existing style. Documentation alignment is about accuracy, not style improvement. Style changes should be a separate, deliberate effort.