skillet-refire

a plate comes back to the kitchen. the line's instinct is to fire the same dish again, faster. the chef's job is to find out why it came back first, because a refire of the same mistake comes back twice and now the diner is angrier. this skill is the chef's version of debugging: no fix until the cause of the sendback is known.

core principle: no fixes without root cause first. a fix that makes the symptom disappear without explaining it is not a fix, it is a scheduled second incident. violating the letter of this process is violating its spirit.

intent

use this skill when anything misbehaves: failing test, production bug, build break, flaky or unexpected behavior. deploy it before proposing or attempting any fix, especially under pressure ("ci is blocking everyone", "just get it green") and after a previous fix didn't hold. the goal is to identify the actual root cause, pin it with a failing test, and apply one minimal change that fixes the cause, not just the symptom. the process is faster than thrashing; investigation on a reproduced bug takes minutes. guessing takes hours and ships masks.

inputs

• access to the codebase (local repo or remote read access)
• ability to run the test suite or reproduce the failing condition
• ability to run git log and git diff on recent commits
• schema docs, interface comments, specs for the affected component
• stack trace or error output (full output, not summarized)
• environment details: which branch, which config, which deployment or test environment the failure occurred in
• optional: monitoring/logging access (CloudWatch, DataDog, Honeycomb, etc.) if the failure is production-only or intermittent
• optional: git blame or commit history if the failure is new and you need to know when it started

no external connections or credentials required. this skill is pure investigation and code review.

procedure

phase 1: evidence gathering (find out why it came back)

1. read the error completely. capture the full traceback, line numbers, actual message. download or screenshot it. the cause is frequently named outright. if the error is truncated or redacted, get the unredacted version.

   • input: error message or crash output
   • output: written summary of the error, line numbers, the actual assertion or exception that fired

2. reproduce it reliably. trigger the failure with the smallest input you can. use the minimal test case, minimal data, minimal config. if you cannot reproduce it, gather more evidence (logs, stats, timing conditions, concurrency patterns). do not guess.

   • input: steps to trigger (test command, curl request, user action sequence)
   • output: a local or isolated reproduction that fires the same error consistently, or list of evidence collected if not yet reproducible (timing window, error rate, specific conditions)

3. check what changed recently. run git log --oneline -20 and git diff on the affected files. focus on commits that touched the broken code path. check for new dependencies, version bumps, config or environment drift. most bugs are young.

   • input: the file that crashes or the test that fails
   • output: list of recent commits and diffs that could have introduced the bug, ordered by likelihood (recent + in the code path)

4. check the documented contract. read schema docs, interface comments, function signatures, the spec. the difference between documented behavior and actual behavior usually points to the cause. note: the fix must satisfy the contract, not just the failing test.

   • input: docs, comments, schema, spec for the affected component
   • output: explicit statement of what the contract says the code should do vs. what it is doing

5. trace to the source. where does the bad value originate? who called this with it? walk up the stack until you find the source. the fix lands there, not at the crash site. in multi-component systems, instrument each boundary (what enters, what exits) and run once to see which layer breaks, rather than theorizing.

   • input: stack trace, code flow, logs
   • output: the origin point where the bad value entered, the function or layer that should have prevented or handled it

6. compare against what works. find the nearest working sibling: same pattern, same codebase, different input or config. list every difference, including the ones that "can't matter".

   • input: a passing test or passing code path that is similar to the failing one
   • output: explicit list of differences between working and broken versions

phase 2: fix (once, and with a test)

7. state the hypothesis in writing. "X is the root cause because Y." specific. if you cannot finish that sentence, go back to phase 1. do not pretend.

   • input: evidence from steps 1-6
   • output: written hypothesis, e.g. "the query is not filtering by tenant_id because the middleware is not setting it on the request context before the handler runs"

8. pin it with a failing test first. write a test that reproduces the bug and asserts the violated contract, not just the absence of a crash. this test must fail before your fix and pass after. this is the guard that catches the next regression.

   • input: the hypothesis and the reproduction steps
   • output: a new test file or test case that fails on the current code and documents what the contract requires

9. apply one minimal change. test the hypothesis with the smallest change that fixes the cause. one variable, one line, one condition. no bundled cleanups, no "while I'm here" refactors.

   • input: the hypothesis and the pinned test
   • output: the code change (git diff), one minimal edit

10. verify and read the output. the pinned test passes. the whole suite stays green. the original symptom is gone. actually run it, actually read the logs or output.

    • input: code change from step 9, full test suite
    • output: passing test run, confirmation that symptom is resolved, no new test failures introduced

if the fix did not work: stop. do not stack a second fix on top. new evidence, new hypothesis, back to phase 1. after three failed fixes, stop fixing entirely. three misses on one bug means the architecture or pattern is wrong, and that conversation happens before attempt four.

decision points

if you cannot reproduce it: gather more evidence. check production logs, monitoring dashboards, network traces, timing conditions. confirm the failure rate, the specific input, the environment state. only proceed to fix if you can trigger it locally or you have detailed logs that name the cause.

if the error is intermittent or flaky: do not guess. add logging or instrumentation to narrow the timing window, the concurrency pattern, or the race condition. reproduce it multiple times before forming a hypothesis. check if it is environment-specific (one region, one database state, one cache state).

if you have a candidate fix but the test still fails: your hypothesis was wrong or incomplete. do not apply a second fix on top. revert, gather new evidence, return to phase 1.

if you have applied three fixes and the test still fails: stop. the problem is not a simple bug. it may be an architecture issue, a design pattern that is broken, or a misunderstanding of the contract. escalate to the user or team owner before attempting a fourth fix.

if the crash site is not the source: you found where it breaks, not where it started. continue tracing upstream (who called this function with that value). the fix goes at the source, not at the symptom.

if the fix makes the test pass but you cannot explain the bug: you got lucky. this is the most dangerous state. revert, return to phase 1, build understanding before shipping. luck is not process and it just hasn't cost you yet.

if production-only or staging-only: cannot ship a fix without reproducing it in your test environment or on a staging replica. if you cannot reproduce it, you cannot confidently fix it. add the missing test environment condition or log output, get reproducibility first.

output contract

success is a state, not a document. but you can verify it by:

• failing test committed: a new test file or test case in the suite that documents the contract and fails on the old code, passes on the new code.
• single code change: git diff shows one minimal edit. no bundled refactors. no stacked fixes.
• all tests pass: the original failing test passes. the full suite passes. no new failures introduced.
• symptom is gone: the original error, crash, assertion failure, or unexpected behavior does not occur on the input that triggered it.
• hypothesis written: in commit message, PR description, or comment: the root cause stated as "X is the root cause because Y."

store the output in the same repo and branch where the bug occurred. the test lives in the suite. the fix lives in the code.

outcome signal

you know it worked when:

• you can explain the bug in one sentence ("the query was missing the tenant_id filter because the middleware didn't set it on the context before the handler ran").
• the failing test that you wrote now passes.
• the full test suite is green.
• the symptom that was originally reported (crash, flaky test, wrong output) does not occur anymore on the input that triggered it.
• a teammate can read your failing test, understand what contract was violated, and see how your one-line fix restores it.
• you can point to a recent commit or a config change or a dependency bump and say "that is what started this."

opposite outcome: you ship a fix without understanding the bug, and the same symptom appears again in two weeks on a different input. or you apply three fixes and the test still fails and you run out of guesses. or you explain the fix but cannot explain the bug. those are all stops. revert, gather new evidence, go again.