Changeset Doc Sync

Changeset Doc Sync

Use this workflow when release docs must match current changeset content.

Mandatory sequence

1. Run preflight migration review from /example before docs sync:

   • git diff --name-only -- example
   • git diff --stat -- example
   • git diff -- example
   • Save migration conclusions in the active docs/plans/<date>-changeset-doc-sync.md.
   • Mandatory: build a /example change checklist in that goal plan with one checkbox per changed file.
   • For each changed /example file, record:
     • impacted doc file(s), or
     • explicit no doc impact justification.

2. Run autogoal planning first:

   • Create or continue one docs/plans/<date>-changeset-doc-sync.md goal plan.
   • Use node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs --template task --title "changeset doc sync" when creating a new plan.
   • Mandatory: the goal plan must include an exhaustive per-file checklist (every target doc as its own - [ ] item).

3. Resolve active changeset target(s):

   • List .changeset/*.md excluding .changeset/README.md.
   • Use changed changeset file(s) in the branch.
   • Extract breaking/features/patches and migration snippets.

4. Build execution checklists in the goal plan:

   • Include every file in:
     • www/**/*.md
     • www/**/*.mdx
     • packages/kitcn/skills/kitcn/**/*.md
   • Keep /example crosswalk checklist in the goal plan in sync during the run.

5. Read every listed doc and sync:

   • Update docs where migration changes are required.
   • Mark every file checked once synced.
   • If unchanged, still check with note no change needed.
   • For each /example changed file, mark the corresponding crosswalk checkbox only after linked docs are verified.

6. Completion gates:

   • /example crosswalk in the goal plan has zero unchecked file items.
   • The goal plan has zero unchecked file items.
   • No unchecked items remain.
   • The goal plan logs scanned/updated/unchanged totals.
   • The goal plan maps key doc edits to concrete changeset bullets.
   • node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/<date>-changeset-doc-sync.md passes.

Non-negotiable checklist rules

1. Do not summarize file coverage in the goal plan (for example, "56 files scanned").
   You must list each file explicitly with its own checkbox.
2. Every processed file must be marked:
   • updated, or
   • no change needed
3. A run is incomplete if even one file remains unchecked in either checklist.
4. Any changed /example file without a mapped doc check or no doc impact note is a hard failure.
5. Do not close the run until /example diff, changeset bullets, and updated docs are all cross-referenced.

Goal plan checklist template (required)

### Phase: Doc Sync Checklist (www)

- [ ] `www/content/docs/a.mdx` — pending
- [ ] `www/content/docs/b.mdx` — pending

### Phase: Doc Sync Checklist (packages/kitcn/skills/kitcn)

- [ ] `packages/kitcn/skills/kitcn/SKILL.md` — pending
- [ ] `packages/kitcn/skills/kitcn/references/setup/index.md` — pending

### Phase: /example-to-doc Crosswalk (required)

- [ ] `example/convex/shared/api.ts` -> `www/content/docs/cli/backend.mdx`, `www/content/docs/react/infer-types.mdx` — pending
- [ ] `example/src/lib/convex/crpc.tsx` -> `www/content/docs/react/index.mdx` — pending
- [ ] `example/src/lib/convex/rsc.tsx` -> `www/content/docs/nextjs/index.mdx`, `www/content/docs/server/server-side-calls.mdx` — pending
- [ ] `example/src/lib/convex/server.ts` -> `www/content/docs/nextjs/index.mdx` — pending
- [ ] `example/convex/functions/http.ts` -> `www/content/docs/server/http.mdx` — pending
- [ ] `example/convex/shared/types-typecheck.ts` -> `www/content/docs/react/infer-types.mdx` — pending

Checklist template

# Doc Sync Checklist

## Changesets

- [x] `.changeset/your-file.md`

## www docs

- [ ] `www/path/to/doc.mdx` — pending

## packages/kitcn/skills/kitcn docs

- [ ] `packages/kitcn/skills/kitcn/SKILL.md` — pending
- [ ] `packages/kitcn/skills/kitcn/references/setup/index.md` — pending

## Synced

- [x] `www/path/to/doc.mdx` — updated for `@convex/api` migration
- [x] `packages/kitcn/skills/kitcn/references/setup/index.md` — no change needed

Suggested commands

git diff --name-only -- example
git diff --stat -- example
git diff -- example
find .changeset -maxdepth 1 -type f -name '*.md' ! -name 'README.md' | sort
find www -type f \( -name '*.md' -o -name '*.mdx' \) | sort
{ echo 'packages/kitcn/skills/kitcn/SKILL.md'; find packages/kitcn/skills/kitcn/references -type f -name '*.md' | sort; }