agentsclimarketplace

Diagnose

Skill yoelgal/better-dev/skills/diagnose

Use when a bug, regression, crash, flaky test, or a report that "X is broken / throwing / failing / slow", "why is prod down", or "make it faster" needs root-causing before any fix - the fix-side entry into the work-item loop, where a symptom becomes a reproducible red signal and a root cause.From its SKILL.md

Install
npx -y skills add yoelgal/better-dev --skill diagnose

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

18.1 KB, as published. Nobody here has run it

Diagnose a bug into a fix-contract

The front-end for a fix/ work item. Turn a bug report into two things the loop can drive: a red-capable signal (a command that already fails on this bug) and a falsifiable root cause. Package them as a fix-contract in the ledger and hand off to /autonomous-loop, which drives the same red→green loop a feature does. One job: make the bug reproducible and explained before anyone touches a fix.

Honor this project's recorded decisions - from your harness's durable memory where you have it, otherwise from the brief you were given (see /overrides). A repro command, a test seam convention, or a "we never instrument prod" rule wins over anything here.

Locate the repo's contribution guide in the same setup read: an override may pin its path; else look for CONTRIBUTING.md or a coding-standards file at the root, under docs/, or under .github/. If present, read it - documented test requirements feed the fix-contract's done-criteria, PR-size and process rules feed the fix scope, and branch/commit conventions ride the contract as premises. The fix-contract carries one census line - "contribution guide: CONTRIBUTING.md" or "no contribution guide found" - so a missed guide is a visible miss, not a silent one.

Before you re-derive anything about this area, read what earlier sessions recorded about it - the recorded lessons, from your harness's durable memory where you have it, otherwise from the brief you were given (see /overrides) - and cite what it returned, or an explicit "nothing recorded": a lesson you already paid for is cheaper than the mistake it prevents. A recalled lesson is a prior claim, not a current fact - verify it against today's code before acting on it. A fix item carved by /groundwork also reads its epic's record first (.better-dev/ledger/<epic>/groundwork.md) and enters the settled decisions as settled; a fix that can't proceed without contradicting one stops and shows the conflict rather than absorbing it - plan-grill's carved-item entry rule, same form here.

The order below matters: a theory before a red signal is the exact failure this skill exists to prevent. Don't skip forward.

Phase 0 - Verify the premise

Before building anything, check that the bug is real and the expectation is sound. A bug claim has two parts: the claimed-actual (what the reporter says happens) and the claimed-expected (what they say should happen - often unstated in a symptom-only ticket; record it as not stated).

The cheapest evidence in the whole skill is the artifact you already hold: read the whole error and the full stack trace, end to end - not just the top line. The failing frame, the message, the exit code, and the values they name localize most bugs before any file is opened. Read it before you theorize about it.

One bounded observation pass, cheapest first: locate the code path and read what it actually does on the reported input; find any intent contract - a test, spec, validation rule, or doc that asserts the current behavior is deliberate; run the cheapest already-wired check if one is cheap. The deliverable of this pass is a verdict with receipts, not a change - no fix, no plan, no hypotheses yet.

Three outcomes send you back to the reporter instead of into a fix:

  • The claimed behavior doesn't actually occur (you tried, and it works).
  • The requested behavior already works, possibly under a different surface.
  • An intent contract says the current behavior is deliberate - the premise, not the code, is likely wrong.

In those cases, stop and return the evidence to the reporter (a NEEDS_INPUT stop): the right next move is a conversation, maybe closing the ticket, not a PR. Otherwise the deviation is confirmed and you continue. Receipts throughout - file:line, the command and its output - a verdict without receipts is just a guess.

