Skip to main content
Agent skill

Blocking Io Guard

Ensure async-path backend code that could block the asyncio event loop is protected by a teeth-verified runtime anchor in tests/blockingio/. Use when changing backend Python under app/, packages/harness/deerflow/, or scripts/, when running a blocking-IO triage round over the whole repo, or when a reviewer/CI asks for blocking-IO coverage. Runs a deterministic scan (changed-lines or full-repo), routes each candidate, drafts/extends an anchor, and proves it fails when the blocking IO regresses.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Blocking Io Guard when an AI agent needs a reusable SKILL.md workflow for this job: Ensure async-path backend code that could block the asyncio event loop is protected by a teeth-verified runtime anchor in tests/blockingio/. Use when changing backend Python under app/, packages/harness/deerflow/, or scripts/, when running a blocking-IO triage round over the whole repo, or when a reviewer/CI asks for blocking-IO coverage. Runs a deterministic scan (changed-lines or full-repo), routes each candidate, drafts/extends an anchor, and proves it fails when the blocking IO regresses.

When not to use it

Skip Blocking Io Guard when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/blocking-io-guard
# Save SKILL.md to ~/.claude/skills/blocking-io-guard/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/blocking-io-guard/SKILL.md. For a shared project, commit the folder at .claude/skills/blocking-io-guard/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Blocking Io Guard skill for this task: Your change touches Python under backend/app/,. Confirm any required inputs or files before making changes.

What supports this recommendation?

76/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
82/100
Practical detail
80/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# 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:

```bash 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:

```bash 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.

### Step 2 — Apply the fix, then re-scan (FIX+ANCHOR only)

Offload the blocking call in production code, then re-run the Step 0 scan and confirm the candidate no longer appears. If the offloaded call sits in a `finally` / cleanup path, keep it best-effort and bounded (swallow-and-log, `asyncio.wait_for`) so a failing or hung cleanup cannot mask the primary exception. Match by the stable key **(path, function, symbol)** — line numbers shift after edits, so never compare by line.

- The finding must disappear. If it still shows, the fix did not remove the blocking pattern (e.g. the call is still a direct call, not offloaded) — go back before touching any test. - GUARD / NO-ACTION routes skip this step: a residual finding there is *expected* (the raw call still exists inside a sync helper with the offload at the caller, or the exposure was judged acceptable).

This is pattern-level feedback in seconds; it complements but never replaces Step 5 — only the runtime gate proves the event loop is actually protected.

### Step 3 — Check existing anchors

Look in `backend/tests/blocking_io/` for a test that drives the production async entry point reaching this candidate's branch.

- Covers this branch already → go to Step 5 (re-verify teeth). - Covers the entry point but not this branch (e.g. happy path covered, cleanup/404/409 not) → **extend** that anchor. - None → create one from `templates/anchor.template.py`.

### Step 4 — Generate / extend the anchor

Follow `references/good-anchor-rules.md`. Drive the *specific* branch (e.g. force the create failure that hits the cleanup `shutil.rmtree`). Never bypass the blocking surface with a test-only `asyncio.to_thread` wrapper.

### Step 5 — Verify teeth (mandatory; also the anchor-vs-rule discriminator)

1. Reintroduce the block (GUARD: temporarily revert the offload; FIX+ANCHOR: run against the pre-fix code). 2. Run `cd backend && make test-blocking-io` (or target the one test). It **must go RED**. 3. Restore the fix. It **must go GREEN**.

A real block that stays GREEN means Blockbuster has no rule for that primitive — that is the **RULE** route; see `references/good-anchor-rules.md` for the admission criteria before adding one.

### Step 6 — Deliver

Commit the anchor(s) with your change; `make test-blocking-io` green. In the PR, note: candidates found, each disposition, the re-scan result (Step 2), and the teeth evidence (red→green). Include the reason for any NO-ACTION. A new Blockbuster rule, if any, goes in its own commit with the evidence from Step 5.

Intended uses

  • Your change touches Python under backend/app/,
  • You are doing a maintenance triage round over the existing codebase

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.