Diagnose

Why this workflow exists

The most common bug-fixing failure is patching while guessing: no reproduction, a speculative cause, and no proof the fix worked. Diagnose forces evidence first — reproduce, locate, then repair — and stays completely read-only until you authorize a fix. After authorization, the first write must be a regression test that is observed failing before any production code changes.

How it runs, stage by stage

Every rule below is taken from the workflow definition in the source repository — this is what the agent is actually told to do.

1. 01

   Pin the symptom and signal

   Say exactly what is wrong, then build the fastest way to see it happen.

   • State the expected versus the actual behavior.
   • Read applicable instructions and docs, plus the relevant implementation, tests, callers, and recent changes.
   • Build the fastest practical signal for the exact symptom: focused test, command or request, replay, minimal harness, stress loop, or performance measurement.
   • Tighten that signal for speed, determinism, and unattended execution.
   • Inspect once and reuse the evidence. If automated reproduction is impractical, report what was attempted and calibrate confidence instead of guessing.
2. 02

   Minimize and locate ownership

   Watch it fail, strip it down, and find the module that owns the broken rule.

   • Observe the failure before committing to a cause.
   • Remove inputs, steps, dependencies, and callers while preserving the failure.
   • Follow data and control flow across boundaries, and inspect sibling entry points.
   • Locate the module that owns the violated invariant.
   • Test a small ranked set of falsifiable hypotheses, one distinguishing observation at a time.
   • If you reject the diagnosis, it stays read-only, discards the rejected cause, and looks for new distinguishing evidence — no re-invocation needed.
3. 03

   Repair when authorizedHuman gate

   Read-only until you say fix it — then red before green, with no exceptions.

   • An initial request to fix the defect already grants repair authority. Otherwise the root cause, evidence, repair boundary, and remaining uncertainty are presented and the workflow pauses.
   • A later same-task instruction such as “fix it” grants authority without a Develop invocation.
   • After authority, the first write must change only the regression test. Run it immediately and observe a non-zero failing result before any production code changes.
   • Earlier diagnostic probes, a passing pre-existing suite, or a failed editing tool never replace that red observation.
   • Apply the smallest clear change at the owning boundary, observe focused green, and verify affected sibling callers.
   • When no correct regression seam exists, report the limitation instead of adding a misleading test.
   • If repair requires undefined product behavior or materially expands scope, align that increment and pause for approval first.
4. 04

   Harden around the root cause

   Prevent this class of regression — and nothing more.

   • For a boundary defect, add only adjacent cases that prevent the same class of regression: below/at/above, before/at/after, first/duplicate/concurrent, or allowed/denied.
   • Derive expectations from requirements; do not invent product behavior.
   • Improve the owning design only when the root cause demonstrates scattered rules, hidden effects, repeated variation, distributed state transitions, or an unstable dependency.
   • Do not turn a focused fix into a broad redesign, or apply a pattern without pressure.
5. 05

   Complete

   Re-verify the original symptom and report what remains uncertain.

   • Remove temporary diagnostics.
   • Verify the regression signal, the original symptom, relevant siblings, and one warranted broader check — without rerunning unchanged evidence.
   • Reconcile affected acceptance behavior and authoritative documentation.
   • Report the root cause, evidence, authorized fix, hardening performed, and remaining uncertainty.
   • If you later identify an omitted part of the same defect, repair and verification reopen without repeating the full diagnosis or approval.

Rules that cannot be bypassed

A real invocation

What the conversation actually looks like, from the token you send to the evidence you get back.

1. Agent

   States expected (February 28/29) versus actual (March 3) and builds the smallest reliable reproduction.

2. Agent

   Strips the case down and locates month-end overflow inside the date utility module — not in the caller that reported the symptom.

3. Agent

   The initial request already said “fix”, so repair authority exists: it writes only the regression test first and shows it failing.

4. Agent

   Applies the smallest fix inside the date utility, observes focused green, and checks sibling callers of the same module.

5. Agent

   Reports the root cause, the evidence, what was repaired, what was hardened, and what remains uncertain.

When to use it

• A bug, regression, intermittent fault, wrong output, or measured slowdown.
• You want an evidence-backed root cause before anyone changes code.
• The repair must leave behind a test that catches this regression.
• A previous fix did not hold and you need to know why.

When to reach for something else

Questions