check

Files (2)

• SKILL.md
• fixes.md

SKILL.md (first lines)

# /check — Workspace convention audit (with proposed fixes)

Orchestrates the three **fast deterministic** project audits, **proposes
fixes for every finding**, and lets the user approve before any change
lands. Thin wrapper over the underlying tools — the skill's job is
**sequence, unified reporting, and the propose-then-apply interaction
shape**.

The default behavior is *propose-and-apply*, not read-only. Pass `--json`
when you want a raw report for tooling or CI.

| Mode | What it audits | Backing |
|---|---|---|
| `docs` | doc-contract presence, todo/done hygiene, thinking.md sections, source/build naming (incl. multi-output folder), pandas merge validate=, archive.md leakage, idea frontmatter | `research-kit/tools/check_docs.py` (deterministic, <2s workspace-wide) |
| `ledgers` | `artifacts.yaml` ↔ disk drift, `validation.yaml` pending/stale rows, `.run.json` sidecar provenance, doc ↔ artifacts.yaml cross-refs | `research-kit/tools/coverage.py` (deterministic; requires pyyaml) |
| `cite` | `[ns:key]` citation tokens against the workspace registry, internal anchors, and `.bib` files | `research-kit/tools/citations.py` (deterministic; lint only — no manifest sync) |

For IAT (INTENT / REASONING / ASSUMES / SOURCE) comment compliance, see
`/iat` — that audit is LLM-driven and slower, kept as its own skill so
`/check` stays fast.

For manifest regeneration (`docs/refs/manifest.toml`), see `/cite-sync` —
that's a write action, not an audit.

## How to invoke

| Form | What it does |
|------|--------------|
| `/check` | All three modes for the current project (inferred from cwd) or workspace-wide; **propose fixes and ask before applying** |
| `/check <slug>` | All three modes against a single project/pipeline |
| `/check docs` | Docs mode only |
| `/check ledgers` | Ledgers mode only |
| `/check cite` | Citation mode only |
| `/check <mode> <slug>` | One mode, one repo |
| `/check --full` | Show every instance in the report (not the grouped summary) |
| `/check --json` | Raw JSON output, no proposals — for CI, tooling, or "just tell me how dirty it is" |

## Finding the workspace root

Workspace root contains `CLAUDE.md` alongside `projects/`, `pipelines/`,
`ideas/`, `research/`. Search upward from cwd; project root is
`$ROOT/projects/<slug>/`. If neither cwd nor an explicit slug resolves, fail
with a useful message.

## Procedure

### 1. Resolve mode and scope

- Mode: `docs`, `ledgers`, `cite`, or `all` (default). If the first
  positional arg matches a mode keyword, treat it as the mode; otherwise
  treat it as a slug and use mode `all`.
- Scope: explicit slug, cwd's project, or workspace-wide if neither.

### 2. Run the underlying tool(s)

For each requested mode:

```bash
# docs
python3 $ROOT/research-kit/tools/check_docs.py [<slug>] --json

# ledgers (project-scoped only — no workspace-wide rollup)
python3 $ROOT/research-kit/tools/coverage.py --project $PROJ --json

# cite (lint mode; --sync is /cite-sync's responsibility)
python3 $ROOT/research-kit/tools/citations.py [<slug>] --json
```

If any tool errors, surface the traceback — do not silently fall back. If
`coverage.py` is missing, surface a hint to clone `research-kit`. If
`pyyaml` is missing, tell the user to `pip install pyyaml`; don't try to
install it yourself.

### 3. Render the focused report

Open with a one-line summary: `N gaps across {docs, ledgers, cite}` and
the totals.

For each mode, group findings by code and show counts + first 3 examples,
truncating with `… +N more`. `--full` enumerates every instance.

Use the underlying tool's grouped output for all three modes.

### 4. Propose fixes

This is the default. For every finding, derive a concrete fix (or a routed
follow-up). The interaction shape differs by mode because the work differs:

**Docs (`/check docs`): enter plan mode with the full fix list.**

Each finding gets a templated fix from `fixes.md` (sibling file). Build the
complete plan as a numbered list grouped by repo, then call `EnterPlanMode`
with the plan. The user sees every change at once and approves or redirects
before any edit lands. On approval, execute the file ops (renames, moves,
new files, merge `validate=` insertions) and commit per repo with the
message format in `fixes.md`. Findings without a templated fix
(`.merge() validate=` value choice, `archive.leakage`) go in a
**Manual review** section at the end
of the plan — surfaced but not auto-applied. Common fixes:

| Gap | Default fix |
|---|---|
| `doc.missing` | Create the file with the canonical heading template |
| `doc.unallowed` | Rename to canonical (e.g. `todos.md` → `todo.md`) or move to `briefs/`/`notes/`/`reference/` based on content |
| `*.naming-violation` | `mkdir` the script-named folder and `git mv` the sibling outputs into it |
| `*.orphan` / `*.orphan-folder` | Either rename the script to match, or delete the orphan (ask which) |
| `source.no-output` (data layers) | No fix — surface as manual ("build may be unbuilt") |
| `source.merge.no-validate` | Manual review — pick `one_to_one`, `many_to_one`, etc. per call |
| `project.no-claude-md` | Create `CLAUDE.md` at project root with a one-line summary + pointer to `docs/summary.md` |
| `gitignore.no-build` | Add `build/` to `.gitignore` (create the file if missing) |
| `decisions.bad-header` | Rewrite the header to `## YYYY-MM-DD — <title>` (em-dash). Auto-fix if the date is parseable; manual otherwise |
| `handoff.bad-filename` | `git mv` to `<ISO-timestamp>_<short-tag>.md` (manual: pick the right tag) |
| `source.underscore-cited` | Manual review — either rename the script to drop the underscore (and let it be a real artifact) or rewrite the citing doc to point elsewhere |
| `analysis.design.unknown-key` | Manual review — either fold the value into an allowed `design:` key (or `notes`), or, if it recurs across analyses, add the key to `docs/reference/analysis-schema.yaml` |
| `stale.runtime-disclaimer` | Auto — delete the `NOT runtime-tested` / `parse-checked only` line. The affordance was retired 2026-05-29 (see `research/rules/synthetic_and_bypasses.md`); the disclaimer is residual text, not a live convention. /check flags residue only; the queue/export skill (e.g. `/connect-run`) gates new scripts on the actual runtime test |

**Ledgers (`/check ledgers`): numbered list, per-gap apply/skip/quit.**

Plan mode is a bad fit here because most ledger gaps route to *other gated

From hsigstad/research-kit, MIT.

More from hsigstad/research-kit