loop-doctor
Reviews — and, when asked, sets up — a project's autonomous, scheduled loop — the routine that wakes on a cadence (cron, launchd, a /loop interval, a cloud routine, a CI schedule, a driver script in a sleep loop, a tick counter), does work unattended, and re-arms. Draws how one tick works from the project's real files, scores the loop on ten dimensions (correctness, safety, reliability, cost, maintainability, understandability, observability, purpose, improvement, proportionality), finds redundant and contradictory rules across the governing files, finds invalid detail (dead references, tripped stop sentinels, competing drivers, unbounded state files, gates the actor can approve itself), and compares the loop against a complete loop concept — works through the roadmap, re-plans from intent when it runs dry, tries-verifies-adjusts until the work is right, challenges finished work against a cited bar, spends in proportion, and uses Jev (if present) for cheap decisions at fixed points. Prescribes what closes each finding; in setup mode writes the loop's rules and config after approval. Use whenever someone asks how their loop / tick / wake / orchestrator / routine works, wants it reviewed, scored, benchmarked, audited, simplified or made safer, says the loop is stuck, drifting, doing busywork or "doesn't stop", asks what a scheduled agent actually does each run, or wants to design a periodic autonomous loop and check it before turning it on.
- License 许可
- MIT
- 最近更新
- 2026-09-27
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- loop-doctor
- description
- Reviews — and, when asked, sets up — a project's autonomous, scheduled loop — the routine that wakes on a cadence (cron, launchd, a /loop interval, a cloud routine, a CI schedule, a driver script in a sleep loop, a tick counter), does work unattended, and re-arms. Draws how one tick works from the project's real files, scores the loop on ten dimensions (correctness, safety, reliability, cost, maintainability, understandability, observability, purpose, improvement, proportionality), finds redundant and contradictory rules across the governing files, finds invalid detail (dead references, tripped stop sentinels, competing drivers, unbounded state files, gates the actor can approve itself), and compares the loop against a complete loop concept — works through the roadmap, re-plans from intent when it runs dry, tries-verifies-adjusts until the work is right, challenges finished work against a cited bar, spends in proportion, and uses Jev (if present) for cheap decisions at fixed points. Prescribes what closes each finding; in setup mode writes the loop's rules and config after approval. Use whenever someone asks how their loop / tick / wake / orchestrator / routine works, wants it reviewed, scored, benchmarked, audited, simplified or made safer, says the loop is stuck, drifting, doing busywork or "doesn't stop", asks what a scheduled agent actually does each run, or wants to design a periodic autonomous loop and check it before turning it on.
02 资源文件 47
- 参考文档evals/evals.json4.8 KB
- 参考文档evals/gauntlet/BAR.md5.8 KB
- 参考文档evals/gauntlet/CRITIC.md569 B
- 参考文档evals/gauntlet/ROUNDS.md4.2 KB
- 参考文档evals/gauntlet/rounds/r2-sample-app-LOOP-REVIEW.md13.2 KB
- 参考文档evals/gauntlet/rounds/r3-sample-app-LOOP-REVIEW.md14.2 KB
- 参考文档evals/gauntlet/rounds/r4-sample-app-LOOP-REVIEW.md14.6 KB
- 参考文档evals/gauntlet/rounds/r5-concept-loop-LOOP-REVIEW.md10.1 KB
- 参考文档evals/gauntlet/rounds/r6-concept-loop-LOOP-REVIEW.md16.0 KB
- 参考文档fixtures/concept-loop/.claude/agents/verifier.md106 B
- 参考文档fixtures/concept-loop/CLAUDE.md1.3 KB
- 参考文档fixtures/concept-loop/docs/GATES.md73 B
- 参考文档fixtures/concept-loop/docs/LOOP-LOG.md61 B
- 参考文档fixtures/concept-loop/docs/RESUME.md53 B
- 参考文档fixtures/concept-loop/expect.json907 B
- 参考文档fixtures/concept-loop/intent.md193 B
- 参考文档fixtures/concept-loop/ROADMAP.md507 B
- 脚本fixtures/concept-loop/scripts/loop.sh182 B
- 其他fixtures/instructed-loop/.claude/scheduled_tasks.lock—
- 参考文档fixtures/instructed-loop/CLAUDE.md251 B
- 参考文档fixtures/instructed-loop/expect.json804 B
- 参考文档fixtures/instructed-loop/LOOPS-archive.md114 B
- 参考文档fixtures/instructed-loop/LOOPS.md240 B
- 参考文档fixtures/instructed-loop/notes/ENV.md24 B
- 参考文档fixtures/instructed-loop/notes/loop-doctor-rescore-2026-09-20.md32 B
- 参考文档fixtures/instructed-loop/notes/RESUME.md59 B
- 参考文档fixtures/instructed-loop/ROADMAP.md460 B
- 脚本fixtures/instructed-loop/scripts/loops/guard.py58 B
- 脚本fixtures/instructed-loop/scripts/loops/inflight.py70 B
- 脚本fixtures/instructed-loop/scripts/loops/record.py18 B
- 参考文档fixtures/script-loop/CLAUDE.md398 B
- 参考文档fixtures/script-loop/docs/BACKLOG.md539 B
- 参考文档fixtures/script-loop/docs/DEFINITION-OF-DONE.md110 B
- 参考文档fixtures/script-loop/docs/HUMAN-GATES-LOG.md162 B
- 参考文档fixtures/script-loop/docs/LOOP-STATUS.md233 B
- 参考文档fixtures/script-loop/docs/LOOPS.md263 B
- 参考文档fixtures/script-loop/docs/MANUAL-ACTIONS.md214 B
- 参考文档fixtures/script-loop/expect.json815 B
- 参考文档fixtures/script-loop/intent.md37 B
- 脚本fixtures/script-loop/scripts/loop.ps1299 B
- 参考文档references/checklist.md18.0 KB
- 参考文档references/loop-concept.md18.1 KB
- 参考文档references/patterns.md7.7 KB
- 参考文档references/report-template.md5.8 KB
- 参考文档references/scorecard.md4.6 KB
- 参考文档references/tick-model.md6.6 KB
- 脚本scripts/inventory.mjs36.8 KB
03 SKILL.md 正文
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.
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
refreshcommand. Onlygit log/git show/git statusand 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) andsections(every heading's line range,usedwhere the loaded rules point) are the reading. Open a file only to confirm a finding's citation or to read ausedsection 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
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.
- Redundant — the same rule in more than one place; name the copy the loop actually loads.
- Risk — nothing wrong yet; the design lets it go wrong silently.
One row per finding: id · what · where (file:line) · exact fix. "Consider consolidating" is not a row.
If the loop has a queue, list the ambiguous items — acceptance
unstated, or judgement-worded (improve, look at, consider, clean up) — by
id and file:line, and hand them to requeue. Rewording them is its job.
4. Score
references/scorecard.md. Ten dimensions, 0–5 by the anchors, one-line
reason each citing a file or a number; mean → health label (fit · watch · treat · stop; a 0 in safety caps at treat). The score summarises the
rows; a reader must be able to go from a score line to the rows behind it.
Score last, and score from the reason: write the one-line reason first — a file:line or a number from the project, then the finding ids — count the Invalid ids in it, and apply the ceiling (one → ≤ 2, two or more → ≤ 1) before writing the number. Both gauntlet rounds so far drifted one point high on exactly the dimensions whose reasons cited two Invalids.
5. Prescribe
references/patterns.md. Recommend only what closes a finding or a gap
from step 2, with its cost. Three habits kept beat twelve written down.
5b. Compare against the loop concept
references/loop-concept.md is the target. Go through its slots c1–c26
and mark each present (file:line), missing (where it should live)
or contradicted (both answers). One row for every missing or
contradicted slot; the present ones show in the scores. List every human-input point (start
it, answer a blocking gate, clarify an item, refill the queue, notice it
is stuck, decide it is done) with what removes each. Then the concept's
rules the loop lacks, worded for this project's files, paste-ready for
the rules file the driver actually loads — every placeholder a real name,
and no line that contradicts a rule already in that file. Keep the principles: the human
leaves the critical path, not the decision; good, not just done — in
proportion.
6. Write the review
references/report-template.md, exactly: ≤ 60 words, the tick diagram
with real file names, files-by-role, the score block, the finding tables,
prescriptions, the concept comparison, do-next (≤ 5), footer receipt. Prose outside tables/diagrams/code ≤ 450 words in total (the
paste-ready rule is a code block and doesn't count). Then a terminal
summary of ≤ 8 lines: one sentence on the loop, the health label and
mean, findings by class, the first fix.
7. Apply — only when asked
Invalid and Redundant fixes you proposed, one commit per class, diff shown first. Risk items and pattern adoption stay separate decisions: they change how the loop behaves, and a loop's behaviour should never change as a side effect of being looked at.
Setup mode — only when asked
When someone asks to set up, design or rebuild their loop (not to review it), after steps 1–2:
- Ask only what the files can't answer, each with the concept's default
as the recommendation: where the roadmap and intent live (if the
inventory didn't find them), which kinds of work need which critique
lenses, the per-item and per-week caps, the improvement share, the
escalation channel, and whether Jev is available (
jev doctor). At most seven questions; take "defaults" as an answer. - Draft one diff, written for this project's files: the concept's
rules as a section of the rules file the driver loads (never a second
copy); a
loop.config.jsonwith levels, caps, share, lenses, models, stops, halt file and channel; the role → agent mapping; the Jev calls at their fixed points, each with its fallback, if Jev is available. - Show it and wait. Write only after an explicit yes, as one commit. Never write the scheduler or driver entry — say which to use and why; where money and machines are involved, the person decides.
- Then run review mode on the result, so the new loop gets the same score as any other.
Judgement calls
The copy that's loaded is the real one. A rule in CLAUDE.md, a
SKILL.md and a docs/*.md is obeyed in whichever the driver puts in
context. Keep that one; turn the others into a one-line pointer.
Sentinels are state, not history. A stop rule that greps for
STATUS: COMPLETE works once. If the log continued past it, the stop
rule is broken now. Rank it above almost everything.
Growth is a cost paid every tick. A file read at wake charges its full length to every run. Report lines and growth; if there's no archive rule, propose one with a threshold.
Two drivers is zero drivers. Don't pick the winner; report that precedence is undefined and propose the person choose.
Absence of a stop is a finding; absence of a human is not. Log-and- continue is a legitimate design. It must then have an asynchronous escalation channel and a kill switch — check for those instead.
Intent is read, never written, by the loop. Re-planning from intent when the queue runs dry is the right rung — as gated proposals. A loop that promotes its own proposals is writing its own mandate.
Good, not just done — in proportion. A loop with no challenge step converges on "done"; one that challenges every item never finishes. Look for the middle: one lens on standard items, a real review per milestone, a written share and caps.
The doer never moves the bar. A loop that can rewrite an acceptance line to pass will, eventually. Rank it with self-approval.
Jev advises; code decides. A Jev call that lives only in a skill is a wish; one that replaces the verifier is a hole. Look for it in the driver or a hook, with a fallback, and with its outcomes recorded.
The owner's decisions stand. A slot the owner deliberately left out (Jev at two points only, a rule they refused) is not applicable — owner decision with the file:line, not a gap to argue with. Before pasting or prescribing anything, look for a recorded "refused", "do not re-raise" or "decided" on the same subject; if there is one, don't paste against it — one row saying the concept differs and the owner decided, nothing more.
Continuous means never stalled, not never stopped. A loop that reaches
steady state and stops is healthy; one that always has a next item because
a rule is always true is not continuous, it's unbounded. How clear the
objective is belongs to sharpen-intent; this review checks the loop is
anchored to it and knows when it's met.
No driver script is not no loop. When the Claude session following the
rules is the driver, the scripts the rules tell it to run
(instructedScripts) are its code — guards, recorders, locks.
Say which scale. The score block names the scale (ten dimensions,
loop-doctor 0.3). If the inventory's concept.scoreGates shows the
project gates on a loop-doctor score, give the mean of the first eight
dimensions too, and say the gate's threshold was set on the eight-dimension
scale — a silent scale change moves someone's gate.
Explain before you judge. If the diagram was hard to draw from the files, say so once — that difficulty is itself a finding.
Files
scripts/inventory.mjs— discovery + cheap checks;--self-test.references/tick-model.md— the tick, the empty-queue ladder, the three questions.references/checklist.md— dimensions → checks, with the why.references/scorecard.md— anchors, health label, sharpness.references/patterns.md— prescriptions catalogue.references/loop-concept.md— the target: the complete loop, its roles, Jev points, inner loop, challenge, proportion, doors and stops, config, and paste-ready rules.references/report-template.md— the review, exactly.evals/gauntlet/— the bar this skill's output is graded against.
Related
It hands off rather than repeats: ambiguous queue items to requeue; a
vague or missing intent to sharpen-intent; what the runs actually cost to
loop-economist (which also runs the concept's weekly cost pass); the
shape inside one tick to graph-engineer; every cheap judgement to jev.
Four siblings share this loop's subject and answer different questions:
loop-economist (what the runs actually cost and whether the right agent did
the work), loop-atlas (what the whole thing looks like, and who is on the
crew), requeue (what the loop should be fed next) and sharpen-intent (what
the whole thing is for). This skill judges the design: whether the tick is
sound, safe, and says one thing. When the files are fine but the runs are
expensive, it is the economist's question, not this one. And the shape of
the work inside one tick — how a job fans out across subagents, where the
verifier sits, whether a barrier is earned — is graph-engineer's subject:
this skill reviews the loop around a run, that one the graph within it.
04 同仓库更多 Skills
loop
one tick
wake-weight
暂无简介
solo-flow
Prescribes and audits a trunk-based git workflow for a repository with exactly one writer — a single autonomous agent or loop, with no other humans committing. One branch (main), local-only short-lived work branches, CI as the sole independent check (no PRs, nothing to review socially), and releases as tags cut directly off main rather than a develop/release branch dance. Use whenever someone is setting up or reviewing git/branching/release conventions for an agent-driven or loop-driven repo, asks whether to use GitFlow/GitHub Flow/GitLab Flow/trunk-based development, wants AGENTS.md or CLAUDE.md git rules written, is deciding whether a develop branch or long-lived feature branches earn their keep, or reports branch drift, a forgotten back-merge, or an autonomous loop that got confused about which branch it was on. Also use to sanity-check an existing branching setup that looks like GitFlow but has no other human collaborators to justify it, and when deciding how the agent should isolate each unit of work (git worktrees, a primary checkout that never leaves main, running items in parallel).
sharpen-intent
暂无简介
requeue
Reviews and reorders the queue an engineering loop or team works from — backlog, roadmap, todo, milestones — so the next work picked up is the right work. Pulls every open item with the attributes that decide order (acceptance stated or not, blocked, human-only, duplicated, contradicted between files, stale), ranks them against the project's intent by unblocking power, purpose, readiness, decay and cost, splits them into lanes (the loop can finish it · needs a bounded subloop · needs a gauntlet of approaches · needs a human), rewrites the top vague items into tasks with an object, a test and a bound, and proposes the new order without touching the repo. Use when someone asks what to work on next, wants the backlog or roadmap reprioritised, re-ranked, triaged or cleaned up, says the priorities are wrong or the roadmap is stale, asks which items the autonomous loop should be fed, or arrives from loop-economist because the loop's problem is its input rather than its actor.
progress-dashboard
Publishes a one-page stakeholder progress dashboard for any git project — where it stands, what's waiting on people, whether it's stalled — from whatever records the project keeps (ADRs, decision notes, design graphs, roadmaps, gates, backlogs, changelogs, PRs). Use whenever someone asks how a project is going, wants a status update or progress report, asks "where are we", "what's blocked", "what's waiting on me/us", "what's left", or wants an existing dashboard refreshed.