# Mpt Ext Task Update Docs From Changes

> Only update repository docs to match a code change set (docs/*, README.md, AGENTS.md) for unstaged, uncommitted, last-commit, or branch-diff changes. A building block: no self-check or staging.

- Skill: `softwareone-platform/mpt-ext-task-update-docs-from-changes` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add softwareone-platform/mpt-ext-task-update-docs-from-changes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/softwareone-platform/mpt-ext-task-update-docs-from-changes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: softwareone-platform (https://skillmd.com/u/softwareone-platform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/softwareone-platform/mpt-ext-task-update-docs-from-changes

---


# Update Docs From Changes

## Purpose

Bring repository documentation (`docs/*`, `README.md`, `AGENTS.md`) up to date with a specific set of code changes, following the shared documentation guideline.

## Use When

- Code or behaviour changed and the matching documentation must be updated.
- The user wants documentation regenerated from unstaged, uncommitted, last-commit, or branch-diff changes.
- A change is ready for review and its documentation impact must be reflected first.

## Do Not Use When

- The repository has no documentation yet and the full required set must be authored from scratch (use `mpt-ext-task-write-documentation`).
- The task is to commit, open a pull request, or transition Jira state.
- The task is to verify documentation without editing it.

## Inputs

- A target repository that is a Git working tree with history.
- The change source to document:
  - `unstaged`: working tree vs index
  - `uncommitted`: working tree vs `HEAD` (staged + unstaged)
  - `last-commit`: `HEAD~1..HEAD`
  - `branch-diff`: `<base>...HEAD` (base defaults to `origin/main`)
- Optional base ref when the source is `branch-diff`.
- Installed shared package root when shared guidance is needed:

```text
${MPT_EXTENSION_SKILLS_HOME:-$HOME/.mpt-extension-skills}/current
```

## Workflow

1. Build repository context first.
- Read the target repository `AGENTS.md` once per session. If you already loaded it earlier in this session and still have its full contents, reuse them instead of re-reading; if the context was summarized or you are unsure it is complete, read it again. Do not pre-load shared docs in this step; read them lazily only when the repository points to them.
- Read repository-specific docs when they exist, because they may extend or override shared guidance.
- Read shared docs required by this skill (see Shared References) regardless of repository pointers; read additional shared docs only when the repository explicitly points to them.
- Resolve shared docs from `${MPT_EXTENSION_SKILLS_HOME:-$HOME/.mpt-extension-skills}/current` when available; otherwise read them from the `main` branch of the shared GitHub repository.

2. Determine the change source.
- Use the source the user requested.
- If the source is ambiguous, ask the user before running. For `branch-diff`, confirm the base ref.

3. Collect the change set with the bundled script.

```bash
python3 "${MPT_EXTENSION_SKILLS_HOME:-$HOME/.mpt-extension-skills}/current/skills/mpt-ext-task-update-docs-from-changes/scripts/collect_changes.py" \
  --source branch-diff --base origin/main
```

- Use `affected_docs` to know which documents each changed path most likely affects.
- Use `missing_doc_updates` to see which affected docs were not yet touched in this change set.
- Treat `always_review` (`README.md`, `AGENTS.md`) as documents that need a judgement call, because behaviour and structure changes affecting them are not detectable from paths.
- Treat `unmapped_code` as changes with no default mapping; decide their documentation impact manually. Modified (not added or deleted) source files map to `docs/architecture.md` only through a structural signal, so ordinary edits land here for a manual call rather than flooding `missing_doc_updates`.
- Treat `stale_doc_references` as likely-stale references: each entry is an existing document that still mentions a path removed or renamed in this change set; confirm and fix or remove the reference.

4. Update the affected documents.
- For each affected document, read the current document and the actual change content, then edit only what the change affects.
- Follow `standards/documentation.md` for structure, topic boundaries, and required-set expectations.
- Do not duplicate shared standards; link to them and document only repository-specific behaviour, exceptions, or context.
- Update `README.md` navigation and `AGENTS.md` reading order only when structure, entry points, or public behaviour actually changed.

5. Report the result.
- List the documents updated and the change paths that drove each update.
- List affected documents you intentionally left unchanged, with a short reason.
- Surface anything that needs human judgement (for example a behaviour change whose user-facing impact is unclear).

## Guardrails

- Never document behaviour that is not present in the change set; do not invent features or future plans.
- Never duplicate shared engineering rules that already live in `standards/`; link to them instead.
- Never edit documentation unrelated to the change set.
- Never reproduce the deterministic change collection in prose; always use the bundled script.
- Never stage, commit, push, open a pull request, or change Jira state in this task; the invoking workflow stages the updated documentation files.
- Keep edits minimal and scoped to the change; do not rewrite untouched sections.

## Shared References

- `standards/documentation.md`: required documentation set, structure, and authoring rules.

## Bundled Resources

- `scripts/collect_changes.py`
  - Inputs: `--source {unstaged,uncommitted,last-commit,branch-diff}`, optional `--base`
  - Output: JSON with `source`, `base`, `changed_files`, `code_changes`, `doc_changes`, `affected_docs`, `missing_doc_updates`, `always_review`, and `unmapped_code`
  - Runtime path: `${MPT_EXTENSION_SKILLS_HOME:-$HOME/.mpt-extension-skills}/current/skills/mpt-ext-task-update-docs-from-changes/scripts/collect_changes.py`

## Expected Outcome

The documentation affected by the given change set is updated in line with `standards/documentation.md`, README/AGENTS are adjusted only when structure or behaviour changed, and the result clearly states what was updated and what was intentionally left unchanged.