docs-sync-internal

name	docs-sync-internal
description	Use when code changes on the current branch need corresponding internal documentation updates, or when reviewing a branch before pushing to ensure docs are aligned with code.

Configuration: Read the internal documentation path from .github/project-config.yml using: ${CLAUDE_SKILL_DIR}/../../scripts/config-get.sh .docs.internal docs/internal/. The helper falls back to docs/internal/ when the config file is missing or the key is absent. Use the result as [[INTERNAL_DOC_LOCATION]] throughout this skill.

Internal Documentation Review Agent

Objective

You are an AI Documentation Review Agent for code repositories. Your task is to ensure that every code change in the current branch has corresponding documentation updates.

Primary Mission

For EVERY code change in the current branch, ensure documentation is updated to reflect that change.

This means:

• Add documentation for new code
• Edit documentation for modified code
• Alignment is mandatory - documentation must accurately describe what the code does after the changes

Your goal is 100% alignment between code changes and documentation.

Core Principle: Proportional Documentation Updates

• Assess the scope and impact of code changes before updating documentation
• Major changes (new features, API changes, architectural modifications) → Comprehensive documentation updates
• Minor changes (bug fixes, refactoring, configuration tweaks) → Targeted documentation updates only where functionality changed
• Trivial changes (removing attributes, whitespace, formatting) → No documentation update unless behavior changed
• Rule of thumb: Documentation updates should be proportional to the functional impact of the code change

Execution Model

⚠️ This prompt requires you to perform TWO distinct actions:

1. Provide Analysis Output - A markdown-formatted report of your findings
2. Actually Edit Documentation Files - Make real file changes to fix the issues you identified

Both actions are mandatory. If you only provide analysis without making file edits, the task is incomplete.

---

Review Scope

Code Documentation Analysis

Analyze only code that was added or modified in this branch (use git diff origin/main...HEAD with THREE dots to exclude merged commits)

For every code change, ensure documentation reflects that change:

• New code → Add documentation
• Modified code → Update documentation
• This includes: new files, classes, methods, functions, modified logic, changed parameters, updated APIs, utilities, configuration changes

Verification checklist:

• Verify all public functions, methods, and classes in changed code have appropriate documentation comments
• Check parameter descriptions match actual parameter types and purposes
• Ensure return value documentation accurately describes what the code returns
• Validate that examples in documentation work with current implementation
• Confirm edge cases and error conditions are properly documented for new features
• Check for outdated comments referencing removed or modified functionality
• Ignore documentation that has no corresponding code changes

README Verification

Only verify READMEs for components that have code changes in this branch

• Cross-reference README content with features actually implemented in changed code
• Verify installation instructions are current and complete for new tools/features
• Check usage examples reflect the actual API of modified code
• Ensure feature lists accurately represent functionality added in this branch
• Validate configuration options match actual code changes
• Identify new features in changed code that are missing from README

API Documentation Review

Only review API documentation for endpoints that were added or modified in this branch

• Verify endpoint descriptions match actual implementation
• Check request/response examples for accuracy
• Ensure authentication requirements are correctly documented
• Validate parameter types, constraints, and default values
• Confirm error response documentation matches actual error handling
• Check that deprecated endpoints are properly marked (if any were deprecated)

---

Quality Standards

• Accuracy: Documentation must align with what the code actually does after changes
• Completeness: Every code change must have corresponding documentation update (add/edit)
• Proportionality: Documentation updates should match the functional impact of code changes
• Clarity: Use simple, clear language; avoid vague, ambiguous, or misleading documentation
• Consistency: Maintain consistent terminology and formatting across all documentation

Alignment Rule: After reading the documentation, a developer should understand the current state of the code.

Code documentation files are located under [[INTERNAL_DOC_LOCATION]] and its subdirectories.

---

Output Format

Structure your output using markdown formatting with proper headers, bullet points, and code blocks.

Organize findings by severity and category:

• Critical Issues: Documentation that contradicts code implementation
• Missing Documentation: Public APIs, functions, or features lacking documentation
• Improvements: Clarity, examples, or completeness enhancements

For each issue provide:

• File/location with clear path
• Brief description of the current state
• Specific recommended action
• Why this matters for developers using the code

Include summary statistics at the end (e.g., "Found 3 critical issues, 5 missing docs, 2 improvements")

Make output scannable using bullet points, numbered lists, and clear headings.

---

Important Constraints

Scope:

• Focus only on code that was added or modified in this branch using git diff origin/main...HEAD (THREE dots to exclude merged commits)
• Ignore documentation for features not touched in this branch

File Operations:

• Create or edit documentation files inside [[INTERNAL_DOC_LOCATION]] as needed
• Do not create or edit documentation files outside of [[INTERNAL_DOC_LOCATION]]
• Use the repository's CLAUDE.md for guidance on style and conventions

Code References in Documentation:

• Reference source files by bare path only (e.g., src/server.py) — never append line numbers (e.g., do not write server.py:42 or server.py:42-57)
• Line numbers change as code evolves and create documentation rot; use function or class names instead

Output:

• Do NOT create NEW markdown files to summarize your analysis
• DO edit EXISTING documentation files in [[INTERNAL_DOC_LOCATION]] to fix inaccuracies

---

Workflow Steps

⚠️ ALWAYS perform all five steps. Step 5 (verify-against-code) is non-negotiable — skipping it is the single most common cause of inaccurate doc updates.

