Problem
When I need to understand how a complex feature actually works, none of the current paths get me to a factful report I can trust:
/ba-research fans out and synthesizes, but has no rule that a claim needs corroboration — it anchors on the first evidence that looks like an answer.- Ad-hoc research and same-session follow-ups drift: Claude builds a coherent-but-incomplete theory, launders assumptions into prose as if they were observed facts, and never runs a falsification step. I'm left constantly doubting it, with a false sense of understanding.
- Blind spots are silent — an unexplored error path just doesn't appear on the page, so I can't even know to ask about it.
- Within a single session, follow-up turns re-theorize from scratch instead of tightening one shared, improving picture.
Goal
A verification-first investigation capability for mechanistic understanding of complex features — the slow, adversarial-depth counterpart to ba-research's fast breadth. Output must represent how the system works with explicit confidence, named assumptions, and named blind spots — not confident prose.
Mechanisms to fold in (with provenance)
Borrowed from Claude Code's deep-research skills (adversarial multi-source verification + confidence grading) and mattpocock's diagnosing-bugs discipline, adapted from web sources → codebase evidence types:
-
Claim/evidence ledger — decompose the report into atomic claims; each row carries support-status + confidence + citations. Prose is generated from the ledger last, inheriting the tags. (deep-research claims.jsonl.)
-
Triangulation across independent evidence types — a claim from one weak source is a hypothesis; corroboration by ≥2 independent types promotes it to supported. Codebase adaptation of "cluster-independent sources":
| Evidence type |
Proves |
Strength |
| Runtime observation (run / test / instrument / logs) |
what actually happens |
strongest |
| Tests pinning the behavior |
what's asserted |
strong |
| Callers / usages |
how it's really invoked |
medium |
| Git history / PR / commit msg |
why / when it changed |
medium (intent) |
| Config / schema / types |
bounds & wiring |
medium |
| Implementation code |
what it appears to do |
weak alone |
| Docs / comments |
claims, often stale |
weakest |
-
Adversarial CRITIQUE → REFINE pass — after synthesis, deliberately attack the highest-stakes and every single-source/assumption claim; delta-retrieve to close them, ideally by upgrading the evidence (add a test, run it, instrument). Loop until load-bearing claims are ≥corroborated or explicitly flagged.
-
Evidence-before-theory discipline (mattpocock) — "if you catch yourself explaining behavior before the surface map exists, stop." Hypotheses must be falsifiable, ranked, and competing (2–4 per sub-question).
-
Coverage / blind-spot map — enumerate entry points, exits, branches, error/edge paths, state, side effects before theorizing; every item marked verified / assumed / unexplored, so blind spots are printed, not silent.
-
Confidence vocabulary — Verified (observed or test-pinned) · Corroborated (≥2 independent types) · Single-source · Assumption · Contradicted/Unknown.
Open design questions (for the brainstorm)
- Packaging: new skill (
ba-investigate) vs. a "deep/verified" mode on ba-research. Leaning new skill — different discipline (adversarial depth vs. fast fan-out), different output contract, and a mode flag would force one prompt to hold two contradictory disciplines.
- Contract vs. steering split (per
.claude/agent_docs/prompt-authoring.md): the ledger schema is a machine-boundary contract — specify claim-row shape, confidence vocabulary, and evidence-type taxonomy to the character. The anti-anchoring / falsification discipline is steering — state the goal + the "stop if you catch yourself…" trigger and stop.
- Agent-composition / harness pattern: which fits adversarial verification — subagents (current
ba-research fan-out) / agent teams (independent sessions that cross-challenge) / dynamic workflows (Claude authors a JS harness with per-step model choice)? The first-party /deep-research runs on dynamic workflows. Confirm what's actually reachable from a plugin skill in this runtime before assuming. Ref: https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code
- Same-session convergence: the ledger is the durable working state within a session (in-context / scratch file / TodoWrite); follow-up turns target the weakest rows so understanding converges monotonically. Decide the concrete mechanism.
- Relationship to
ba-research (cheap first pass → hand off to investigate when a theory is load-bearing?) and to docs/research/ artifacts.
Design input — fog/map borrow from wayfinder (added 2026-08-02)
Borrow the structure of mattpocock's wayfinder (a wayfinder:map index + child tickets + a fog-of-war rule), not its issue-tracker machinery (too heavy for one-sitting comprehension). The valuable primitives:
| Wayfinder concept |
Use in this skill |
| Map buckets (Decisions so far / Not-yet-specified / Out of scope) |
The coverage map: Verified/Corroborated (one-line gists + confidence) · Fog (in-scope, unresolved — named, not silently theorized) · Out of scope. Blind spots become printed rows. |
| Fog graduation test ("can you state the question sharply?") |
Forbids answering an unsharp question with a plausible story. Not sharp → stays Fog (honest "unresolved"), not false understanding. |
| Frontier (next unblocked, unclaimed items) |
Same-session convergence: follow-up turns work the sharpest unresolved fog instead of re-theorizing. |
| Map loaded once, low-res; detail in tickets |
The ledger is a compact index; evidence lives in the detail rows. |
Caveat — two item types, one substrate. Wayfinder charts decisions to make (forward — "what should we build?"); this skill's core is facts to verify (backward — "how does it work?"). Keep the fog/map/frontier substrate shared, but fork the resolution engine by item type: a fact resolves by triangulation + confidence grade (discovered truth); a decision resolves by research/prototype/judgment (chosen, with rationale — no "confidence it's true"). Blurring the two (grading a design choice, or "just pick one" on a factual question) is the confusion to avoid; typing each item fact-vs-decision is what prevents it.
Both-modes question (I work "learn X to build Y" — the two interleave). Facts naturally block decisions (a verified fact is a precondition for a build choice — wayfinder's native blocking), so a unified map expresses "learn to build" directly. But this repo already has the forward skills (ba-brainstorm, ba-plan), so the open architecture call is where the shared fog/map substrate lives — under this investigate skill and the forward skills, composed by handoff (verified map → plan input) — not one mega-skill absorbing planning. Lean: shared substrate + typed items + engine-forks + compose-don't-absorb. Same substrate also settles the too-big-for-one-session case for both modes: persist the map, resume on the frontier.
Evidence / sources
Next step
/ba-brainstorm this (design-it-twice on packaging + ledger schema + the shared-substrate architecture) → /ba-plan. Add to #29's Needs brainstorm table once the cluster lane is confirmed.
Problem
When I need to understand how a complex feature actually works, none of the current paths get me to a factful report I can trust:
/ba-researchfans out and synthesizes, but has no rule that a claim needs corroboration — it anchors on the first evidence that looks like an answer.Goal
A verification-first investigation capability for mechanistic understanding of complex features — the slow, adversarial-depth counterpart to
ba-research's fast breadth. Output must represent how the system works with explicit confidence, named assumptions, and named blind spots — not confident prose.Mechanisms to fold in (with provenance)
Borrowed from Claude Code's deep-research skills (adversarial multi-source verification + confidence grading) and mattpocock's diagnosing-bugs discipline, adapted from web sources → codebase evidence types:
Claim/evidence ledger — decompose the report into atomic claims; each row carries support-status + confidence + citations. Prose is generated from the ledger last, inheriting the tags. (deep-research
claims.jsonl.)Triangulation across independent evidence types — a claim from one weak source is a hypothesis; corroboration by ≥2 independent types promotes it to supported. Codebase adaptation of "cluster-independent sources":
Adversarial CRITIQUE → REFINE pass — after synthesis, deliberately attack the highest-stakes and every single-source/assumption claim; delta-retrieve to close them, ideally by upgrading the evidence (add a test, run it, instrument). Loop until load-bearing claims are ≥corroborated or explicitly flagged.
Evidence-before-theory discipline (mattpocock) — "if you catch yourself explaining behavior before the surface map exists, stop." Hypotheses must be falsifiable, ranked, and competing (2–4 per sub-question).
Coverage / blind-spot map — enumerate entry points, exits, branches, error/edge paths, state, side effects before theorizing; every item marked verified / assumed / unexplored, so blind spots are printed, not silent.
Confidence vocabulary — Verified (observed or test-pinned) · Corroborated (≥2 independent types) · Single-source · Assumption · Contradicted/Unknown.
Open design questions (for the brainstorm)
ba-investigate) vs. a "deep/verified" mode onba-research. Leaning new skill — different discipline (adversarial depth vs. fast fan-out), different output contract, and a mode flag would force one prompt to hold two contradictory disciplines..claude/agent_docs/prompt-authoring.md): the ledger schema is a machine-boundary contract — specify claim-row shape, confidence vocabulary, and evidence-type taxonomy to the character. The anti-anchoring / falsification discipline is steering — state the goal + the "stop if you catch yourself…" trigger and stop.ba-researchfan-out) / agent teams (independent sessions that cross-challenge) / dynamic workflows (Claude authors a JS harness with per-step model choice)? The first-party/deep-researchruns on dynamic workflows. Confirm what's actually reachable from a plugin skill in this runtime before assuming. Ref: https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-codeba-research(cheap first pass → hand off to investigate when a theory is load-bearing?) and todocs/research/artifacts.Design input — fog/map borrow from wayfinder (added 2026-08-02)
Borrow the structure of mattpocock's wayfinder (a
wayfinder:mapindex + child tickets + a fog-of-war rule), not its issue-tracker machinery (too heavy for one-sitting comprehension). The valuable primitives:Caveat — two item types, one substrate. Wayfinder charts decisions to make (forward — "what should we build?"); this skill's core is facts to verify (backward — "how does it work?"). Keep the fog/map/frontier substrate shared, but fork the resolution engine by item type: a fact resolves by triangulation + confidence grade (discovered truth); a decision resolves by research/prototype/judgment (chosen, with rationale — no "confidence it's true"). Blurring the two (grading a design choice, or "just pick one" on a factual question) is the confusion to avoid; typing each item fact-vs-decision is what prevents it.
Both-modes question (I work "learn X to build Y" — the two interleave). Facts naturally block decisions (a verified fact is a precondition for a build choice — wayfinder's native blocking), so a unified map expresses "learn to build" directly. But this repo already has the forward skills (
ba-brainstorm,ba-plan), so the open architecture call is where the shared fog/map substrate lives — under this investigate skill and the forward skills, composed by handoff (verified map → plan input) — not one mega-skill absorbing planning. Lean: shared substrate + typed items + engine-forks + compose-don't-absorb. Same substrate also settles the too-big-for-one-session case for both modes: persist the map, resume on the frontier.Evidence / sources
199-biotechnologies/claude-deep-research-skill— evidence-loop-per-section, triangulation (≥3 cluster-independent), claims/evidence/sources JSONL ledgers: https://github.com/199-biotechnologies/claude-deep-research-skilldiagnosing-bugs— evidence-before-hypothesis, falsifiable ranked hypotheses: https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnosing-bugs/SKILL.mdwayfinder— fog-of-war + map/frontier decomposition for multi-session work: https://github.com/mattpocock/skills/blob/main/skills/engineering/wayfinder/SKILL.md/deep-researchruns on it): https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code/deep-researchships inside the Claude Code CLI package (not a public repo) — internals not extractable; the mechanisms above are sourced from the public equivalents.Next step
/ba-brainstormthis (design-it-twice on packaging + ledger schema + the shared-substrate architecture) →/ba-plan. Add to #29's Needs brainstorm table once the cluster lane is confirmed.