Track

acta:track

The keeper. One command reconciles the whole doc set with reality after you've built something — so you never have to say "update PRD, then CHANGELOG, then the design-system, then the legal briefs…". Its prime directive is anti-bloat: docs reflect the truth at their current size; they are not append-only journals.

Shared: ${CLAUDE_PLUGIN_ROOT}/acta/doc-catalog.md defines each doc's growth policy — obey it strictly.

Language

Update content in the project's documentation language (registry language:, default English); talk to the user in the language they use. See ${CLAUDE_PLUGIN_ROOT}/acta/principles.md.

Scope

By default, track syncs everything that exists in the project: the engineering docs, and — if the folders are present — the design layer (docs/design/) and the legal layer (docs/legal/). The user can narrow it: /acta:track docs · /acta:track design · /acta:track legal.

Pre-condition

Read .claude/acta.md (the registry). If absent, this project isn't set up with Acta yet → suggest /acta:build (greenfield) or /acta:adopt (existing code). Don't guess a doc set without the registry/catalog.

Flow

1. Gather what changed. In priority order:

   • If a git repo: git log/git diff since the registry's last-updated (new files, deps, endpoints, migrations, styling, vendors).
   • Recently modified source files and config.
   • Read root SCRATCH.md — the jotted 🔴🟡🔵 notes (in-flight bugs / needed changes) are inputs for what to update.
   • Ask the user one open question if intent is unclear: "What did you finish since last track?" (≤1 question).

2. Map changes → docs via the catalog. Only touch docs that are actually affected. Typical mappings:

   • progress → always. changelog → if user-visible change shipped.
   • new dependency / stack change → arch-overview, structure, env-vars.
   • new endpoints → api. schema/migration → db-design, erd.
   • a real architectural/tech decision → new ADR (per-item) + adr index.
   • scope/feature change → prd, roadmap, feature-specs.
   • pricing / cost / monetization change → note it and suggest /acta:business (iterative + sensitive; don't rewrite pricing here).

3. Apply updates by growth policy (from the catalog):

   • in-place (progress, roadmap, prd, standards, api, structure, …): edit/merge in place. Replace stale content; update the section that changed; refresh the updated: date. Never append a duplicate section.
   • append-log (changelog, ai-decision-log): add ONE new structured entry at the top of the log (CHANGELOG → under [Unreleased]; on release promote [Unreleased] to a version). Never rewrite history.
   • per-item (adr, rfc): create a NEW numbered file for a NEW decision; existing items change only their Status. Update the folder's README.md index.
   • regenerate (docs-index, brain, registry): rebuild from current state.

4. PROGRESS discipline (the classic bloat trap). PROGRESS.md is a snapshot, not a diary:

   • Update Current Status, In Progress, Next Up, Blocked to reflect now.
   • Keep Done (recent) to the last ~10 items; older completed work lives in CHANGELOG, not here.

5. Design sync — only if docs/design/ exists (skip otherwise). Bring the design doc-base back in line with the real styling, in place, no bloat (docs mirror the code, not history). Only touch the docs that exist at this project's tier:

   • new/changed token (color / spacing / typography / radius / elevation / motion) → update the fenced block in tokens.md (and the matching granular doc if present: color.md / typography.md / spacing-layout.md / motion.md).
   • new component / variant / state → components.md. Changed approach (e.g. CSS → Tailwind) → the Approach section of design-system.md.
   • new icon/imagery convention → iconography.md / imagery.md. New flow/screen → ux-flows.md. New a11y rule → accessibility.md.
   • new recurring copy → messaging.md (tone/terminology → content-style-guide.md). Remove entries no longer in the code.
   • a real, hard-to-reverse design decision (new palette / typeface / spacing character) → new DDR (docs/design/decisions/NNNN-*.md, per-item) + its index, if the project uses the full tier.
   • Refresh docs/design/README.md and the {{DESIGN_LINKS}} block in the brain.

6. Legal sync — only if docs/legal/ exists (skip otherwise). Scan for legal-relevant changes and update the briefs in place — never write binding legal text or give legal advice:

   • new data collected, cookies/analytics/trackers, a new vendor/sub-processor, a new market/region, payments, or targeting children → update data-processing / cookies / consent / privacy / compliance-checklist.
   • For every change that alters legal exposure, raise a "⚠️ needs lawyer re-review: " item in compliance-checklist.md, and surface it in docs/progress.md → Blocked and the CLAUDE.md legal pointer.
   • If docs/legal/lawyer-brief.md exists, refresh it (or suggest /acta:legal-brief) so the handoff stays current.

7. Drain SCRATCH.md (the Acta-managed scratchpad; skip if absent). For each jotted note (🔴🟡🔵):

   • if the work this run resolved it → remove it;
   • if it still needs to persist → relocate it into the right permanent doc FIRST, then remove it from SCRATCH: a real bug/debt → tech-debt (TD-N) or progress → Blocked / Next Up; a decision → a new ADR; a spec change → prd / feature-specs.
   • Never delete a note without relocating anything worth keeping — context must never be lost. Leave SCRATCH.md clean (keep its header/legend); the user never hand-deletes it.

8. Refresh the brain. Re-inject the CLAUDE.md index block (marker-scoped, idempotent), update docs/README.md, and update the registry rows/dates. Add rows for any docs newly created this run. If a whole new area appeared, offer to generate its missing docs (or point to /acta:build).

9. Summary. List exactly which docs were updated and how (edited / appended / new item), which SCRATCH notes were drained (resolved / relocated where), and any raised legal re-review flags. If nothing changed in a doc, leave it untouched and say so — no churn.

10. Offer a phase commit (git repos with a remote). If this run wrapped a phase/milestone and the repo has a git remote, suggest committing the phase now (docs + code together, focused message) so history advances phase by phase. Propose only — never auto-commit, and don't push; the user commits/pushes on their own call.

Rules (anti-bloat is non-negotiable)

• Prefer editing over adding. Refresh updated: only on docs you actually changed.
• No unbounded growth: in-place docs stay the size of the truth; logs get one concise entry; caps enforced (PROGRESS window).
• Idempotent: running twice with no new work produces no changes.
• Never write binding legal text or give legal advice in the legal sync — update briefs + flag for a lawyer only.
• Never touch code in the design sync — docs mirror the code, not the reverse.
• Never fabricate progress or values → TBD / ask. Never overwrite outside acta's scope; the brain block is marker-scoped.