Check docs

Documentation Consistency Check

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

Steps

1. Identify what changed: Run git diff main...HEAD --name-only (or git diff HEAD~5 --name-only if on main) to see recently changed source files.

2. Decide whether a deep review is needed (short-circuit). The docs gate's scope includes src/**, so any src edit invalidates the marker — but most internal refactors and bug fixes don't affect anything the docs describe. Skip the LLM-judged review and set the marker directly when the diff only touches files that the docs don't describe. A deep review is required if the diff touches ANY of:

   • src/index.ts — public exports
   • src/cli/options.ts, src/cli/commands/** — CLI surface described in README.md
   • src/types/** — public type definitions
   • src/state/** — bucket name, key layout, lock layout, schema version. These are documented verbatim in docs/state-management.md, docs/troubleshooting.md, README.md ("Outputs" example path), and CLAUDE.md ("S3 storage structure"). A path-layout change in s3-state-backend.ts or lock-manager.ts invalidates ~30 shell snippets across those files; the auto-migration session of 2026-05-01 (PR #57 → v0.7.0) shipped before this trigger existed and the docs took the full rollout to be re-aligned.
   • any new file added anywhere under src/** — must be mentioned in CLAUDE.md "Key Files and Directories"
   • package.json — dependency additions/removals described in CLAUDE.md "Dependencies"
   • README.md, CLAUDE.md, docs/**, .claude/rules/** — the docs themselves
   • README-visible CLI behavior changes (new flags, changed defaults, new commands)

   If none of the above apply (only internal src files modified, no new files, no deps changed), write a one-line note — "no docs-visible surface touched" — set the docs marker (see "Commit-gate marker" below), and stop. Do NOT re-read docs for unrelated internal edits.

3. For each changed source file (when a deep review is warranted), determine what documentation might be affected:

   • src/cli/ changes → check CLI options/commands in README.md, CLAUDE.md
   • src/synthesis/ changes → check docs/architecture.md synthesis section, CLAUDE.md synthesis section
   • src/assets/ changes → check docs/architecture.md asset section, CLAUDE.md asset section
   • src/deployment/ changes → check docs/architecture.md deployment section, CLAUDE.md deployment section
   • src/provisioning/ changes → check docs/provider-development.md, CLAUDE.md provider section. For a NEW SDK provider ALSO check docs/supported-resources.md + docs/import.md (per .claude/rules/providers.md "Adding a New SDK Provider"). If the provider gates a stabilization wait on process.env['CDKD_NO_WAIT'] (i.e. --no-wait skips a multi-minute poll for this type), its resource type MUST appear in the --no-wait resource lists: the table + intro in docs/cli-reference.md, the --no-wait bullet in README.md, and the noWaitOption help + JSDoc in src/cli/options.ts. Enforced by tests/unit/provisioning/no-wait-doc-coverage.test.ts (CI fails if a CDKD_NO_WAIT provider is absent from the cli-reference --no-wait table). The AWS::Lambda::MicrovmImage provider shipped honoring --no-wait but missed this list — this bullet + that test are the backstop.
   • src/analyzer/ changes → check docs/architecture.md analysis section
   • src/state/ changes → check docs/state-management.md
   • New files added → check if they're mentioned in CLAUDE.md "Key Files and Directories"
   • New exports in src/index.ts → check if public API docs are updated
   • package.json dependency changes → check CLAUDE.md "Dependencies" section
   • New CLI options → check README.md usage section
   • New integration tests → check docs/testing.md

4. Read the relevant documentation sections and compare with the actual code to find:

   • Missing mentions of new files, features, or options
   • Outdated descriptions that no longer match the code
   • Stale lists (e.g., provider lists, context provider lists) that don't match what's in the source
   • Hardcoded lists that should reference the source directory instead

5. Report findings as a checklist:

   • List each discrepancy found with the specific file and section
   • For each issue, suggest the fix
   • If no issues found, confirm documentation is consistent

6. Fix the issues if the user agrees, or ask for confirmation first.

Commit-gate marker (on success only)

After documentation is verified consistent (either no issues were found, or all issues were fixed), record the docs markgate marker so the PreToolUse check-gate hook (see .claude/hooks/check-gate.sh) allows the next git commit. The docs gate is scoped to src/**, docs/**, README.md, CLAUDE.md, and .claude/rules/** via .markgate.yml, so it only invalidates when one of those is edited.

Run from the repo root (use mise exec to avoid PATH issues when shims aren't active):

mise exec -- markgate set docs

Skip this step if issues remain unfixed — a stale or missing marker correctly forces the user (or Claude) to re-run /check-docs after fixing docs.

Important

• Do NOT add documentation that doesn't exist yet (don't create new doc files)
• Focus on consistency between existing docs and code, not completeness
• Check CLAUDE.md's "Known Limitations" section AND docs/changelog-cdkd.md (the per-PR shipped-feature changelog moved out of CLAUDE.md per Claude Code's ≤200-line memory guidance) for stale entries
• Prefer referencing source directories over hardcoded lists in docs