changeset-doc-sync

description	Read every doc in www and packages/kitcn/skills/kitcn, sync to active changeset(s), and track with checkmarks.
name	changeset-doc-sync
metadata	{"skiller":{"source":".agents/rules/changeset-doc-sync.mdc"}}

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 findings.md.
   • Mandatory: build a /example change checklist in task_plan.md with one checkbox per changed file.
   • For each changed /example file, record:
     • impacted doc file(s), or
     • explicit no doc impact justification.

2. Run file-based planning first (planning-with-files):

   • Keep task_plan.md, findings.md, progress.md in repo root.
   • Append dated sections if these files already exist.
   • Mandatory: task_plan.md 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 checklists in both places:

   • task_plan.md (execution checklist; required)
   • Include every file in:
     • www/**/*.md
     • www/**/*.mdx
     • packages/kitcn/skills/kitcn/**/*.md
   • Keep /example crosswalk checklist in task_plan.md 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 task_plan.md has zero unchecked file items.
   • task_plan.md has zero unchecked file items.
   • No unchecked items remain.
   • progress.md logs scanned/updated/unchanged totals.
   • findings.md maps key doc edits to concrete changeset bullets.

Non-negotiable checklist rules

1. Do not summarize file coverage in task_plan.md (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.

task_plan.md 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; }