Commit Documentor

Reviews the commits the user just made, decides whether they change anything the documentation claims to describe, drafts the doc edits, and — only after the user approves — commits the approved files locally.

Draft within the requested scope before seeking approval. Commit only reviewed files when the user has authorized that action. Never push; prepare publication instructions for the user. Preserve existing authorization across turns.

Two modes

Set by mode in the config, chosen once during first-run setup:

• repo (default) — docs live in a separate repository. Publishing means local branch → scoped commit. The user handles push/PR publication.
• local — the project has no separate docs repo, so this skill creates and maintains docs inside this repo under local_docs.docs_root. Publishing means a commit on the current branch, scoped to the docs paths only. It never pushes in local mode — the user pushes docs along with the rest of their work.

Everything else — the doc index, the rules, the classification logic, the approval gate — is identical in both modes. scripts/doc-repo.sh handles the difference; run scripts/doc-repo.sh mode if you need to know which one is active.

First run: setup

If scripts/doc-repo.sh config exits 3, nothing is configured yet. Do the whole setup from existing project instructions and user answers. Reading commits and drafting a proposed configuration can proceed before missing details are resolved.

Do not guess a documentation location. Ask the user in one grouped question (an available question tool or chat):

1. Where do the docs live? Options: a separate docs repo (ask for the local clone path, the remote URL, the base branch, and the docs root within it) — or "no separate docs repo", in which case offer local mode: this skill will create and manage a docs/ tree in this repo instead. Do not treat "no docs repo" as a reason to stop; local mode is a first-class answer.
2. What should never trigger a doc update? e.g. chore commits, dependency bumps, test-only changes → rules.exclude_commit_types, rules.exclude_paths.
3. What must always trigger one? e.g. anything under the API or config surface → rules.always_document_paths.
4. Anything else to always or never do when editing docs → rules.instructions.

Only if the user declines to answer at all — they don't want docs managed either way — stop cleanly: say the skill needs a documentation target and leave the repo untouched. Never invent a docs repo, never write docs to a path the user didn't agree to.

Then write .agents/commit-documentor.json from templates/config-template.json, keeping only the block for the chosen mode (doc_repo or local_docs) and dropping every _comment_* key. Show it to the user and offer to commit it to the project repo.

Requires git, jq, and realpath. No remote publication is performed.

Optional index for larger documentation trees

A committed index at the config's doc_index path maps code areas to doc pages and keeps queries cheap. For a small docs tree, search directly and skip it. Setup and refresh details live in references/doc-index.md.

Rules

Rules live under rules in the config, gathered during first-run setup: exclude_commit_types, exclude_paths, always_document_paths, and free-form instructions. See references/rules.md for precedence.

Any instruction the user gives when invoking the skill applies to this run only and overrides the config; if it looks durable ("stop documenting CLI flag changes"), offer to add it to the config.

Workflow

Track each step as a task.

0. Check preconditions — before reading any commits

Do not start reviewing commits until the applicable checks pass:

scripts/doc-repo.sh config >/dev/null   # exit 3 → run "First run: setup" above

• Config missing (exit 3)? Run First run: setup and finish it before continuing.
• Using an index? Refresh it if stale; otherwise search the small docs tree directly.

Hitting either of these halfway through a run wastes the review and forces the user to answer setup questions mid-flow. Check first.

1. Establish the commit range

Default: everything on the branch not yet on origin.

git rev-parse --abbrev-ref --symbolic-full-name @{u} >/dev/null 2>&1 \
  && range="@{u}..HEAD" || range="HEAD~1..HEAD"
git log --format='%h %s' $range
git diff --stat $range

If the user passed a range or a SHA as an argument, use that instead. If the range is empty (nothing unpushed), say so and stop — there is nothing to document.

2. Review the commits

For each commit, read the actual diff, not just the subject:

git show --stat <sha>
git show <sha> -- <paths of interest>

Fold in whatever extra instruction the user gave when invoking the skill. Judge each commit on what the diff does, not what its message claims — a commit typed chore: that changes a default config value is a behavior change and the message is wrong.

3. Decide applicability

Apply the rules from references/rules.md to each commit and classify it: needs docs, excluded by rule (name the rule), or no user-visible change. Then, for the commits that need docs, use the doc index to find the target pages, and confirm against the live doc repo:

scripts/doc-repo.sh sync
scripts/doc-repo.sh search "<symbol>" "<flag>" "<endpoint>"

Read the target pages in full before editing them. If a needed page does not exist and the area is listed under "Undocumented areas", propose a new page — but say plainly that it is new, and where it would sit.

If nothing needs docs, report the classification per commit and stop. That is a successful run, not a failure.

4. Draft the updates

Edit the doc files directly — the doc repo clone in repo mode, docs_root in this repo in local mode; scripts/doc-repo.sh path and ... root resolve both. Match the surrounding page's structure, voice, and heading depth — read neighbors before writing. In local mode with no docs yet, you are creating the first pages: establish a simple, obvious structure (a page per user-facing surface) rather than scaffolding an elaborate tree the project can't sustain. Keep edits minimal and scoped to what the commits actually changed; do not opportunistically rewrite unrelated prose.

Present for approval:

scripts/doc-repo.sh diff

This shows tracked edits and the full content of any new pages, scoped to docs_root so the user's unrelated working-tree changes never appear. Show the user the full diff, plus a short per-file rationale tying each edit to a specific commit, and the list of commits you excluded and why.

5a. Approved → commit locally

Write the commit message and an approved-file manifest (one repo-relative file path per line, no directories). Include only files whose complete changes were reviewed. The helper commits all working-tree changes in each listed file, so inspect pre-existing edits before including that file.

scripts/doc-repo.sh commit "docs/<short-slug>" <msg-file> <approved-files-manifest>

Repo mode creates a local branch; local mode stays on the current branch. Neither pushes nor opens a PR. Prepare a PR body using templates/doc-pr-body.md when useful and provide the user's publication commands. Publication approval does not override no-push rules.

If an index is used, update its recorded SHA/mappings and report that change.

5b. Declined → revise or preserve

Track the initial contents and the exact files changed during this run. Revise those edits in place. Never use checkout/reset/clean on a docs tree. Preserve rejected drafts unless the user asks to undo the run's changes; undo only those changes and preserve intervening edits. The old broad revert command refuses execution. Report retained drafts and their paths on exit.

Hard rules

• Never publish docs without approval of the specific diff in this session.
• Never guess a documentation location. If none is configured, run first-run setup; if the user has no docs repo, offer local mode rather than inventing a target.
• In local mode, never push the project repo and never stage anything outside docs_root — the user's other work is not yours to commit.
• Never edit paths the config or index marks as hand-maintained / no code owner.
• Never invent doc content that the commits do not support — if the code's behavior is ambiguous, ask rather than documenting a guess.
• Never rewrite the project repo's own commits; this skill only writes docs and the index.
• Report committed, retained-draft, and blocked files accurately on exit.