# Track

> After finishing work, bring every affected doc to the current state — engineering docs, and the design + legal layers when they exist — in place, no bloat. Trigger on /acta:track, "update the docs", "sync progress", "track".

- Skill: `erenisci/track` (Agent Skill)
- Install (CLI): `npx skillmds@latest add erenisci/track`
- Raw SKILL.md: https://api.skillmd.com/api/skills/erenisci/track/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: erenisci (https://skillmd.com/u/erenisci)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/erenisci/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: <what changed>"** 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.