Documentation Update Skill

Phase 1 — Execute and Parse the Diff

1. Run the {git_diff_command} argument as a shell command (or read the provided file/patch) to obtain the diff output.
2. Parse the diff to extract:
   • Files added, removed, or modified.
   • Functions, classes, endpoints, models, or configuration keys that changed.
   • New dependencies or removed ones.
   • Renamed or moved modules.
   • Breaking changes vs. additive changes.

Phase 2 — Map Changes to Documentation Files

For each changed code unit, determine which doc file(s) it affects:

If no existing doc covers a new topic, note that a new file may be needed and include it in the preview.

Phase 3 — Investigate Existing Documentation

1. Check whether docs/ exists in the workspace.
2. Read docs/SUMMARY.md (if present) to understand the current doc structure.
3. Read each doc file identified in Phase 2 to understand its current content before proposing changes.

Phase 4 — Preview All Proposed Changes

For each documentation file that requires an update:

1. State the file path.
2. Describe in plain language why this file needs updating (link it explicitly to the diff).
3. Show a diff-style preview of the exact text that will be added, changed, or removed:

- old line or section
+ new line or section

4. Ask the user to confirm before writing anything.

Example prompt: "I plan to make the following changes to docs/endpoints.md. Shall I proceed?"

Phase 5 — Apply Confirmed Changes

After confirmation for each file:

1. Write only the confirmed changes.
2. Preserve all existing content that is unaffected by the diff.
3. Maintain consistent Markdown style (headings, tables, code fences, Mermaid diagrams) with the rest of the file.
4. Update docs/SUMMARY.md if any file was added, removed, or had its top-level section titles changed.

Phase 6 — Consistency Review

After all writes are complete:

• All modified files still have valid internal Markdown structure.
• All cross-links between docs are intact.
• docs/SUMMARY.md reflects the current state of the docs/ hierarchy.
• No placeholder text (TODO, ..., <fill in>) was left behind.
• No information was duplicated across files.

Decision Rules for "Should This Doc Be Updated?"

Apply these rules in order. Stop at the first match.

1. Directly referenced — the diff modifies code that is explicitly described in the doc (e.g., a function documented in modules.md). → Update.

2. Structurally affected — the diff adds or removes a module, endpoint, model, or configuration key that belongs in the doc's scope. → Update.

3. Behavior change — the diff changes observable behavior that a user or integrator would need to know about (return values, error codes, environment variables, CLI flags). → Update the relevant usage/setup/endpoint doc.

4. Internal refactor only — the diff is a pure internal refactor with no visible behavioral change and no new/removed public surface. → Do not update (unless the doc currently describes the internals being refactored and the description would become inaccurate).

5. Test or tooling change only — the diff only touches test files, CI configuration, or developer tooling with no user-facing impact. → Do not update (unless docs/contribution.md explicitly covers the changed workflow).

Writing Standards

Anti-patterns to Avoid

• ❌ Writing to a doc file before showing a preview and receiving confirmation.
• ❌ Updating a file whose content is unrelated to the diff.
• ❌ Adding content "just in case" or to make the docs feel more complete.
• ❌ Creating a new file when an existing file already covers the topic.
• ❌ Forgetting to update docs/SUMMARY.md after adding or removing a doc.
• ❌ Leaving cross-links broken after renaming or removing a section.
• ❌ Duplicating information that already lives in another doc file.
• ❌ Skipping the consistency review in Phase 6.