The symptom-only gate (a bright line, not a suggestion). A symptom names a deviation - "X is wrong / broken / slow" - but rarely states the concrete correct behavior. Never fill that gap by guessing the expected behavior from the symptom: a guessed expectation gets baked into the Phase 4 red signal and regression test, so the loop then drives green against a made-up target and may happily "fix" a non-bug. When the claimed-expected is not stated, source it from the reporter, a spec, or an intent contract before you write the fix-contract - cite where it came from. If none can state it, halt with a NEEDS_INPUT stop that quotes the symptom and asks for the correct behavior (or a pointer to where it's specified); don't proceed on an invented one. This is the same discipline /plan-grill applies to feature baselines - a goal you can't state concretely isn't one you can prove. A report whose claimed-actual is only an adjective - "it's slow", "it feels flaky" - with no event, no wrong output, and no artifact to read is not yet a symptom either: enter /brief-to-problem to recover the event the word compressed, and come back with the concrete deviation it names.

Phase 1 - Build a red-capable signal

This is the skill; everything after it is mechanical. The loop cannot run without this, so spend disproportionate effort here - be creative, don't give up early.

Produce one command you have already run at least once that goes red on this bug. Paste the invocation and its red output. It must be:

  • Red-capable - it drives the real bug code path and asserts the user's exact symptom, so it goes red now and green once fixed. Not "runs without erroring" - it has to catch this bug.
  • Deterministic - same verdict every run. A non-deterministic bug means raising the reproduction rate until it's debuggable, not chasing a clean one-shot.
  • Fast - seconds, not minutes. A 30-second flaky loop is barely better than none.
  • Agent-runnable - you can run it unattended.

For the ladder of ways to construct a signal (failing test, curl, CLI diff, headless browser, replayed trace, throwaway harness, fuzz loop, bisection, differential run, and the human-in-the-loop last resort), how to tighten it, and how to handle non-deterministic bugs, read signal.md.

If you catch yourself reading code to build a theory before this command exists, that's the failure this phase prevents - come back and build the signal first. If a first attempt doesn't reproduce, don't jump to handing back - the shape of the non-reproduction is itself a lead: read signal.md's non-reproducible triage (timing / environment / state / truly-random), and for a bug that is live in production its incident path (stabilize first, then read telemetry as the signal), before you conclude no loop exists. If you genuinely cannot build one after that, stop and say so: list what you tried and ask for env access, a captured artifact (HAR, log dump, core dump, timestamped recording), or permission to add temporary instrumentation (a NEEDS_INPUT / BLOCKED stop). Don't proceed to hypotheses without a loop.

Phase 2 - Minimise the repro

Once it's red, shrink to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps one at a time, re-running the signal after each cut - keep only what's load-bearing. Done when removing any remaining element turns it green. A minimal repro shrinks the hypothesis space in Phase 3 and becomes the clean regression test in Phase 4.

Phase 3 - Root-cause via falsifiable hypotheses

Recall first. Before generating any hypotheses, distill the red signal into a failure signature - the stable fingerprint of this failure, drawn from the whole error and stack you read in Phase 0, not the run that happened to expose it: the error class and message shape, the top frames of the stack, the failing assertion, the symptom in one line. Search the recorded lessons for a prior diagnosis of the same shape - your harness's durable memory where you have it, otherwise what the brief carried (see /overrides). A confident match returns a known root cause and the fix that resolved it last time - apply it and re-run the Phase 1 signal to confirm it goes green here too, rather than re-deriving from scratch. A match that no longer holds (the signal stays red) isn't wasted: it rules out a candidate and tells you the shape recurred for a new reason. No match, or a stale one, drops you into fresh hypotheses below. Where the signature looks like someone else's bug rather than ours - a dependency's error text, a platform behaviour, a symptom that appeared at a version boundary - spend one light /deep-research pass on the prior art before generating hypotheses: an upstream issue naming the cause beats five hypotheses of our own.

Before free-generating, run the failure signature down the pattern table - a matched row seeds one ranked hypothesis with its search area attached; no match just means every hypothesis is fresh, not that the table was skipped.

PatternSmells likeFirst place to look
Race / orderingintermittent, timing- or load-dependentshared state on concurrent paths; the awaits and callbacks nearest the symptom
Null propagationTypeError / null deref far from an obvious causewhere the value was allowed to become null, not where it crashed
State corruptioninconsistent data, partial writes, works-then-doesn'ttransaction boundaries, error paths that skip cleanup, hooks
Off-by-one / boundaryfails at empty, first, last, or size-limit inputsloop bounds, index math, pagination
Missing validationcrash or corruption on malformed inputthe trust boundary the input crossed uninspected
Integration drifttimeouts, unexpected shapes from a dependencythe external call site and the contract or version it assumes
Stale cache / stateold data shown after a change definitely landedcache keys and invalidation, memoization, state not re-derived

Write 3-5 ranked hypotheses before testing any of them - generating one at a time anchors on the first plausible idea. Each states a prediction that could falsify it: "if X is the cause, then changing Y makes the bug disappear (or changing Z makes it worse)." A hypothesis with no prediction is a vibe - sharpen it or drop it. Show the ranked list to the user before testing; they often re-rank it instantly ("we just deployed a change to #3"). Cheap checkpoint - don't block on it if they're away.

After ranking, spend one more recall keyed to the top hypothesis's component - the noun stem of the module or file it accuses (auth-cookie, session-expiry), never a sentence or a path. The entry recall was keyed to the area and the signature recall to the failure's shape; this one surfaces prior work on the specific component now under suspicion. Cite the hit, or the explicit recall empty.

Test one variable at a time. For the instrumentation mechanics - local cheap-experiment loops versus parallel fan-out for cross-service bugs, tagged trace probes and log peppering, routing verbose output to disk, and building the evidence chain - read instrument.md.

If three ranked hypotheses each fail against their own falsifying prediction, stop generating - a fourth guess is where a wrong fix comes from, and an unresolved diagnosis recorded plainly beats a speculative one. Settle NEEDS_INPUT carrying three things: the three falsifications (what each predicted, what the probe showed), what you now suspect and why you can't confirm it, and a menu of the three honest next moves for the reporter to pick:

  • Continue - only against a genuinely new hypothesis you name in the ask, never a re-rank of the three that died.
  • Escalate - to someone who knows this subsystem; attach the evidence chain so far.
  • Instrument and wait - land a diagnostic work-item instead of a fix: a valid fix/ work-item whose deliverable is targeted probes at the boundaries the three failures implicate, plus a narrow alert on the failure signature, so the next real occurrence arrives captured (the same capture-the-next-occurrence move signal.md uses for truly-random bugs, offered here as a deliberate deliverable). Its done-criteria are observable like any other work-item's - the probes land and the alert demonstrably fires on the signature - with no red-goes-green signal to chase.

The fix-contract is never written from a hypothesis that survived only by default.

Fix the root cause, not the symptom. Before you settle where the fix lands, produce the caller list: every caller of the function you'd touch - the lsp tool's references action returns them, the aliased and re-exported ones a name-grep misses included - and record them in the evidence chain. One guard in the shared function all callers route through is a smaller, more correct change than a guard in the single path the ticket named - which leaves every sibling caller broken. Guarding at the surface - swallowing an unexpected null, de-duping in the view, wrapping the throw in a try/catch - hides the deviation instead of fixing it; if a value is unexpectedly null, the bug is wherever it was allowed to become null, not where it finally crashed.

The caller list also prices the fix before it exists. Read the planned fix's blast radius as evidence, not a work estimate: one file, additive, reads as the right layer; a fix that needs edits in more than a handful of files - or in every caller - is a wrong-layer signal. A large fix usually means the root cause lives one layer further in, where a single change covers what the wide fix patches piecemeal - re-check the layer before writing the contract. This is a diagnosis check, distinct from the repo's safety-scope gate (~10 files by default), which stops a sprawling diff for a human at loop time: a planned fix already near that number before any code exists means the diagnosis is wrong, not that the schedule is big.

Land the diagnosis as an evidence chain: symptom observed → checked source → found evidence → confirmed by a second source → reproduced. That chain, plus the correct hypothesis, is the root cause.

Phase 4 - Write the fix-contract and hand off

Write contract.md into the primary checkout's .better-dev/ledger/<slug>/ - the ledger is shared across worktrees, and the fix worktree doesn't exist yet, so resolve that path with dirname "$(git rev-parse --path-format=absolute --git-common-dir)". The contract is what makes the loop's done-criteria observable rather than asserted:

  • Red signal - the exact command and its captured red output. This is the loop's done-when-green.
  • Minimised repro - the smallest failing scenario.
  • Root cause - one sentence plus the evidence chain.
  • Fix scope - the narrowest set of paths the root cause and caller list implicate: one directory, a short explicit file list, or repo-wide plus one sentence of why (a missing reason is a missing scope). Declared only now, after the root cause - a scope guessed at investigation start locks the wrong module. The scope is a prose tripwire the loop reads and honors, never a mechanical boundary - nothing refuses an edit outside it - so it carries its reason recorded beside it.
  • Regression test at a correct seam - a seam that exercises the real bug pattern at the call site. A too-shallow seam (a single-caller unit test for a bug that needs several callers) gives false confidence. If no correct seam exists, that itself is the finding: note it - the architecture is preventing the bug from being locked down - and flag it for follow-up rather than testing at a wrong seam. The test body carries a one-line attribution comment - the work-item slug and the one-sentence root cause - so a future red on this test identifies itself as this bug recurring, not as a new mystery or a flake candidate.
  • Merge disposition - the same seal question /plan-grill's done-contract defines settles the fix-contract's merge: auto | hold line and its gated-paths line; a fix earns auto-merge exactly the way a feature does, never by being "just a fix". The gated-paths line earns its keep here in particular: a diagnosis already knows the file the root cause sits in, so whether the fix lands on a gated path is answerable now rather than at merge, and a fix is the work-item most likely to be aimed straight at machine-touching or high-consequence code.

Then hand to /autonomous-loop. The same loop that builds features drives this red→green: it writes the regression test, watches it fail, applies the fix, watches it pass, and re-runs the Phase 1 signal against the original scenario. The fix's done-criteria are exactly red signal goes green + regression test at a correct seam - no new discipline for the loop to learn; the merge line above rides the contract for the PR stage, not the loop.

When the diagnosis was fresh (nothing recorded matched), close the loop that Phase 3 opened: write the failure signature → root cause + fix in your harness's durable memory (see /overrides) so the next occurrence of this shape hits the fast-path instead of re-deriving. Record the durable thing - the root cause and the fix that resolved it, plus any repro technique worth reusing - never the transient run that surfaced it (a one-off timeout, a flake seed, a machine-specific path).

Composability

Diagnose adds; it never replaces an installed debugger, test runner, or observability skill - it sequences them. On a production incident with no telemetry to read, this project's recorded obs-* lines name the gap, and once the incident is stabilized /observability-install is the route that fills it - per-incident instrumentation covers this diagnosis, not the next one. It's the fix-side twin of /plan-grill (the feature front-end); both feed the same /autonomous-loop. A live production incident is diagnosed here first; once the fix lands through the loop and /pr-and-verify, /release-promotion carries the hotfix to both branches. When revising this skill, follow /writing-skills.

Gives 0 of the 12 instructions most test skills give

Counted across 1,201 of the 2,096 authors here whose files we hold, read 2026-09-06

  • Write a failing test before writing codein 43 of 1201, across 36 files
  • Run the full test suitein 36 of 1201, across 35 files
  • Test only one variable per experimentin 34 of 1201, across 17 files
  • Read product marketing context before asking questionsin 34 of 1201, across 14 files
  • Mock external dependenciesin 34 of 1201, across 30 files
  • Define primary, secondary, and guardrail metricsin 33 of 1201, across 16 files
  • Pre-determine sample size before startingin 31 of 1201, across 14 files
  • Test behavior rather than implementationin 31 of 1201, across 29 files
  • Formulate a hypothesis before designing a testin 30 of 1201, across 13 files
  • Document every test hypothesis, variant, and resultin 29 of 1201, across 11 files
  • Use descriptive test function namesin 25 of 1201, across 21 files
  • Commit to the methodology without stopping earlyin 24 of 1201, across 8 files

Said here and by no other author read

  • verify the bug is real and the expectation is sound
  • source the expected behavior from the reporter or documentation
  • build a deterministic and fast red-capable signal
  • minimize the reproduction to the smallest failing scenario
  • distill the red signal into a stable failure signature
  • search recorded lessons for prior diagnoses of the same shape

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.

Keep looking

Skills are one crate of 613,297. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.