# Dart Docs Update

> DART Docs Update: update docs or AI instruction visibility without code changes, or audit the docs tree for stale, duplicated, and orphaned content

- Skill: `dartsim/dart-docs-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dartsim/dart-docs-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dartsim/dart-docs-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: dartsim (https://skillmd.com/u/dartsim)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dartsim/dart-docs-update

---


<!-- AUTO-GENERATED FILE - DO NOT EDIT MANUALLY -->
<!-- Source: .claude/commands/dart-docs-update.md -->
<!-- Sync script: scripts/sync_ai_commands.py -->
<!-- Run `pixi run sync-ai-commands` to update -->

# dart-docs-update

Use this skill in Codex to run the DART `dart-docs-update` workflow. The editable
workflow source lives in `.claude/commands/`; this file is its generated adapter
in the shared `.agents/skills/` catalog.

## Invocation

- Claude Code: `/dart-docs-update <arguments>`
- Codex: `$dart-docs-update <arguments>`

Treat the text after the skill name as `$ARGUMENTS`. When the workflow
references `$1`, `$2`, etc., map those to the positional values supplied by the
user.

## Command Body

Update documentation: $ARGUMENTS

## Required Reading

@AGENTS.md
@docs/README.md
@docs/AGENTS.md
@docs/ai/principles.md
@docs/ai/verification.md

For AI instruction or workflow changes, follow the owner read order in
`docs/ai/README.md`; read the relevant tool section of
`docs/onboarding/ai-tools.md` only when compatibility is affected. Load
`docs/onboarding/changelog.md` when making the closeout changelog decision.

## Modes

- `<topic>` (default): make the requested documentation change.
- `audit [bucket]`: find stale, duplicated, unowned, or oversized docs and
  propose or apply consolidations; limit to one bucket when given.

## Workflow

1. Create a branch from the target branch: `git checkout -b docs/<topic> origin/main`
2. For `audit`, build the finding list first:
   - run `pixi run check-docs-policy` and collect every failure and advisory
     (broken links, orphans, dev-task size budgets, dashboard budgets);
   - run `pixi run check-architecture-map` and, when a build exists,
     `pixi run check-architecture-map-runtime`; treat findings as drift of the
     architecture map views under `docs/assets/architecture/` (see the
     `dart-architecture` skill for the update procedure);
   - walk the "Keeping Docs Current" table in `docs/README.md` against the
     bucket: completed tasks whose folders remain, archived plans still
     pointing at numbered files, resolved `Decision needed` blocks, superseded
     pages, rules copied into more than one doc, running logs in snapshot
     files, and pages describing a state the code has left behind;
   - for each finding record the owner doc, the proposed action (rewrite,
     merge, delete, promote, link), and the evidence; prefer deletion and
     consolidation over new files or sections. Apply the findings that stay
     within the requested scope and list the rest in the output.
3. Edit docs and AI workflow sources only:
   - Regular docs: `docs/**`, `README.md`, `AGENTS.md`, `CONTRIBUTING.md`,
     and `CHANGELOG.md` when `dart-changelog` requires a release-note entry
   - AI source files: `.claude/commands/**`, `.claude/skills/**`
4. For AI workflow changes, edit `.claude/` sources and run `pixi run sync-ai-commands`; do not hand-edit generated `.agents/skills/` files (`.codex/` is a maintained source)
5. Classify new or moved docs by lifecycle first, then audience, then topic,
   using the placement matrix in `docs/README.md`. For AI docs, keep
   always-loaded entrypoints compact: improve owner placement or pointers
   instead of duplicating procedures.
6. Update indexes and cross-references that point to changed docs; redirect
   every link into a deleted file.
7. Use `docs/ai/verification.md` to select the docs-only or AI docs/adapters
   gate set, then run `pixi run lint` before committing
8. Invoke the `dart-changelog` routine for the `CHANGELOG.md` decision and any
   required entry.
9. Ask for explicit maintainer/user approval before pushing or opening the PR.
   After approval, use `.github/PULL_REQUEST_TEMPLATE.md` and the proper
   milestone.

## Output

- Docs and AI workflow sources changed
- For `audit`: findings applied, findings deferred with their owner, and
  advisories left in place with the reason
- Sync and verification commands run
- Changelog decision
- PR readiness, noting any external mutation that was explicitly approved