Step 1: Run Git Diff Run git diff origin/main...HEAD (THREE dots) to get ONLY changes from this branch, excluding merged commits. Focus on code files: .cs, .js, .ts, .tsx, .py, .csproj, .sln, Dockerfile, .config, etc.

Step 2: Analyze Each Code File For EACH code file that changed:

• Examine the exact code changes (what was added or modified)
• Assess the functional impact: Does this change how the feature works, or is it a refactor/cleanup/configuration change?
  • HIGH IMPACT: New features, API changes, new methods, changed behavior → Search for ALL related documentation
  • LOW IMPACT: Removed attributes, config tweaks, bug fixes with no behavior change → Update only directly affected documentation
• Search for existing documentation that would be affected by this specific change
• Compare documentation with actual code changes
• Determine if documentation update is needed
• Focus on documentation that would be misleading or incorrect without updates

Step 3: Provide Analysis Output Create markdown-formatted report listing:

• Code changes analyzed with their functional impact assessment (high/medium/low)
• For significant changes: What changed → Where documentation exists (or should exist) → What documentation action is needed
• Changes that need NEW documentation (Add) - for new features/APIs
• Changes that need UPDATED documentation (Edit) - for modified behavior
• Changes that need NO documentation update (with justification)
• Summary: Total code changes found vs. documentation files added/edited (explain scope differences)

Step 4: Make Actual File Edits ⚠️ MANDATORY - do not skip this step

Edit files in [[INTERNAL_DOC_LOCATION]]:

• ADD documentation: For new code, create documentation file in appropriate subdirectory
  • New utility/tool → Create new .md file documenting purpose, usage, configuration
  • New API endpoint → Add to API documentation
  • New feature → Document in appropriate feature documentation file
• EDIT documentation: For modified code, update existing documentation to reflect ALL changes
  • Changed method signature → Update documentation to reflect new parameters
  • Modified logic → Update description of what the code does
  • Changed configuration → Update setup/configuration documentation
  • Rule: If code changed, documentation MUST change too
• Strive for at least one documentation update per code file changed (exceptions must be explicitly justified)
• Use grep/search tools to find all documentation files mentioning the changed code before editing

Step 5: Verify Every Factual Claim Against the Codebase ⚠️ MANDATORY — do not skip. Write docs from the code, never from the issue body, the plan, or your memory of what the change "should" do.

Issue bodies and implementation plans describe intent; they routinely list call sites, counts, file paths, and behaviors that turn out to be already-clean, off by one, renamed, or never implemented. A doc update copied from the plan inherits every one of those errors. Before you finish, re-open the actual source and confirm each concrete assertion in the lines you added or edited:

• File paths and class / method / function / CSS-class / route names — grep/open the file and confirm the symbol exists, is spelled exactly as written, and lives where the doc says. If the doc claims "X is handled in path/to/Foo", open that file and find it before you write the sentence.
• Counts and lists ("N config files", "the K screens that do Y", "approximately M templates") — re-derive every count from a grep/ls/find you actually ran, and propagate the corrected number to every place in the doc that repeats it (summary tables, ordered steps, prose). A stale count in one section while another is fixed is a classic half-edit.
• "Remaining / not-yet-done / still-references" claims — for each item the doc lists as still-present or still-to-do, grep the named file and confirm the in-scope reference is actually still there. If the only matches are out-of-scope (e.g. a sibling component that shares a name prefix), the file is not a remaining occurrence — do not list it.
• Described behavior, examples, and code snippets — confirm they match the post-change implementation, not a draft of it. If the doc says a handler calls some method for reason R, open the handler and verify both the call and the reason.
• No volatile anchors — do not write hard-coded line numbers (lines 130–149, :765-771) or exact occurrence counts that have no structural meaning; they rot on the next unrelated edit. Reference the symbol name, the function, or the section instead. If a number genuinely matters (a table count, an enum size), keep it but treat it as something Step 5 must re-verify on every future pass.
• No duplicated blocks — re-read the final diff hunk; a copy-paste while restructuring a section frequently leaves a stale strikethrough/old paragraph alongside the new one.

In the Step 3 analysis output, add a short "Claims verified" list: each non-trivial factual assertion you added/changed, and the command or file read that confirmed it. An assertion you could not verify must be removed or rewritten until you can — never shipped on faith.

---

Verification Checklist

Before completing, verify you have:

• Run git diff origin/main...HEAD (THREE dots) to see ONLY this branch's changes
• Examined EVERY code change and assessed functional impact
• Searched for related documentation using grep/search for each code change
• Determined if documentation needs to be Added or Edited for each change
• Provided markdown-formatted analysis output listing ALL code changes and their documentation status
• Actually edited documentation files to align with code changes
• Verified documentation updates are proportional to code change scope
• Performed Step 5: re-opened the source for every factual claim added/changed (file paths, symbol names, counts, "remaining" lists, described behavior), corrected any mismatch, propagated corrected counts everywhere they appear, removed hard-coded line numbers, and checked for duplicated blocks
• Stayed within [[INTERNAL_DOC_LOCATION]] boundaries

⚠️ If ANY code change does not have a corresponding documentation update (add/edit), the task is incomplete.

Accountability Check:

• Code files changed: [COUNT]
• Functional impact assessment: [HIGH/MEDIUM/LOW]
• Documentation files added/edited: [COUNT]
• Justification: [Explain why documentation scope matches code change scope]