Update Docs

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Bring an Antora-based documentation module’s .adoc pages (and its nav.adoc/antora.yml if structure or version changed) up to date with changes already made to the codebase. This skill only edits documentation — it never changes source code, and it never invents documented behavior that isn’t actually in the code.

Purpose

iru-update-docs closes the gap between a code change and a stale documentation site. It reads the actual diff, not just file names, cross-checks every class/method/endpoint it plans to mention against the real current source, and only touches the specific pages that diff actually concerns — leaving the rest of the site untouched. It makes no assumption about a fixed docs path or a fixed set of page names; it discovers the real Antora module(s) present and their real page map fresh each run, which is why it works the same way regardless of which repository it’s invoked in. If a documentation MCP (e.g. Confluence, Notion) is connected, it extends the same diff-driven understanding to that external system too — finding the relevant existing page(s) there first, then showing the user the exact proposed change for approval before anything is written. Before drafting anything against that connector, it checks what its own tools actually expose: if the connector is read-only (search/read only, no create-page/update-page tool), it warns the user by name and skips the external-docs enrichment entirely instead of drafting an update it could never send.

Purpose group

Repository Maintenance

Invocation

/iru-update-docs
/iru-update-docs <git-ref-or-range>

Inputs

Argument Required Description Default

Argument	Required	Description	Default
`git-ref-or-range`	No	A commit, ref, or range (e.g. a tag, `main..HEAD`) to scope the documented diff to.	None — defaults to uncommitted changes plus commits on the current branch not yet on the repository’s base branch (`git diff <base-branch>…HEAD` plus `git diff`).

git-ref-or-range

A commit, ref, or range (e.g. a tag, main..HEAD) to scope the documented diff to.

None — defaults to uncommitted changes plus commits on the current branch not yet on the repository’s base branch (git diff <base-branch>…HEAD plus git diff).

Outputs

Updated .adoc pages reflecting only what the scoped diff actually changed — new/removed/renamed public APIs, behavioral changes, new variants of an existing abstraction, or changed documented commands.
nav.adoc/antora.yml updated only if a page was added, removed, or renamed, or the component version should track a source version bump.
Mermaid diagrams ([mermaid]) or MathJax equations added only where the Antora playbook already has the matching extension wired in, and only where they genuinely clarify a decision process, data flow, or formal definition better than prose.
If no antora.yml existed anywhere in the repository and the user agreed to bootstrap one: a newly scaffolded Antora module (via iru-setup-antora), then the rest of the run proceeds against it.
If a documentation MCP (e.g. Confluence, Notion) is connected and exposes a write (create/update-page) tool: a proposed update to the relevant existing external page(s), sent only after the user reviews and approves the exact change shown to them.
If a documentation MCP is connected but only exposes read tools: an explicit warning naming the connector, and the external-docs enrichment skipped entirely for this run — never a drafted change that couldn’t be sent.
A report naming, per page: what changed in the source that drove the edit and what was updated in the docs — plus pages deliberately left unchanged, any doc gap noticed but left out of scope, and what was sent (or proposed-but-declined) to a connected documentation MCP.
No source code is ever modified.

Execution flow

flowchart TD A[Start /iru-update-docs] --> B{Ref/range argument given?} B -- yes --> C[Scope diff to git diff arg] B -- no --> D["Scope diff to uncommitted changes +\ncommits on current branch not on base branch"] C --> E{Diff empty?} D --> E E -- yes --> E1[Report nothing to document; stop] E -- no --> F[Search repo for antora.yml files] F --> G{Any antora.yml found?} G -- no --> H[Ask user whether to\nbootstrap docs now] H -- declines --> H1[Stop: nothing to update] H -- agrees --> I["Run setup-antora via sub-agent,\nbriefed with the actual diff context"] I --> F G -- yes --> J["Read antora.yml + nav.adoc to build a live\npage map; check playbook for Mermaid/MathJax extensions"] J --> K["Understand changes in code terms: new/removed\nAPIs, behavior changes, new variants"] K --> L["Map changes to affected pages only;\nedit them, verifying every named symbol against real source"] L --> M{"Documentation MCP\nconnected (Confluence, Notion, ...)?"} M -- no --> M1[Skip external doc update] M -- yes --> M1B{Connector exposes\na write tool?} M1B -- read-only only --> M1C["Warn user by name;\nskip external-docs enrichment"] M1B -- write tool available --> M2["Search MCP for relevant existing page(s);\nread current content/structure"] M2 --> M3["Draft proposed update from\nStep 3's diff-driven understanding"] M3 --> M4["Show user exact proposed change;\nAskUserQuestion: send / skip / revise"] M4 -- approved --> M5[Call MCP tool to\nupdate/create the page] M4 -- declined --> M1 M5 --> Q{Node.js + Antora playbook available?} M1 --> Q M1C --> Q Q -- yes --> N[npm install && npx antora;\nfix any build/xref/Mermaid errors] Q -- no --> O[Note build was not locally verified] N --> P["Report per-page changes, unchanged pages,\nnoted doc gaps, and MCP doc outcome"] O --> P

Dependencies

Invokes

Setup Antora — Step 2, conditionally: only when no antora.yml is found anywhere in the repository, and only after asking the user whether to bootstrap Antora documentation now. Run via a sub-agent (the Agent tool) briefed with the actual code-change context, so iru-update-docs itself can resume once scaffolding finishes and continue with the rest of its run against the newly created module.

Invoked by

Code — Step 8, once per run (not per task), invoked directly (not via a sub-agent) once the build, quality, and security gates all pass, so the project’s documentation reflects everything the whole plan changed before the plan is archived.
Also meant to be run directly by a person (or potentially by another skill in a different repository) after code changes have already been made outside the /iru-code flow.

Related agents

None directly — iru-update-docs delegates the conditional iru-setup-antora call in Step 2 to a sub-agent (see Agents), but that is calling a skill through a sub-agent wrapper rather than relying on an agent’s own unique capability, so no agent is listed as a direct dependency here.

Source

SKILL.md on GitHub — the file this page was generated from.