Blocking IO Guard

Blocking-IO Guard Skill

Help a contributor ship backend async changes together with the runtime anchor that lets DeerFlow's blocking-IO CI gate actually see the new code. The dynamic detector only catches blocking IO on paths a test executes — this skill closes that gap, either for your own diff or for a repo-wide triage round.

Read references/good-anchor-rules.md before writing any anchor. Only read references/sop-skeleton.md when generalizing this SOP to another detector domain — it is not needed to execute the steps below.

When to use

• Your change touches Python under backend/app/, backend/packages/harness/deerflow/, or backend/scripts/ and may run on the async event loop (Mode A). If unsure, run Step 0 — it answers deterministically.
• You are doing a maintenance triage round over the existing codebase (Mode B).

SOP (router)

Step 0 — Scope (deterministic)

Mode A — your own diff (default, pre-PR). From repo root:

uv run --project backend python scripts/scan_changed_blocking_io.py --base origin/main

Lists blocking-IO candidates your change introduces: findings on lines the diff added, plus findings that are new versus the merge base — the latter catches a new async caller exposing an old sync helper whose blocking line is not in the diff. The diff is <base>...HEAD, so commit your work first — uncommitted lines are not selected.

If the list is empty, this change introduces no blocking-IO surface that the static detector can see in the changed files. One residual blind spot remains: reachability is same-file only, so a new async caller of a sync helper defined in another file is invisible to both selections. If your diff adds an async call into a helper that lives elsewhere, check that helper manually (codegraph or git grep) before stopping.

Mode B — full-repo triage round. From repo root:

make detect-blocking-io

Prints a summary and writes the complete structured finding list to .deer-flow/blocking-io-findings.json. Work HIGH priority first; do not start MEDIUM until every HIGH is dispositioned (fixed, guarded, or recorded NO-ACTION).

Batching policy (PR sizing). One fix unit per PR while any HIGH remains: a fix unit is one root cause — usually a single HIGH, but two HIGHs resolved by the same one-place fix belong together. Once no HIGH remains, MEDIUM/LOW may be batched (about five per round, grouped by module or by disposition) so each PR stays reviewable. A new Blockbuster rule is never batched with anything — it always ships alone (see Step 5).

Both modes emit the same JSON shape per finding: priority, location (path/line/function), blocking_call (category/operation/symbol), event_loop_exposure, reason, code. Priority is a deterministic review ordering, not proof of a bug — Step 1 makes the actual call.

Step 1 — Judge each candidate (router)

Read the code around each candidate and route it:

• Already offloaded (asyncio.to_thread, run_in_executor, async client) → GUARD: add/extend an anchor that locks the offload so a future edit cannot move it back onto the loop.
• On the loop, not offloaded → FIX+ANCHOR: offload the production code (your fix), then add an anchor that guards it.
• Not actually exposed / acceptable (rare: scanner false positive, startup-only code) → NO-ACTION: record one line of why.
• Cross-file caveat: the scanner's async reachability is same-file only (ASYNC_REACHABLE_SAME_FILE). If the candidate is a sync helper, check for async callers in other files (codegraph or git grep) before deciding NO-ACTION.