Treat Blockers As Incidents

Treat Blockers as Incidents

Core principle. The stone in your shoe is not the walk. It is an incident with a cause, a cost, and a record.

• The failure is about your task, or it is not. That single question routes everything below.
• The weight sits in Bound it before you start and What you may claim. Everything else spends what those two allow.
• You opened this in the middle of something. This is how to get back to that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

Is this yours

Answer before touching anything.

• A test failing because the behaviour is missing is your task. That is test-first-by-evidence.
• A defect in the code you are changing is your task. That is debugging-by-evidence.
• A tool, runtime, credential, network path, or environment that will not do its job is not your task. It is this.
• Where you cannot tell, use records and a narrow check to distinguish the layers. A failed tool call can be real even if a later invocation passes.

Bound it before you start

Say the budget out loud, in the report, before the first probe.

• Name the ceiling. A number of probes, or a wall-clock span. Without one, "understand it up to a point" has no point.
• Say what reaching the ceiling means. Hand back what you have, incomplete, rather than continue.
• Investigate in a session that is not this one where the harness allows it. Context spent here is context the original task no longer has.
• Record as you go, not at the end. An investigation that runs out of room produces nothing, and it was the one with the most to teach.

Say which state you are in

You MUST report it every time. Each state licenses only what it names.

• No state is reached by assumption. Each names an observation you made.
• blocker/CLEARED requires the original command to run, not a substitute you found instead.
• A successful retry alone does not prove an intermittent defect is repaired. If the original operation cannot be exercised, report that remaining blocker even when a narrower handling repair is demonstrated.
• Use independent layers where helpful. Source analysis or an isolated handling test need not wait for capture of a transient. Runnable Signal owns experiment selection; this skill retains the scope and authority limits.

Which rules to read

This table is a gate, not a checklist. Match the left column against what failed.

• Read every row whose signal is present. Report an absent one as not-applicable, naming the signal.
• A blocker that hides a second blocker matches two rows. Read both.
• Read every row, then act on the matches, hardest to undo first. Reading a row costs nothing; the row you skipped is where the coverage went.

Default stance.

• Use the available failure evidence to choose the next bounded step. Do not require the whole incident to recur before investigating a supported hypothesis.
• Choose the source, experiment or trace that answers the missing question. Avoid repeated attempts or environment escalation when a narrower contract test suffices; retain tracing when the real trigger is what must be identified.
• Hand back anything whose fix is not obviously clean. The decision is the developer's, and an unclean fix bought quietly is worse than a blocker reported loudly.

What you may claim

Four words, and each one names how you know.

• Confirmed. Supported by a directly inspected observation, with the relevant incident record or experiment conditions and output cited. State the claim it supports; a controlled result confirms handling under the injected condition, not that the condition occurred in the historical incident.

• Inference. Reasoned from something Confirmed, and labelled so.

• Gap. Not established. State the next concrete observation that would close it.

• Recommendation. Never proof.

• A workaround is a Recommendation until the mechanism is Confirmed. Reporting it as a fix is the failure this skill exists to prevent.

• Never claim a command succeeded unless its output was observed.

Where the record goes

• Use the location the request named, if it named one.
• Otherwise the one the instruction file declares.
• Otherwise a learnings directory that already exists, in this repository or in the user's agent directory. Writing beside an existing one beats starting a second.
• Otherwise decide from the finding. A blocker anyone cloning this repository would hit is written inside it; one only this machine has is written to a learnings directory beside the user's own instruction file, outside any repository.
• Where you cannot tell, write outside the repository. A note in the wrong home directory is invisible to everyone; a note committed uninvited is not.
• Report the path you chose and whether it is tracked. A wrong guess then costs one line to correct.

Do not skip this when

• The workaround already worked. It worked once, on your machine, for reasons nobody wrote down.
• The blocker looks trivial. The ones that eat an afternoon all looked trivial at the first attempt.
• You are nearly done. Nearly done is where the second blocker lives.

Routing

• The table above selects the rule. Read a selected rule in full, and say which one you opened.
• A defect in the code under change belongs to debugging-by-evidence.
• Judging a change that already exists belongs to evidence-backed-review.
• A direct instruction from the user outranks anything here.