diff --git a/SKILLS_INDEX.md b/SKILLS_INDEX.md index f984028..031bf2c 100644 --- a/SKILLS_INDEX.md +++ b/SKILLS_INDEX.md @@ -30,6 +30,7 @@ This index lists all available engineering skills. Load the full SKILL.md on dem | `discovery-framing` | Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing | | `stage-gate-review` | Stage-gate product governance (go/no-go council) | Preparing a Product Council ask; building a go/no-go checklist; gate review | | `web-shot` | Screenshot a running web UI via a koala k3s Playwright job | Visual verification of a running UI when no local browser exists | +| `cad-babysit` | Focused human-in-the-loop session working CAD's stuck queue (read-only) | Picking up whatever `cad stuck` flags, with a human present | | `superpowers-brainstorming` | Structured divergent brainstorming | Generating or expanding a set of ideas | | `superpowers-writing-plans` | Writing implementation plans | Planning substantial work before coding | | `superpowers-executing-plans` | Executing a written plan step by step | Running an approved plan to completion | diff --git a/skills/cad-babysit/SKILL.md b/skills/cad-babysit/SKILL.md new file mode 100644 index 0000000..82d365e --- /dev/null +++ b/skills/cad-babysit/SKILL.md @@ -0,0 +1,263 @@ +--- +name: cad-babysit +description: Focused human-in-the-loop session working CAD's stuck queue (cad-stuck output). Read-only — diagnoses, never dispatches, arms a label, or closes an issue. Use when picking up whatever CAD has run into trouble on, with a human present. +--- + +# CAD Babysit + +## Overview + +A deliberately narrow session: pick up whatever CAD has run into trouble on, work it with a +human present, and stop. This is not an autonomous supervisor — it is a babysitter with a +person in the room, and that is the point, not a limitation to route around later. + +**Core principle:** an unattended supervisor reproduces the exact failure it exists to catch. +`dispatch` ran dead for eight weeks because it exited 0 and nobody noticed (`dispatch#33`); a +long-running watcher process that dies quietly has the same property one level up, and +manufactures false confidence while doing it. With a human present, **the human is the +liveness check** — that removes the objection entirely and needs no new machinery. + +This skill is the ritual around `cad stuck` (`mathias/cad#14`), not a replacement for it. +Without that query it would be a checklist with no input; the query without this skill is +data nobody reads carefully. Neither closes the loop alone. + +## When to Use + +- Picking up CAD's stuck queue with a human present and time set aside to work it +- After `dispatch` (or any executor) reports a failure and it is not immediately obvious + whether it is an infrastructure fault or a real task outcome +- Reviewing the "awaiting human" queue (issues CI has verified but nobody has closed) + +**Do not use for:** +- Unattended/scheduled runs. This skill assumes a human is present for its entire duration — + if nobody is watching, its central safety property (human-as-liveness-check) does not hold. +- Dispatching, arming a redispatch label, or closing an issue. This skill only ever diagnoses; + see Iron Laws. + +## Iron Laws + +1. **Read-only, always.** No dispatching, no arming labels (including `status:redispatch`), no + closing or reopening an issue. A reviewer that can act on its own findings has no + independent check — control stays where it already is. +2. **Every finding cites a locator.** A run id, commit sha, comment permalink, or a specific + log line. A finding without one is an unfalsifiable opinion about a machine — do not emit + it, and do not soften this into "probably" language instead of dropping it. +3. **Re-derive, never recall.** State lives in Gitea and Actions, not in this session. Start + cold every time: run `cad stuck` fresh, do not carry forward a prior session's worklist. + Sessions get compacted and lose exactly the cross-run history that makes a stale worklist + dangerous to trust. +4. **Distinguish "blocked" from "awaiting human".** `cad stuck` already makes this split + (`stuck` vs `awaiting_human`); preserve it in every summary. The `awaiting_human` class is + the human gate working, not a bottleneck — do not report it as one. +5. **Anything that is the operator's call surfaces as `DECISION NEEDED`, never gets decided + for them.** See Output Format. + +## Process + +### Phase 1 — Query (re-derive the worklist) + +Run `cad stuck` against the estate (the `dispatch-repos.txt` scope, or whatever repo set the +operator names). This is the only input. Do not substitute a memory of a prior run, a brain +note, or this issue's own worked examples — all three can be stale within the same day (a +taxonomy row's cited live example can stop reproducing between when it was written and when +you run the query, because the underlying state genuinely changed; that is the design working, +not a bug to paper over). + +Group the output by class exactly as `cad stuck` returns it: `stuck` first, `awaiting_human` +second. Pick ONE row to work per pass — this skill is deliberately narrow, not a full-estate +sweep. + +### Phase 2 — Read the issue's own comments FIRST + +Before anything else, before touching Actions or pod logs: read every comment on the issue, +oldest first. This step exists because it was skipped once and it cost a session — a confident +wrong root cause was produced from pod logs while the correct diagnosis sat in the issue's own +comment thread from nine days earlier (`cad-atlas#10`). The rule "read issue comments before +working" was already written down elsewhere and was not followed; it is written down again +here because that is exactly the kind of already-known thing a rushed session skips. + +What to look for: the bot's own report comments (routing decision, ground-truth verdict, +attempt count), and any human comment that already contains the diagnosis. + +### Phase 3 — THEN the Actions job logs + +Only after Phase 2 turns up nothing conclusive, read the CI job logs: + +``` +GET /repos/{owner}/{repo}/actions/runs # find the run, match on .run_number +GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs # returns 200, full text, secrets masked +``` + +This endpoint works. A prior note claiming it 404s was wrong and cost a diagnosis the day this +skill was written — do not rediscover that. Get the run id from `/actions/runs`, not from the +`run_number` shown in a comment (they are different fields; match on `.run_number` to find the +internal `id` the jobs endpoint needs). + +This is where the two most valuable findings of the day this skill is drawn from lived: an +agent issuing the identical refused command five times and stopping (never trying the tools it +was actually permitted to use), and a different model, same denial, writing a Go program to +route around it. Neither is visible from the issue comments alone — no metric produces either +of them. They need a reader of the raw transcript. + +### Phase 4 — Separate infrastructure fault from task outcome + +A run that died before turn 1 says nothing about the issue itself. Before concluding anything +about the WORK, check whether the run reached the model at all: + +- Zero turns, a 2-3 record transcript, a "could not start" comment, or a claim label with no + attempt comment behind it → infrastructure fault. This is not evidence the issue is hard, ill + specified, or that the assigned model is unsuitable — it is evidence something upstream + (credit, a key, MCP connectivity, the executor binary) is broken. +- A run that reached the model, drove tools, and stopped on a ceiling, a denial loop, or a + genuine task failure → a real task outcome, worth diagnosing on its own terms. + +Four claim labels were burned this exact way in one estate sweep and the tracker read them as +four handled issues (`dispatch#33`). Get this distinction wrong and everything downstream is +about the wrong thing. + +### Phase 5 — Decide, or say `DECISION NEEDED` + +For each row worked, produce one of: + +- **A closed diagnosis** — cause identified, cited to a locator, no operator judgment call + required (e.g. "infrastructure fault, credit exhausted, see comment #N — retry is automatic + on the next cycle, no action needed"). +- **A `DECISION NEEDED`** — anything that is genuinely the operator's call: whether to close a + verified-but-open issue, whether to raise a ceiling, whether to abandon an issue that keeps + hitting the same denial. Never make this call on the operator's behalf. + +This skill's OWN last act, every time, is to stop — not to dispatch, not to redispatch, not to +close. Ending a pass is itself the enforcement of Iron Law 1. + +## Output Format + +For a closed diagnosis: + +``` +DIAGNOSIS: # — +CAUSE: +LOCATOR: +ACTION: +``` + +For anything requiring a human call: + +``` +DECISION NEEDED: # +QUESTION: +OPTIONS: + 1.