loop-doctor

Files (49)

• SKILL.md
• evals.json · evals/
• BAR.md · evals/gauntlet/
• CRITIC.md · evals/gauntlet/
• ROUNDS.md · evals/gauntlet/
• r2-sample-app-LOOP-REVIEW.md · evals/gauntlet/rounds/
• r3-sample-app-LOOP-REVIEW.md · evals/gauntlet/rounds/
• r4-sample-app-LOOP-REVIEW.md · evals/gauntlet/rounds/
• r5-concept-loop-LOOP-REVIEW.md · evals/gauntlet/rounds/
• r6-concept-loop-LOOP-REVIEW.md · evals/gauntlet/rounds/
• verifier.md · fixtures/concept-loop/.claude/agents/
• CLAUDE.md · fixtures/concept-loop/
• ROADMAP.md · fixtures/concept-loop/
• GATES.md · fixtures/concept-loop/docs/
• LOOP-LOG.md · fixtures/concept-loop/docs/
• RESUME.md · fixtures/concept-loop/docs/
• expect.json · fixtures/concept-loop/
• intent.md · fixtures/concept-loop/
• loop.sh · fixtures/concept-loop/scripts/
• scheduled_tasks.lock · fixtures/instructed-loop/.claude/
• CLAUDE.md · fixtures/instructed-loop/
• LOOPS-archive.md · fixtures/instructed-loop/
• LOOPS.md · fixtures/instructed-loop/
• ROADMAP.md · fixtures/instructed-loop/
• expect.json · fixtures/instructed-loop/
• ENV.md · fixtures/instructed-loop/notes/
• RESUME.md · fixtures/instructed-loop/notes/
• loop-doctor-rescore-2026-09-20.md · fixtures/instructed-loop/notes/
• guard.py · fixtures/instructed-loop/scripts/loops/
• inflight.py · fixtures/instructed-loop/scripts/loops/
• record.py · fixtures/instructed-loop/scripts/loops/
• SKILL.md · fixtures/script-loop/.claude/skills/loop/
• CLAUDE.md · fixtures/script-loop/
• BACKLOG.md · fixtures/script-loop/docs/
• DEFINITION-OF-DONE.md · fixtures/script-loop/docs/
• HUMAN-GATES-LOG.md · fixtures/script-loop/docs/
• LOOP-STATUS.md · fixtures/script-loop/docs/
• LOOPS.md · fixtures/script-loop/docs/
• MANUAL-ACTIONS.md · fixtures/script-loop/docs/
• expect.json · fixtures/script-loop/
• intent.md · fixtures/script-loop/
• loop.ps1 · fixtures/script-loop/scripts/
• checklist.md · references/
• loop-concept.md · references/
• patterns.md · references/
• report-template.md · references/
• scorecard.md · references/
• tick-model.md · references/
• inventory.mjs · scripts/

SKILL.md (first lines)

# Loop Doctor

A scheduled loop runs when nobody is looking, and its design is never in
one file: scheduler → driver → skill → rules in `CLAUDE.md` → a
definition-of-done → a gate log → a state file. Each was written at a
different time, and they drift. The loop keeps running on whichever copy
it happens to read.

Loop-doctor has two modes. **Review** (the default) produces one artifact —
a review that is **diagram first, score second, rows third** — and costs the
project nothing. **Setup** (only when asked to set up, design or fix a loop)
walks through the few decisions the project must make and writes the loop's
rules and config as one diff, after approval. Both measure against
`references/loop-concept.md`, the complete loop: roadmap-driven, re-planning
from intent, try-verify-adjust until right, challenged at milestones against
a cited bar, spending in proportion, with Jev at fixed points when present.

```mermaid
flowchart LR
  A["inventory.mjs<br/>≤ 2 s · read-only"] --> B["map onto<br/>the tick"]
  B --> C["audit<br/>Invalid · Redundant · Risk"]
  C --> D["score<br/>10 × 0–5 → health"]
  D --> E["prescribe<br/>what closes a finding"]
  E --> F["review<br/>diagram · score · rows · do-next"]
  F -. only when asked .-> G["apply"]
```

## The guard-rail: no overhead on the project

The person calling loop-doctor is asking a question, not adopting a tool.
So:

- **Write nothing into the target repo** in review mode. The review goes to the
  scratchpad (and to a published page if that's how they read things). If
  they want it in the repo, they name the path and you write exactly that
  one file.
- **Run nothing of the project's.** No install, no build, no tests, no
  `refresh` command. Only `git log`/`git show`/`git status` and the
  inventory script.
- **Read from the digest, not the files.** The inventory's `rulesDigest`
  (the lines that govern behaviour, with file:line, the sections a tick
  uses first) and `sections` (every heading's line range, `used` where the
  loaded rules point) are the reading. Open a file only to confirm a
  finding's citation or to read a `used` section the digest can't settle —
  and batch those reads, several ranges in one command. **Budget: ~1,500
  lines of governing text opened in all** — the rules files, the sections a
  tick uses, the scripts the rules run, and the intent and config sections;
  the skill's own files don't count. The receipt reports the number.
  Cost is context × turns: ten batched reads beat fifty single ones. State
  files by header, first screen and last screen — the inventory gives their line counts, and
  the count *is* the finding. Never read a queue or log end to end,
  unless it is under about 40 lines; say so in the receipt.
- **Stay blind to earlier reviews.** Don't open the files the inventory
  lists under `priorReviews`; a previous score anchors the new one. The
  footer says they were skipped.
- **No subagents by default.** One context, one pass. The inventory
  already did the mechanical work.
- **Leave a receipt.** The review's footer says how many files were read,
  that no state file was read whole, and that the target repo is
  untouched — so the reader can see the cost.

## Workflow

### 1. Inventory

```bash
node <skill-dir>/scripts/inventory.mjs <repo-path> > <scratchpad>/loop-inventory.json
```

Triggers (cron, launchd, workflow `schedule:`, `/loop Nm`, cloud-routine
mentions), drivers, governing docs, loop skills/commands, agents, state
files with size and growth, the intent document and who references it,
queue sharpness, and the cheap checks: repeated sentences across files,
dangling references (dead vs moved), numbers that disagree for the same
phrase, terminal sentinels with entries after them, swallowed errors,
single-OS drivers. Under `concept`: a loop config file, Jev calls (from
the driver or a hook, or only in docs), verifier agents, kill-switch, cap,
inner-loop and challenge mentions, and milestone tags — the evidence for
step 5b. `runway` holds what could stall the loop (re-arm evidence, the
lock and its stale rule, the oldest open gates, the empty-queue rule) and
the recent record commits. Read all of it. It is evidence, not conclusions.

No trigger, no driver, no loop docs → this project has no scheduled
loop. Say so in three lines and stop.

### 2. Map onto the tick

`references/tick-model.md`. Fill the eight nodes — trigger, wake, select,
act, verify, gate, record, re-arm/stop — with the project's real file
names and numbers. A node with two answers is a finding; a node with none
is usually the worse one. Answer the three questions once each: who owns
"done", where does state live between ticks, do human gates block or log.
Climb the empty-queue ladder (steady state → re-plan from intent as
proposals → bounded explore) and note which rungs exist.

State the **runway** in one line: how long the loop can run unattended
and what stops it first — a real stop (goal met, steady state, a written
cap, `HALT`, an escalated repeat failure while other work continues) or a
stall (a person needed for reversible work, a blocking gate with nothing
else to take, an empty queue with no refill rule, no re-arm, a lock with
no stale rule, "continue" typed by hand, a rule the loop skips without
saying so). The first stall is the blocker, with file:line; add an
estimate in ticks or days only when cadence, cap and queue length are all
written down, labelled *estimate*. Check the recent record commits
(`runway.recentTicks`) against what the selection rule would have picked —
a loop that silently skips its own rule stalls in the worst way: it keeps
running. `tick-model.md` has the lists.

State **built vs declared** in one sentence: what runs today, what the
documents describe in the present tense that is only planned, simulated
or dormant. In every real loop reviewed so far this was the sentence the
reader needed most.

### 3. Audit

`references/checklist.md` — every item says why it matters unattended and
how a miss is classified:

- **Invalid** — the loop does not do what its files say, or cannot.

From Busy-Office/ai-skills, MIT.

More from Busy-Office/ai-skills