| name | work-sweep |
| description | Parallel blind search from multiple independent angles (by structure/files, by content/semantics, by git history/time, by entity/domain, by error paths, alternative-storage-paths, config/realm dimensions, etc.), then a BARRIER at the merge step that dedups against a persistent SEEN set and lists what no angle covered. Each searcher is kept ignorant of what the others found in the same round. Use when one search strategy is known to be incomplete: "find all X", security review, "where can this break?", data flow tracing. Invoke via /work-sweep.
|
| metadata | {"short-description":"Blind parallel searches from diverse angles → barrier merge against a SEEN set"} |
/work-sweep — Multi-Angle Blind Discovery
Implements the Multi-modal sweep pattern.
Orchestration shape: PARALLEL with a BARRIER at the merge
This skill is PARALLEL fan-out → BARRIER at the dedup/merge step. See the three
shapes in ../work/references/workflow-mode.md §1.
- The fan-out is parallel: N blind searchers run at once, one per angle, fully
independent. No barrier between searchers.
- The merge is a genuine barrier: you must wait for ALL searchers because the
dedup and the completeness pass are cross-item operations — "same issue found via
two paths counts once" and "what did NO angle cover?" can only be computed once every
angle has reported. This is exactly the cross-item dependency that justifies a barrier
(workflow-mode §1: dedup/merge across the full result set). It is not a barrier of
convenience: the cross-angle comparison genuinely needs the whole set.
- The barrier is plain set logic, not an agent call. Dedup + completeness run in the
orchestrator's own context against the
seen set; never spawn a sub-agent to "merge".
A failed angle does not hold the barrier open: filter it out, recompute coverage
over the surviving angles, and log the drop (see Execution Mechanics → Null-handling).
When this sweep is one round of work-exhaust, the barrier's output (the new findings
plus the updated seen set) feeds the next round; the loop shape lives in
../work-exhaust/SKILL.md, and this skill supplies its
per-round fan-out + barrier.
When to use
- A single search strategy (grep one term, read a few files, ask one agent "find issues") will miss important cases.
- Different modalities of the system (code structure, runtime behavior, historical changes, data entities, user journeys, error states) reveal different things.
- You want coverage without the searchers contaminating each other (they stay blind within the round).
Often combined with work-exhaust for repeated rounds.
Usage
/work-sweep "what to discover" [angles=...]
Examples:
/work-sweep "places that can affect job SLA or status visibility"/work-sweep "security and data exposure risks in the signup flow" angles="authz,storage,logging,public-endpoints,third-party-calls"
The orchestrator uses this heavily in Research and early Review phases.
How it works
-
Define modalities / angles
- Default set if not provided:
- Structural (file layout, modules, entry points)
- Content / semantic (keywords, patterns, business rules)
- Historical (git blame, recent changes, refactors)
- Entity / data flow (specific domain objects like Order, Stage, Draft)
- Error / failure paths
- User / external interface paths
- Or accept explicit angles from the caller.
-
Launch blind parallel searchers
- Spawn a sub-agent per angle.
- Each receives only the high-level goal + its own angle instruction.
- Explicitly told: "You will not see results from other angles in this round. Search only through your lens."
- They use all available tools (grep, read, terminal, etc.) but stay within their modality.
-
BARRIER — collect & dedup against a persistent SEEN set (L4)
- Wait for every searcher (or its filtered-out failure) before merging.
- Maintain a persistent
seen set keyed by a stable identity (normalized
locations[] + a slug of the claim), carried across rounds and never reset on
resume (it is the journal's source of truth).
- For each candidate finding: report it only if its key is not already in
seen.
A finding that matches a key already in seen — including one a prior round
rejected — is not re-reported; it is dropped as a dup.
- Return
seen ∪ new as the updated set, plus the list of genuinely-new findings.
Deduping against survivors instead of seen makes rejected items reappear every
round so a work-exhaust never converges — dedup against seen is what makes the
loop dry out.
- Tag each new finding with the angle(s) that discovered it (provenance is signal: a
finding surfaced by two independent angles is higher-confidence).
-
Verification gate — not a courtesy pass, a real gate (L1, L2, L8)
For every new finding before it leaves this skill:
- L1 — direct oracle first. If a deterministic oracle exists (a test, a
type-check, an exact
grep + manual confirmation, git, running the app), run it
before believing the finding. A finding with an available-but-un-run oracle is
needs_review, never confirmed. Prefer the oracle over any agent's say-so.
- L2 — re-open every
locations[] entry from the current source. Never accept
the searcher's quoted evidence as given. A finding whose locations[] fails
re-read (line moved, code gone, quote not found) goes to needs_review — it is
never silently kept (it may be real but stale) and never silently dropped (it
may be a real bug the searcher mis-cited). Record what you re-read in reReadSources.
- L8 — a dismissal counts only if it did the work. Demoting a finding to
dropped
because "it's fine / already handled" is valid only if that judgement re-read the
code and gave file:line evidence (workDone: true, reReadSources non-empty). A
lazy dismissal is an abstention: the finding stays needs_review and survives to
the next round. A single well-evidenced refutation outweighs two empty "looks fine".
- Pass surviving security/auth/multi-tenancy/data-integrity findings to
../work-refute/SKILL.md for
perspective-diverse refutation (L3 lives there, not here).
-
Completeness — what did NO angle cover? (L5)
After merging, do not stop at "here is what we found". The highest-value move is
naming what was never swept:
- List
completenessGaps[]: modules/files outside every angle's fan-out;
modalities no angle touched (e.g. no angle looked at the storage path, the
config/realm dimension, a downstream consumer, an async/job path, a public endpoint).
- Run at least one global oracle to surface items outside the angle list — a
repo-wide
grep for the core entity, or a scope-coverage diff (files touched by an
angle vs. files that mention the target). This is the cheap catch for the orphan
code-path that lives between everyone's lenses.
- Hand
completenessGaps[] to ../work-gaps/SKILL.md
and/or seed them as new angles for the next work-exhaust round.
-
Output
- Structured
SweepResult (see contract below): new unique findings with provenance,
the updated seen set, completenessGaps[], and dropped[] (angles that failed +
findings deduped/dismissed, each with a reason — no silent caps, L7).
- Notes on modalities that were weak or expensive.
- Suggestions for the next round (different angles, or feed into
work-exhaust).
Structured I/O contract
Free-form severity strings defeat calibration (L6), so severity is an enum anchored to
a verified-impact rubric, and verification status is an enum the gate sets. See the
schema conventions in
../work/references/workflow-mode.md §4.
Each blind searcher returns (a fenced ```json block at the end of its reply):
{
"angle": "alternative-storage-path",
"findings": [
{
"title": "storage tenant derived from ?hostname, not session",
"description": "Orphan code path: the storage layer re-resolves the tenant from a request query param after auth, bypassing the session-bound tenant.",
"locations": ["src/storage/resolve.ts:88"],
"evidence": "resolve.ts:88 — `const tenant = req.query.hostname ?? session.tenant` (query wins)",
"severity": "high"
}
]
}
Field rules for a searcher finding:
locations — file:line array, required, non-empty (the gate re-opens each entry).evidence — a short quote the caller can re-find at that location.severity — enum critical | high | medium | low (searcher's first guess; the
gate may recalibrate). Rubric (L6, two-sided):
- critical / high — concretely reachable + damaging + currently uncovered, with a
reachability argument. Never assign
high to a speculative gap.
- medium — plausible but unverified, or no oracle was available.
- low — cosmetic, dev-time-only, or already-mitigated. Never assign
low to
something shown exploitable.
The skill merges + gates and returns one SweepResult:
{
"goal": "multi-tenant isolation risks in the upload flow",
"anglesUsed": ["forgery", "config-realm", "alternative-storage-path", "error-paths"],
"round": 1,
"findings": [
{
"id": "storage-hostname-override",
"title": "storage tenant derived from ?hostname, not session",
"description": "...",
"angles": ["alternative-storage-path"],
"locations": ["src/storage/resolve.ts:88"],
"evidence": "resolve.ts:88 — query param wins over session tenant",
"reReadSources": ["src/storage/resolve.ts:88"],
"severity": "high",
"status": "confirmed",
"workDone": true,
"oracle": "grep '\\?\\.hostname' src/ + manual re-read of resolve.ts"
}
],
"seen": ["storage-hostname-override", "auth-issuer-check", "..."],
"completenessGaps": [
"No angle traced the async thumbnail-worker path (jobs/thumbnail.ts) — same tenant resolution may be duplicated there.",
"config/realm dimension only checked for the primary realm; secondary realms untested."
],
"dropped": [
{ "kind": "angle", "ref": "git-history", "reason": "sub-agent returned empty after one retry; coverage recomputed over 4 surviving angles" },
{ "kind": "finding", "ref": "logging-pii", "reason": "duplicate of seen 'pii-in-access-log' from round 0" },
{ "kind": "finding", "ref": "csrf-upload", "reason": "dismissed — re-read route, CSRF token enforced at middleware.ts:40 (workDone:true)" }
]
}
Enums and required gate fields:
status — enum confirmed | needs_review | dropped.
confirmed — re-read passed and any available oracle was run (L1, L2).needs_review — re-read failed, OR an oracle existed but was not run, OR a dismissal
failed the L8 work-test. Never silently keep or silently drop — park it here.dropped — a dup (already in seen) or an evidenced dismissal (workDone:true,
reReadSources non-empty). Every drop also appears in dropped[] with a reason.
severity — same enum + rubric as above; the gate is the final say.oracle — string; the L1 command(s)+result run for a confirmed finding (required when
status==confirmed, else null/omitted).workDone: boolean + reReadSources: string[] — required on every gated finding so a
lazy verdict is detectable and demoted (L8).completenessGaps[] — required (L5); [] only after a global oracle actually ran.dropped[] — every angle filtered and every finding deduped/dismissed, with reason
(L7, no silent caps).
Execution Mechanics
Spawn each blind searcher as a sub-agent with the right sub-agent role (general-purpose),
in the background. Read-only sweeps need no isolated worktree; add one only for an
angle that mutates files. Await the barrier by waiting for all of them, then collect each
result. These are the same primitives
../work-tournament/SKILL.md uses — keep the vocabulary
consistent. The concrete per-harness tool names are tabulated once in
../work/references/workflow-mode.md.
- Independence / blindness: Core to the value. Each searcher gets only the goal + its
own angle, and is told explicitly: "You will not see other angles' results this round;
search only through your lens." Separate sub-agent contexts enforce it.
- Concurrency cap: Launch angles in controlled waves of ~min(6, cores−2); excess
queues. Six angles is the practical ceiling for one sweep — beyond that, split into
rounds and log the deferral (next bullet), do not silently launch fewer.
- Schema validation + single retry (workflow-mode §3): parse each searcher's
fenced ```json block and validate the shape. On malformed or empty output,
re-request the same angle once. A still-bad result is treated as a failed angle
(next bullet) — dropped and logged, never silently accepted as "no findings".
- Null-handling (recompute + log, never count a ghost): a dead / errored / still-bad
angle is filtered out —
angles.filter(Boolean) — and is not treated as
"this territory is clean". After filtering, recompute completeness coverage over the
surviving angles (its modality is now an explicit completenessGap, not silently
covered) and log the drop in dropped[] ({kind:"angle", ref, reason}). A failed
angle reading as "swept and empty" is the exact false-clean L7 guards against.
- Early-exit on zero: if the barrier yields zero new findings (all candidates were
already in
seen), skip the verification gate entirely and report the round as dry —
do not spin up verifier sub-agents on an empty set. (This is the per-round signal
work-exhaust counts toward its K-consecutive-empty termination.)
- No silent caps (L7): any angle deprioritized for concurrency/budget, any round
deferred, any finding capped — written as a named line in
dropped[] and
surfaced via your harness's todo/plan tool. A reader must be able to tell "clean" from
"truncated".
- Worktree isolation: usually not needed (read-only search); available per-angle.
- Journaling / resume: write machine-resumable events to
quality-journals/<task-id>.json (under your agent's data dir) — { phasesDone[], seen[], anglesUsed[], findings[], completenessGaps[], dropped[] }. On resume, load
seen[] and never reset it so rejected findings don't re-enter and exhausted angles
aren't re-run.
- Budget & Concurrency: orchestrator sets the ceilings; this skill respects and logs
them.
- log/phase via your harness's todo/plan tool: e.g. "Sweeping via 4 angles (git-history queued, wave
2)…", "Barrier: 7 candidates → 3 new after seen-dedup", "Gate: 2 confirmed, 1
needs_review (oracle un-run)", "completenessGaps: thumbnail-worker path untouched".
Worked example — the multi-tenant orphan storage path
Goal: "multi-tenant isolation risks in the upload flow." The orchestrator picks four
distinct angles (diversity is the point — same prompt ×4 is redundancy, not coverage):
| Angle | Lens | What it chases |
|---|
forgery | spoofing | can a caller forge/replay another tenant's identity? |
config-realm | config/realm confusion | shared CIAM/issuer, realm mix-ups, default-tenant fallbacks |
alternative-storage-path | code-path | a second way to reach storage that skips the main guard |
error-paths | failure modes | does an error/catch leak across tenants or default to tenant 0? |
Three angles read the auth middleware and conclude "the issuer check closes it" — a
plausible single-shot false negative (the exact L2 failure the case in
../work/references/anti-error-lessons.md
records). But alternative-storage-path re-reads the storage layer and finds
resolve.ts:88 deriving the tenant from ?hostname after auth — the orphan code path
the others' lenses never crossed.
At the barrier: the finding's key isn't in seen, so it's reported (L4). The gate
runs the oracle — grep '\?\.hostname' src/ + a manual re-read of resolve.ts
(L1) — confirming the query param wins over the session tenant; status:"confirmed",
severity:"high", workDone:true (L2, L8). The three "issuer check closes it" dismissals
did re-read code, so they're evidenced — but they only covered auth, so they do not
override the storage finding. Completeness (L5) then runs a global grep for the tenant
resolver and surfaces completenessGaps: ["thumbnail-worker re-resolves tenant in jobs/thumbnail.ts — untouched by every angle"], seeding the next work-exhaust round.
Net: a single smart agent (or any one angle) refuted a real high bug; the diverse sweep +
seen-dedup + oracle gate + completeness pass caught it and pointed at the next place to
look.
Integration with the rest of the toolkit
This pattern dramatically increases the chance of surfacing things that a single "smart
agent" or single grep would have missed, while keeping the searchers from group-think
within one round — and the barrier's seen-dedup + oracle gate + completeness pass turn raw
hits into auditable, convergent results.
