Update Docs

---
name: update-docs
description: Audit and update every documentation surface in the APEX repo against the current state of skills, steering workflows, README marker tables, and the Docusaurus site under misc/website/. After any change to a skill (rename, retire, add, edit description), walk the repo, re-run script-managed surfaces if their --check fails, and reason through every tracked prose *.md to catch references that need updating. Use after adding/removing/renaming a skill, after editing SKILL.md frontmatter, after editing README marker blocks, or before publishing a docs change. Also use when the user says "update docs", "sync docs", "check docs", "run update-docs", or mentions that documentation might be stale.
---

# Update Docs

Walk the APEX repo after any content change and bring every documentation surface back into sync. Two categories of surface exist: script-managed (deterministic, re-runnable) and prose (requires reasoning). Handle both in a single pass.

## When to use

- A skill was added, removed, renamed, or had its frontmatter edited
- A steering workflow was added, removed, or renamed
- README marker blocks were edited manually
- Before opening a PR that touches `skills/` or `steering/`
- The user asks to "check docs", "update docs", or "sync documentation"

## Modes

**Coding-agent mode** (default in Claude Code): walk the repo, re-run scripts, propose diffs, ask before writing user-facing prose. Auto-apply mechanical fixes (script outputs, simple name substitutions in fenced code blocks).

**Chat-only mode** (no file-write tools available): emit the PASS/STALE table + a fix checklist of one-line commands. No file edits.

## Step 1: Detect the change set

Determine what changed. Default comparison base is `origin/main`:

```bash
git diff --name-status origin/main...HEAD -- 'skills/**/SKILL.md' 'steering/workflows/*.md' 'steering/commands/**/*.md' 'devops-agent/**'
```

If the user specifies a different scope ("since my last commit", "just the rename I did"), adjust the base accordingly. Also include any paths the user explicitly names.

## Step 2: Tier 1 — Script-managed surfaces

Two scripts own deterministic regeneration. Detect staleness and re-run them. Never duplicate their logic.

| Surface | Stale when | Fix |
|---|---|---|
| Marker blocks (README.md, skills/README.md, steering/**/*.md) | `./misc/update-all-references.sh --check` exits non-zero | `./misc/update-all-references.sh` |
| Docusaurus wrappers, manifest, skills index | `./misc/update-pages.sh --check` exits non-zero | `./misc/update-pages.sh` |

Run both `--check` commands. If either exits non-zero, re-run the corresponding script. In coding-agent mode, apply the changes directly. In chat-only mode, emit the fix command.

## Step 3: Tier 2 — Prose ripple

Read each file in the candidate set below. Hold the change set in mind and look for stale references.

### What "stale" looks like

- A skill name in prose that no longer matches a `skills/<name>/` directory
- A frontmatter description that was edited, where the old phrasing still appears verbatim elsewhere
- A retired steering workflow still referenced in a list
- A skill count or coverage claim ("APEX ships six skills") that no longer matches reality
- A path link `skills/old-name/` after a rename
- A removed or renamed concept still mentioned in contributor guidance

### Candidate set (tracked files only — use `git ls-files`)

**In scope:**
- `README.md`
- `CONTRIBUTING.md`
- `CODE_OF_CONDUCT.md`
- `THIRD_PARTY_NOTICES.md`
- `skills/README.md`
- Every `skills/<name>/README.md` where present
- Every `skills/<name>/SKILL.md`
- Every tracked `*.md` under `steering/`
- `devops-agent/README.md`
- Every `devops-agent/<name>/SKILL.md`
- `misc/README.md`
- `misc/evals/README.md`
- `misc/evals/_template/README.md`
- Every `misc/evals/<skill>/README.md`
- `misc/website/docs/intro.md`
- `misc/website/docs/getting-started.md`
- `misc/website/src/pages/index.tsx` (not markdown but contains skill-name copy)

**Excluded (generated by scripts — never hand-edit):**
- `misc/website/docs/skills/*.md`
- `misc/website/docs/steering/*.md`
- `misc/website/docs/skills/index.md`
- `misc/website/static/manifests/skills.json`

For each file, if you find stale content:
- In coding-agent mode: propose the diff. For user-facing prose changes, ask before applying. For mechanical substitutions (path renames in code fences, skill-name swaps in lists), apply directly.
- In chat-only mode: add to the checklist with file, line, and what to change.

## Step 4: Final output

Always end with a summary table:

```
| Surface | Status | Action taken | Confirm? |
|---|---|---|---|
| Marker blocks | PASS | — | — |
| Docusaurus wrappers | STALE | Re-ran ./misc/update-pages.sh | — |
| README.md | STALE | Proposed diff | yes (line 42 prose) |
| CONTRIBUTING.md | PASS | — | — |
| skills/README.md | PASS | — | — |
| misc/evals/*/README.md | PASS | — | — |
| ... | | | |
```

Status values: `PASS` (no changes needed), `STALE` (changes applied or proposed), `SKIP` (file doesn't exist yet).

Rows marked `Confirm? yes` require the user's approval before the change is final. Wait for their response before moving on.