---
name: check-docs
description: Check if documentation (README.md, AGENTS.md, docs/) is up to date with recent code changes. Use when code has been modified and docs may be stale.
---

# Documentation Consistency Check

You are checking whether documentation is up to date with recent code changes in
this repository.

## Steps

1. **Identify what changed**: `git diff main...HEAD --name-only` (or
   `git diff HEAD~5 --name-only` if on main).

2. **Decide whether a deep review is needed (short-circuit)**. Most internal
   refactors and bug fixes do not affect anything the docs describe. A deep
   review IS required if the diff touches any of:
   - `src/index.ts` — public exports.
   - `src/cli/options.ts`, `src/cli/commands/**` — the CLI surface described in
     `docs/getting-started.md` and the per-command pages under `docs/`.
   - `src/types/**` — public type definitions.
   - `src/state/**` — bucket name, key layout, lock layout, schema version, all
     documented verbatim in `docs/state-management.md`,
     `docs/troubleshooting.md`, `docs/stack-outputs.md` and
     `.claude/rules/state-schema.md`. A path-layout change invalidates dozens of
     shell snippets across them.
   - Any NEW file under `src/**` — it must be reachable from the key-file index
     in `.claude/rules/code-layout.md` and its `layout-*.md` satellites.
   - `package.json` — dependency changes described in
     `.claude/rules/package-and-release.md`.
   - `README.md`, `AGENTS.md`, `docs/**`, `.claude/rules/**`, `plugins/**` — the
     docs themselves. `plugins/**` is a TRIGGER, not only a step-3 target: a
     plugins-only diff matches nothing else, and step 3 reads changed SOURCE
     files.
   - **Any `src/**` file matched by a `paths:` glob in a `.claude/rules/`
     satellite** — in practice nearly every src file. A comment-only or
     message-only edit does NOT exempt it: those files assert DECISIONS about the
     code, and a reworded message is exactly what invalidates one.

   If none apply, write "no docs-visible surface touched" and stop.

3. **For each changed source file**, determine what documentation is affected:
   - **Any `src/**` change → the `.claude/rules/` satellites whose `paths:` glob
     matches it.** DERIVE them —
     `for f in .claude/rules/*.md; do echo "$f"; sed -n '/^paths:/,/^---$/p' "$f"; done`,
     or the per-area row in `.claude/rules/code-layout.md` — never recall them,
     and use the `sed` range rather than `grep -A<n>`, which truncates a file
     declaring several globs. Then read what each SAYS about the code you
     changed, not just whether it names your new files: nothing mechanical
     watches a rule file that asserts a decision.
   - `src/cli/` → CLI options/commands in `docs/getting-started.md` and the
     per-command pages.
   - `src/synthesis/`, `src/assets/`, `src/deployment/`, `src/analyzer/` → the
     matching section of `docs/architecture.md`.
   - `src/provisioning/` → `docs/provider-development.md` and
     `docs/provider-rules.md`, plus `.claude/rules/providers.md`. For a NEW SDK
     provider also `docs/supported-resources.md` + `docs/import.md`. If the
     provider gates a stabilization wait on `process.env['CDKD_NO_WAIT']`, its
     resource type MUST appear in the per-type wait-semantics table in
     `docs/cli-deploy.md` and in the `noWaitOption` help + JSDoc in
     `src/cli/options.ts` (enforced by
     `tests/unit/provisioning/no-wait-doc-coverage.test.ts`).
   - `src/state/` → `docs/state-management.md`.
   - New exports in `src/index.ts` → public API docs.
   - `package.json` dependency changes → `.claude/rules/package-and-release.md`.
   - New integration tests → `docs/testing.md` and
     `docs/integ-fixture-conventions.md`.
   - **Any behaviour change → `plugins/cdkd-skills/skills/cdkd/SKILL.md`**, the
     DISTRIBUTED plugin surface, written for an audience that never reads this
     repo. Grep it for the subject you changed. If you edit it, bump the
     `version` in BOTH `plugins/cdkd-skills/.claude-plugin/plugin.json` and
     `.claude-plugin/marketplace.json` in the same PR — nothing enforces that,
     and an un-bumped edit ships to nobody.

4. **Read the relevant documentation sections** and compare with the code, for:
   missing mentions of new files / features / options; outdated descriptions;
   stale lists (provider lists, context-provider lists); hardcoded lists that
   should reference the source directory instead.

5. **Report findings** as a checklist: each discrepancy with its file and
   section, and the suggested fix. If none, confirm the docs are consistent.

6. **Fix the issues**, then re-run this check.

## When to run this

Before committing, and again before opening the PR if anything changed since. It
only needs re-running when one of `src/**`, `docs/**`, `README.md`, `AGENTS.md`
or `.claude/rules/**` is edited. If issues remain unfixed, fix them and re-run —
do not report the docs consistent.

## Important

- Do NOT create new doc files; check consistency, not completeness.
- Check the changelog entries for stale content. **First ask whether this change
  writes a changelog entry AT ALL**:
  only a user-visible behavior delta does — what the shipped binary does. Agent
  instructions, tests, CI, hooks and behavior-describing docs write none. A
  required entry is ONE file under
  `changelog.d/entries/<YYYY-MM-DD>-<issue>-<slug>.md` carrying the bullet and no
  dated heading, capped at 2000 characters
  (`tests/unit/scripts/changelog-entry-size.test.ts`); a design decision goes to
  `docs/design/<issue>-<slug>.md` instead.
- Prefer referencing source directories over hardcoded lists in docs.