| name | dart-docs-update |
| description | DART Docs Update: update docs or AI instruction visibility without code changes, or audit the docs tree for stale, duplicated, and orphaned content |
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
- Create a branch from the target branch:
git checkout -b docs/<topic> origin/main
- 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.
- 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/**
- 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)
- 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.
- Update indexes and cross-references that point to changed docs; redirect
every link into a deleted file.
- Use
docs/ai/verification.md to select the docs-only or AI docs/adapters
gate set, then run pixi run lint before committing
- Invoke the
dart-changelog routine for the CHANGELOG.md decision and any
required entry.
- 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
