sc-hypothesize — Hypothesis Generation (Pipeline Stage 4)

This is where the audit's breadth lives. Stages 1–3 build structure; this stage turns structure into concrete, falsifiable vulnerability hypotheses across the whole catalog of bug classes — and adds two things a pure checklist can't: attacker-mindset free exploration (for novel logic bugs) and spec-differential math hypotheses. Everything merges into one schema so stage 5 verifies it all the same way.

Design contract: every hypothesis must (a) link to an invariant INV-N, (b) name a concrete attacker, and (c) make ONE falsifiable claim. If it can't be disproven by a PoC, it is not a hypothesis — it's a worry, and worries don't ship.

When to Use

• After sc-graph (and sc-spec); orchestrator calls this fourth.
• User says: "find the vulnerabilities", "generate hypotheses", "what could be exploited".

Announce

Begin with: "I'm using the sc-hypothesize skill to generate vulnerability hypotheses from all three sources..."

Workflow

1. Route + auto-seed (deterministic backbone)

python skills/sc-hypothesize/scripts/route_hypotheses.py <audit_dir>   # default .audit

Produces in .audit/hypotheses/:

• routing-plan.json — per-function vulnerability classes to run, with rationale, plus the global class set from protocol_type and integrations.
• coverage-matrix.json — (chunk×class) plan + counts; your completeness ledger.
• H-*.json seeds — the mechanical hypotheses that follow deterministically from prior signals. You never have to re-derive these; build ON them.

Read coverage-matrix.json first. It tells you exactly which classes apply and where, so the semantic passes below are targeted, not scattershot.

Scaling: inline vs fan-out (choose by size)

• Small protocols (≲ 40 routed functions): inline. Do the checklist + free- exploration passes yourself, as described below. Cheapest, no subagents.
• Large protocols: fan-out to parallel workers (keeps each context small so it scales like understand):

  python skills/sc-hypothesize/scripts/batch_chunks.py <audit_dir> --size 15

  Then for each hypotheses/batches/batch-NNN.json, spawn an sc-hypothesis-worker subagent (Agent tool, in parallel) with that batch file path. Each worker applies the routed checklists to its batch and writes hypotheses to its output_dir. Report progress per batch (Analyzing batch X/N). When all workers finish, merge:

  python skills/sc-hypothesize/scripts/merge_hypotheses.py <audit_dir>

  The merge dedups worker output against the deterministic seeds by dedup_key (cross-source agreement recorded as also_found_by) and reconciles counts. Run the free-exploration pass (below) as additional parallel subagents — optionally several with different attacker personas (economic, griefer, MEV, governance). Then triage the merged set as in step 5.

The two paths produce the same canonical hypotheses/ set and pass the same triage

• verification gate — fan-out changes only HOW the reasoning is distributed, never the schema or the gate.

2. Checklist-driven pass (recall on known classes)

(inline path; for fan-out this is what each worker does on its batch) For each class in routing-plan.class_to_chunks, read the class's vendored, self-contained pattern file at routing-plan.checklist_files[<class>] (skills/sc-hypothesize/checklists/<class>.md — copied into the repo so there is no dependency on the external audit-* skills) and apply its patterns to the routed chunks. (If a class has no vendored file, fall back to the external audit-<class> skill named in checklist_skills. Refresh the vendored copies with python skills/sc-hypothesize/scripts/vendor_checklists.py.)

• For each pattern, check the routed chunks and emit a hypothesis for any that the seeds did not already cover. Example: the router auto-seeds only the "oracle staleness" pattern; audit-oracle has ~11 patterns (sequencer uptime, min/max bounds, decimals, slot0 manipulation, depeg, …) — generate those here.
• Work highest-risk first: reachable, unprivileged, value-moving chunks (routing.per_function[*].reachable, tags from the chunk bank).
• Set source: checklist, checklist: audit-<class>, created_by: llm.

Do not re-flag what a seed already covers — merge into the seed (same dedup_key) or skip.

Apply integration notes (domain checklists). routing-plan.json → integration_notes lists which external integrations the target uses (GMX, Chainlink, Uniswap-v3, Paraswap, …) and the functions touching each. For every applicable one, read skills/sc-hypothesize/integration-notes/<name>.md and apply its items to those functions (checklist: integration-<name>). These encode the protocol-specific gotchas generic class checklists miss — e.g. GMX multi-handler whitelisting, ADL output handling, synthetic index tokens; the Chainlink sequencer feed; Paraswap calldata parsing. This is the fix for the Gamma domain misses.

