cad-health

Files (1)

• SKILL.md

SKILL.md (first lines)

<objective>
A fast structural pulse on `.planning/` - can the spine even read its own state?
It checks presence, parseability, and internal consistency, nothing deeper. It
does NOT judge whether requirements were delivered (that is /cad-audit's job);
it judges whether the files are well-formed enough for the other skills to trust.
</objective>

<process>
Check, then report - do not fix without asking.

1. **Presence.** `.planning/` exists with PROJECT.md, REQUIREMENTS.md,
   ROADMAP.md, STATE.md. A missing core doc is an issue (if the dir itself is
   absent, point at /cad-new-project for a blank page and /cad-adopt for a repo
   that already has code and history).
   - The run record stays out of git. Run
     `node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" trace ignore --root . --check`
     and report an issue when `ignored` is false or `tracked` is true. Silent when
     the record is ignored and untracked. A project scaffolded before that seam
     existed has no line of its own; `--check` writes nothing and this step never
     edits the user's `.gitignore`.
     The two flags are separate facts and take DIFFERENT remedies, so name the one
     that applies rather than one command for both: `ignored:false` is a missing
     rule, fixed by the same command without `--check`; `tracked:true` means the
     record is in the index ALREADY, where no ignore rule reaches it, and the fix
     is `git rm --cached .planning/trace.jsonl`. Both can be true at once, and
     then both steps are needed - adding the rule alone leaves a tracked file that
     keeps getting committed.
   - The capture queue, in two calls - a census of the file's sections, and a
     verdict on the walked queue itself:
     `node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" capture-sections`
     `node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/planning.mjs" capture-check`
     From `capture-sections`, print one line per section whose `in_walk` is
     false, naming its heading and its bullet count, then what the number MEANS
     in one clause: those bullets are invisible to /cad-plan's recall. Silent
     when `exists` is false or every section is in the walk. It is a NAMED NOTE,
     not an issue, the way step 7's manifest clause is a distinct lower note:
     `## Debt markers` is written wholesale by `debt-harvest` and is not a
     queue, so calling every out-of-walk section an issue trains the user to
     skim past exactly the line this is here to make readable. What is worth
     their attention is a count that MOVED, which they can only see because the
     steady-state number is printed too.
     From `capture-check`, print three things, and these ARE issues.
     `.planning/CAPTURE.md` holds the phase in flight and nothing else, so each
     one says that stopped being true:
     - `substantive` against `bound`, naming the crossing when `over_bound` is
       true. A crossed bound means a filing path stopped filing - the queue is
       carrying work that belongs on the tracker.
     - every `annotations[]` entry with its section, line and text. An
       annotation is an item adjudicated the WRONG WAY: an item is resolved by
       REMOVAL, so re-verifying one in place made the bullet longer instead of
       making it leave.
     - `archive.heading` with `archive.bullets` when `archive.present` is true.
       That heading has LEFT this file's contract - moving settled items to a
       section of the same document changes nothing about the bytes.
     Print both readings EVERY run, never filtered against a list of sections or
     items you expect. That allowlist is precisely what would have hidden the
     incident this check exists for - all five lost bullets sat under
     `## Archive`, the section any allowlist would have named first.

2. **STATE cursor.** Exactly the 4-line schema (Phase / Status / Next / Updated -
   references/conventions.md). `Status` is one of the lifecycle values
   (`ready to plan | context gathered | planned | executed | phase complete |
   paused`). `Phase: N of M` parses with N <= M (except in the closed-milestone
   case rule 5 states). `Updated` is a date. Flag a 5th line, an unknown status,
   or an unparseable phase.

3. **ROADMAP.** `## Phases` entries are `- [ ]` / `- [x]` **Phase N: Name**,
   numbered 1..M with no gaps or dupes. An EMPTY `## Phases` is a legitimately
   closed milestone, not a numbering gap - do not flag it.

4. **REQUIREMENTS.** The traceability table parses; every `Status` is `Pending`
   or `Complete`; every `Phase` value names a phase that exists in ROADMAP.

5. **Consistency.** Cursor `M` == ROADMAP phase count; cursor `N` is within
   range. When ROADMAP has zero phases the cursor reads `of 0`, and
   `Phase: 1 of 0 (no active cycle)` is the expected closed-milestone shape -
   both clauses pass, and a surviving `phases/<N>/` dir there means the prune
   was interrupted (/cad-milestone finishes it).
   `.planning/phases/<N>/` dirs correspond to real phases (a planned
   phase with no dir yet is fine; a dir with no phase is an issue). The
   directory grammar is stated in references/roadmap-phases.md: report every
   `phase-dir-grammar` entry
   `planning.mjs status` returns as an issue naming the entries it lists -
   Cadence resolves no other spelling, so those directories are unsupported, and
   renaming them is the user's call and never an auto-fix. Report a
   `phase-dir-collision` entry too, but say the other thing: both names are
   LEGAL and parse to one number, so no spelling is wrong - only ambiguous. A phase
   marked `- [x]` in ROADMAP whose mapped REQUIREMENTS rows are not all
   `Complete` (or a `Complete` requirement whose phase is still `- [ ]`) is a
   status-drift issue - flag it. This is the cheap structural check that a
   phase closed clean; whether the requirement was actually *delivered* is
   /cad-audit's job, not this one.

6. **Inert config.** A setting that is ON and cannot take effect is worse than
   one that is off: the user believes they have the behaviour and never sees it
   missing. Check the known cases and report each as an issue naming the fix.
   - `parallelization.enabled` true while
     `node "${CLAUDE_PLUGIN_ROOT}/cadence-core/bin/worktree-base.mjs" resolve`
     returns `parallelSafe: false` -> every /cad-execute run has been sequential
     and always will be. Report the resolver's own `reason` and the fix it names
     (`worktree.baseRef` set to `"head"`; /cad-config offers it).
   - `parallelization.enabled` true with `use_worktrees` false -> parallel
     dispatch without isolation is unsupported and falls back to sequential.
   - `review.reviewers` naming a provider with no resolvable credential -> the
     cross-model panel silently degrades to the in-process reviewer. Check
     presence only, NEVER read or print a key's value.
   - `parallelization` present but not an object (e.g. `"parallelization": true`)
     -> the whole block is malformed, every key inside it reads as its schema
     default, and nothing warned. Same for any config block the schema declares
     as an object.

7. **Version drift.** The `PROJECT.md ### Active` milestone version must not be
   one the project has ALREADY SHIPPED. Membership, not sort order: the issue is
   an Active version that equals an existing release TAG (`git tag --list`).
   Report it naming both numbers. No tags, or a version that parses as neither
   semver, is clean: an unprovable comparison is not drift.

   Tags are the publication evidence; a manifest in the checkout is NOT. The
   manifest bumps during the close, before the merge and before the tag, so

From crenshawdev/cadence, MIT.

More from crenshawdev/cadence