跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

diagnose

For a bug-fix brief, a bug resisting its first fix, or a fix about to ship without a proven cause, reproduce the failure, state its cause with evidence, and keep a regression check before shipping.

timharris707 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add timharris707/skills --skill diagnose

技能说明


name: diagnose description: "For a bug-fix brief, a bug resisting its first fix, or a fix about to ship without a proven cause, reproduce the failure, state its cause with evidence, and keep a regression check before shipping."

Diagnose

Read the Codex desktop binding when this workflow needs harness mechanics, model routing, or recovery.

A fix may not ship without a named cause: one plain sentence stating what was wrong, backed by evidence, readable by a non-engineer decider. This skill is the discipline a working lane follows inline when fixing bugs. It is not a lane type of its own, and it deliberately has no binding slots: everything repo-specific already arrived in the lane's brief.

The named-cause test is the trigger, and it binds on every fix. If you can already state the cause in one sentence and point at the evidence, the loop is satisfied: ship. If you cannot, the loop runs, however small the bug looks. "Hard bugs only" is the wrong gate, because the first fix attempt is where the vibes-fix ships: a change that makes the symptom go away for reasons nobody can state.

The loop

Six steps, in order. A failed fix re-enters at the step whose output it disproved, usually the hypothesis list, sometimes the repro itself.

  1. Reproduce red. Write a failing automated test that catches the user's exact symptom, before any fix attempt; it is the loop you iterate against now and the regression test you keep after. Where test infra genuinely cannot reach the bug (timing, a third-party boundary), the recorded fallback is a documented manual repro with exact steps, flagged as a fallback at close-out, never silently substituted.
  2. Minimize proportionately. Shrink the repro until it is tight, fast and deterministic enough to iterate against, cutting one element at a time and re-running after each cut. Tight is the purpose and the stopping point: a two-second deterministic loop is the tool; shrinking past it is polishing the repro instead of finding the cause. Non-deterministic bugs minimize toward a reproduction rate high enough to debug against.
  3. Hypothesize falsifiably. Generate several ranked hypotheses before testing any: a single hypothesis anchors on the first plausible idea. Each is stated so evidence could kill it, skeptic-style: "if X is the cause, then changing Y makes the bug disappear." A hypothesis with no prediction is a vibe; sharpen it or discard it.
  4. Instrument. Evidence gathering precedes any fix attempt. Each probe maps to one hypothesis's prediction, changing one variable at a time: a breakpoint beats ten logs, targeted logs beat logging everything and grepping. Tag every debug probe with one unique prefix so cleanup is a single grep. When a check fails, suspect the observation method before the system: indirect evidence (mtimes, cached screenshots, self-reports) feels cheaper than direct observation and lies more often.
  5. Fix. Only against the hypothesis the instrumentation confirmed. Watch the red test go green.
  6. Regression-test. Re-run the original, un-minimized repro; keep the failing test from step 1 in the suite as the regression test; grep the probe tag out. Then write the closing artifact.

The closing artifact

Two things, and close-out audits check for both:

  • The named cause: one plain sentence a non-engineer decider reads without translation ("the cache key omitted the locale, so two languages shared one entry"), with the evidence that confirmed it.
  • The regression test: the step-1 test, now green in the suite; or the recorded manual-repro fallback with its exact steps, flagged as a fallback.

An unnamed cause is not done, whatever the symptom is doing.

Structural causes feed the friction gate

Sometimes the named cause says the bug is a symptom: a missing seam, a rule duplicated in N places and updated in N−1. The lane still fixes the instance under this skill's own bar, then reports the structural cause as friction, codebase-review's third entry gate, in its close-out summary. The diagnosing lane never expands its own scope to fix the structure: that is a review-and-disposition matter, decided with more information than the lane has.

Where it sits in the pack

  • Lane briefs: orchestrate points bug-shaped items here, so the discipline arrives with the work.
  • Mid-build bugs: implement routes a bug surfacing mid-build here; the named-cause test binds before the lane resumes building.
  • Close-out audit: the orchestrator's audit checks the two closing artifacts on every bug fix; the named cause is what it reads first.
  • Domain memory: where the repo binds domain-memory, a root cause that reveals a standing fact (an assumption the repo held that the bug just proved wrong) is offered to it as a fact record: the same correction class as a decider correcting a session, with reality as the corrector.
  • Deliberately not hooked: handoff GOTCHAS. The durable copy of a diagnosis's lesson is the domain-memory record; writing it into handoff GOTCHAS too would be the same meaning in two places.

Done when (checkable: verify each line before reporting complete)

  • The cause is stated in one plain sentence with its confirming evidence, readable by a non-engineer decider, or no fix shipped.
  • A failing automated test existed before the fix, caught the user's exact symptom, passes after, and stays in the suite as the regression test; where one genuinely could not reach the bug, the recorded manual repro carries exact steps and is flagged as the fallback at close-out.
  • The repro was minimized until tight, fast and deterministic enough to iterate against, and no further.
  • Every hypothesis tested carried a falsifiable prediction, and the fix answers the hypothesis the instrumentation
阅读完整来源 ↗