gauge

gauge

!checklist init ${CLAUDE_SKILL_DIR} --force

An agent works in a loop: act → observe a signal → correct. Its effectiveness is bounded by the quality of the signal at each step — it has no intuition about the system, no memory between sessions, and no "feel" that something is subtly wrong. It knows only what the code, the checker, the test, and the logs tell it. So the highest-leverage thing you can do for an agent is make the codebase's feedback clear.

The goal is not to copy a static language's syntax — it is to reproduce the property a good static language delivers: clear feedback. Decompose "clear" into the dimensions you actually engineer for:

• Fast — it returns inside the agent's working loop (on save, on one command), not minutes later and not only in production.
• Local — it points at the exact site (file, line, sub-expression), not "something failed downstream".
• Attributed — it says why (expected X, got Y; this constraint failed), not just "error".
• Deterministic — same input, same signal; a flaky signal is no signal, because the agent can't attribute it.
• Trustworthy — green means good, and absence of a signal means "fine", not "this path was never checked".
• Un-fakeable — a signal the agent can flip green by hand (delete the assertion, as any, widen the timeout) is noise, not feedback.

No single tool delivers all of this. You assemble clear feedback from several sources, and for each way the code can fail you pick the source that gives the clearest signal cheapest, and push it as far left (early) as it will go. This skill walks a five-stage flight plan and will not fly past a GATE until it is cleared.

Discipline: finish every GATE before the next stage. The checklist tool enforces the order; let it. Commands address stages by name. Recon mode: when this runs as a solo, read-only assessment with no user present (no one to consult at a gate, nothing built yet), the GATEs become a self-check that each stage's failure modes are characterized, and the deliverable is a findings ledger — the six-dimension scoring plus a ranked, scoped fix list — not a built feedback surface. verify <stage> then means "I have diagnosed and ranked this stage's gap," not "I stood the source up."

Read references/agent-feedback-shifts.md first — why feedback quality is the lever for an agent specifically, and why un-fakeable is not optional (an agent games a signal the way it games any gate). Match effort to risk — richly instrumenting a trivial helper is the same waste as leaving a payments path opaque.

Match the reader's fluency. Much of this skill's vocabulary is unavoidably technical (Any, a discriminated union, boundary parsing, mutation testing), and with a fluent engineer that register is correct. But the strictness-by-risk dial and the recon findings ledger are set with whoever owns the code, and not every owner is fluent — read it from how they talk, and gloss a term on first use when they are not. A dial nobody but you understood is a strictness budget one party set; its whole point is a shared call on where rigor is worth its friction.