3. Free-exploration pass (the novel-bug source) ⭐

Run a SEPARATE attacker-mindset analysis that is not given any checklist. Strongly prefer doing this as a subagent (Agent tool) so it reasons with fresh eyes; pass it:

• project-map.md (invariants, trust model, money flow, by_design powers),
• graph/value-flow.json and graph/storage-graph.json (shared-state clusters),
• the source of the critical/high entry points,
• and the instruction: "You are an attacker with a flash loan, the ability to deploy malicious contracts and tokens, and control of callbacks. For each critical/high INV-N, find a concrete sequence that breaks it. Think about THIS protocol's specific logic, composition with the named integrations, economic incentives, ordering/MEV, and edge cases (zero, max, first-depositor, dust, self-reference). Ignore generic checklists — find what a catalog would miss."
• Emit each result as a hypothesis (source: free-exploration, vuln_class may be a free-form label like economic or first-depositor), linked to the INV-N it breaks, with an exploit_sketch.

This pass is what stops the tool from being "just a checklist runner". Spend real effort here.

4. Math-divergence pass

The router already seeds one hypothesis per sc-spec formula with a divergence_risk. Review each: confirm the implemented_by mapping is right, add formula-specific edge cases (zero-supply bootstrap, first-deposit inflation, overflow boundaries), and ensure verification.poc_type: differential with the reference_model path in evidence.

5. Merge, dedup, and triage (keep false positives low even here)

• Dedup by dedup_key; if two sources found the same bug, keep one and note both sources.
• Triage each hypothesis and set triage.decision:
  • reject if it targets unreachable code (reachable: false) with no override path, isn't falsifiable, or contradicts a by_design admin power in the map (with reason).
  • by-design if the behavior is an intended, documented power (note it; not a finding unless unbounded/unintended).
  • needs-info if a precondition can't be determined from code (flag for human).
  • keep otherwise — these go to stage 5 as status: proposed.
• A rejected hypothesis is kept on disk with its reason (auditable trail), not deleted.

5.5 Consolidate + rank (deterministic — so nothing falls out) ⭐

After triage, collapse the (possibly hundreds of) hypotheses into a ranked verification worklist. This is the fix for the failure mode where real bugs sit in a large pile and an ad-hoc manual triage promotes only a few:

python skills/sc-hypothesize/scripts/consolidate.py <audit_dir>

It clusters hypotheses by function into distinct candidates and scores each by severity × invariant-criticality × cross-worker-agreement × reachability × trust-penalty × source-quality × guard-penalty (mechanical reentrancy seeds on access-guarded callbacks are down-weighted; keeper/owner-only ("trusted-actor") claims are flagged needs-info). Output hypotheses/consolidated.json carries a verify_worklist (ranked candidate functions, verify first). Stage 5 works this list top-down, so every high-scoring candidate is examined before effort runs out — the elevation is deterministic, not dependent on what you happened to read. (The orchestrator runs this automatically at the start of the verify phase.)

6. Quality gate (see checklist.md) and handoff

Confirm every routed (chunk×class) pair was examined, every critical/high INV-N has at least one hypothesis attempting to break it (or a documented reason none applies), and every kept hypothesis is falsifiable with a concrete attacker. Hand the keep set to sc-verify.

Why this is strong AND low-false-positive

• Coverage is guaranteed by the router, not by the LLM remembering — the mechanical bugs are seeded, the checklist pass is driven by an explicit plan, and the coverage matrix is auditable.
• Breadth + novelty: 11 checklist classes for the known, free-exploration for the unknown, differential math for the protocol-specific.
• Falsifiability is enforced at creation — no vague hypotheses survive to stage 5, so the verifier spends its effort on real candidates.
• Triage already removes the cheap false positives (unreachable, by-design) before the expensive PoC stage.

Reused assets

The installed audit-* skills are the checklist knowledge base (do not duplicate their patterns here — consult them). sc-spec reference models drive the differential hypotheses. The call graph's reachability gates exploitability.

Handoff

Tell the orchestrator: hypotheses by class and by source, how many kept vs rejected (with reasons), and which critical/high invariants now have attack hypotheses. Next stage: sc-verify.