Source: bmad-rcon-foundation · bmad-rcon-foundation.md · updated 2026-07-25 · 🔒 secret gist

Synced verbatim from gist.github.com/bl9.

Part 0 — Foundations

Read this before bmad-deep-recon-guide.md. It assumes no background in agentic tooling. Every term is defined, traced to where its name came from, and shown in use.

Why the etymologies? Almost every word in this system is borrowed from somewhere else — the military, graph theory, newspaper typesetting, caching, law. That's not decoration. When you know that "topology" comes from network diagrams and "breadth-first" is a graph-traversal algorithm, you stop memorizing vocabulary and start predicting what the system will do, because you already understand the source concept. Naming is compressed explanation.

Contents

• 1. The five-minute model, before any vocabulary
• 2. Layer 1 — the AI substrate
• 3. Layer 2 — how BMAD is built
• 4. Layer 3 — Deep Recon's own vocabulary
• 5. Six mental models that carry the most weight
• 6. Where the metaphors break
• 7. Learning path: your first two weeks
• 8. Resources and references
• 9. What I'm confident about, and what I'm not

1. The five-minute model, before any vocabulary

Strip away every term and this is the whole system:

You have a decision to make. You don't trust the AI's memory, because it's stale and can't show its work. So you make it go look things up, in parallel, from sources it has to name — while preventing your own assumptions from leaking into what it finds. Everything it learns gets written to a file with dates attached, so that in six months you can tell whether it's still true.

Four moving parts:

1. A decision — stated up front, with constraints. Everything else is shaped by it.
2. A plan you approve — what will be investigated, how, and for how long.
3. Parallel lookup with a barrier — several sub-processes search, none of them sees your assumptions.
4. A dated, cited file — the durable output, with an expiry warning built in.

If you hold only that, the rest of the vocabulary is just precise names for these four things.

2. Layer 1 — the AI substrate

You need these before BMAD makes sense. Skip any you already know.

2.1 The basics

2.2 Agents and tools

Why subagents exist at all — this is worth understanding, because it explains the whole architecture. The context window is finite. If one model does twelve searches, it accumulates twelve pages of raw text and chokes. Instead: spawn six subagents, each with its own fresh window, each doing two searches and returning a half-page summary. The parent receives six half-pages instead of twelve full pages.

The cost: each subagent only knows what you told it. Coordination becomes the hard problem. Nearly every complexity in Deep Recon — briefs, digests, the single-writer rule — is machinery for managing that trade.

3. Layer 2 — how BMAD is built

3.1 The naming collision, flagged early

When BMAD docs say "the Analyst agent," they mean a persona file, not an autonomous process. Both senses appear in the same repo. Read from context.

3.2 Structural vocabulary

Why "append-only" matters — if you can rewrite history, the record can't be trusted, because you can't distinguish "this was always true" from "someone changed it." Append-only logs are the backbone of databases, version control, and blockchains for exactly this reason. Here it means: a claim's status can be added to (unverified → verified → overturned), and the earlier states remain visible.

4. Layer 3 — Deep Recon's own vocabulary

4.1 "Recon"

Military reconnaissance: scouting ahead of the main force to learn the terrain and the enemy's position before committing troops. From French reconnaître, "to recognize" — literally to know a place again, by having been there.

Why it's the right metaphor:

• It precedes commitment. You scout before you move, not during.
• It's cheap relative to what it protects. A patrol costs far less than a failed assault.
• It's information-gathering, not action. Recon doesn't take the hill. It tells you whether the hill is takeable.
• "Deep" recon is a real military term: patrolling far beyond the forward line, at higher risk, for strategic rather than tactical information.

Where the metaphor is useful to you: it correctly implies that research is preparatory and bounded. Research that never terminates in a decision has failed at being recon.

4.2 "Run" — the term you asked about

What it is: one complete, bounded execution of a research engagement. It has a beginning, an end, a configuration, an identifier, a folder on disk, and outputs. When you say "the run," you mean that whole bounded episode and everything it produced.

Where the name comes from — three overlapping ancestors:

1. Manufacturing. A production run: one batch produced under one set of settings. Change the settings, it's a different run. This gives you the sense of bounded, configured, and reproducible-ish.
2. Early computing. In batch-processing days, you submitted a job and the operator ran it. One run = one pass of one job through the machine, producing one printout. This gives you one execution, one output.
3. Machine learning experiment tracking — almost certainly the immediate ancestor. In tools like MLflow and Weights & Biases, a run is one execution of an experiment: it gets a run ID, a config, logged metrics, and an artifact directory. That's exactly Deep Recon's structure — a slug, a config, a memlog, an artifact folder.

Why the word does real work here. Compare the alternatives:

• "Session" would imply it's tied to your conversation. It isn't — it survives on disk.
• "Query" would imply one question, one answer. It's dozens.
• "Report" names only the output, not the process.
• "Run" names the bounded episode plus its record. That's the concept you need, because you refresh a run, deepen a run, resume a run.

How you use it — the three senses, which trip up beginners:

Practical consequences of a run being a bounded, identified thing:

• It has an identity. The folder slug is deterministic, so a draft, its later processing, and a refresh three months on all land in the same run folder. One decision, one run, one artifact — not three loose files.
• It's resumable. Because everything hits disk as it arrives, a run that dies at minute 30 picks up from disk rather than starting over.
• It's refreshable. refresh re-executes only the stale parts of an existing run. You can only do that to something with an identity.
• It's configurable as a unit. Effort, validation, and freshness are properties of the run, set once at the plan gate.

4.3 "Mode" — Draft, Process, Run

Mode = a way of operating; from Latin modus, "measure, manner." Same sense as a camera's portrait/night mode: the same device, different operating logic.

The three are named for what you do, and they differ in where the searching happens:

4.4 "Type" and "pack"

Type = the category of research: market, domain, technical, competitive, user-voice, academic-lit.

Pack = the ~25-line configuration card that a type selects. From the gaming/software sense of a pack: a bundle of assets shipped as a unit (texture pack, expansion pack).

A pack contains: prioritized dimensions, source craft, freshness rules per claim class. This is the "data-driven variation" that let three near-identical workflows collapse into one skill — the procedure is shared, only the card differs.

Decision shape is a second, independent axis: explore (build understanding) or select (choose between options, using a weighted matrix). Shape because it describes the form the conclusion takes. Any type can combine with either.

4.5 "Dimension" — the second term you asked about

What it is: one independent axis of inquiry within your research question. Your question gets decomposed into dimensions; each one is investigated separately, often in parallel; the results are recombined.

Where the name comes from: geometry and measurement. A dimension is an independent direction of variation — you can move along one without moving along the others. Length, width, height. Data analysis borrowed it (a "dimension" in a data cube: time, region, product), and the sense carried is the same: a separable axis.

Why the word is well chosen — it encodes three properties at once:

1. Independence. Dimensions should be as orthogonal as possible, because that's what makes parallel investigation valid. If two dimensions overlap heavily, you're paying twice for one answer.
2. Coverage. Together they should span the decision. In geometry, dimensions that don't span the space leave regions you can't reach; a dimension set that doesn't span the decision leaves blind spots. That's what the "could not determine" section reports.
3. Separability. Each can be handed to a different subagent with a self-contained brief.

How you use it — this is the highest-leverage skill in the whole system. At the plan gate you're shown a proposed dimension list. Your job:

Concrete example from the guide: for an embedding-model choice, the proposed dimensions covered benchmarks, cost, license and maintenance — but omitted behavior under filtered ANN search. Benchmarks measure unfiltered top-k retrieval; your recommender queries with filters. That missing dimension is the difference between a report that answers your question and one that answers a similar-looking question.

4.6 "Topology" — and where breadth-first/depth-first come from

What it is: the shape of how subagents are arranged against the dimensions — how work is split and connected.

Where the name comes from: mathematics. Topology studies properties of shape that survive stretching and bending — what's connected to what, regardless of distance. Network topology (star, ring, bus, mesh) is the borrowing you've probably met: the diagram of what connects to what, ignoring cable length.

Here it means the same: the connection pattern of the work graph. Not how long each part takes — the shape.

The three topologies:

Where "breadth-first" and "depth-first" actually come from — and this is the good part. They are graph-traversal algorithms from computer science.

Imagine exploring a maze:

• Depth-first search (DFS): pick a corridor, follow it as far as it goes, hit a dead end, back up, try the next. You go deep before you go wide. Traces back to Trémaux's 19th-century maze algorithm; formalized in mid-20th-century CS.
• Breadth-first search (BFS): step one pace down every corridor, then two paces down every corridor, and so on. You go wide before you go deep. Developed in the 1950s (Moore, for maze routing; Lee, for circuit routing).

The classic property: BFS finds the shortest path and explores evenly; DFS goes further faster on one path but can get lost down a long wrong corridor.

The metaphor transfers exactly:

• Breadth-first research: cover all six dimensions to a moderate depth, evenly.
• Depth-first research: drive hard down one question, following where it leads, accepting you'll learn less about everything else.

Knowing the algorithms means you can predict the failure modes. BFS's weakness is memory — it holds the whole frontier at once, which is exactly why breadth-first research burns more tokens per round. DFS's weakness is going deep down a corridor that doesn't matter — which is exactly what happens when you depth-first a question that turns out to be a side issue.

Fan-out — a related term. From digital electronics: the number of gate inputs a single output can drive before the signal degrades. Distributed systems borrowed it for one request spawning many downstream calls. Here: one plan spawning N assistants. The electronics sense carries a useful warning — fan-out has a limit past which quality degrades. More parallelism is not free, and it is not automatically better.

4.7 "Plan gate"

What it is: the single mandatory stop where the system shows you what it intends to do, and waits.

Where the name comes from: gate in the sense of a controlled passage — nothing proceeds until it opens. Two direct ancestors:

1. Stage-Gate in product development (formalized by Robert G. Cooper in the 1980s): projects move through stages, and between them sit gates where a decision-maker says go, kill, hold, or recycle. The point of a gate is that it's the only place a decision is made, so the decision gets real attention.
2. Quality gates in CI/CD: the build doesn't advance unless it passes.

Why there is exactly one. Constant interrogation trains you to click through. One well-placed gate that actually matters gets read. After it, the run proceeds with light checkpoints. This is a deliberate attention-budget decision, and it means your attention at the gate is the single highest-value input you provide to the entire system.

What it shows: the decision, the dimensions, the topology, the knobs, and a time estimate. What you do: prune, add, adjust, check that the estimate matches your actual patience.

4.8 Rounds, leads, budgets, presets

Precedence — worth memorizing: your request beats a pinned setting beats the preset. Whatever you say in the moment wins.

4.9 Briefs, digests, claims

Why briefs are written to files and not passed as text on a command line — the security fix in PR #2611, and worth understanding as a beginner because it generalizes. If untrusted text is pasted into a shell command, characters like $(...) or backticks are interpreted as commands rather than read as text. Researched content is untrusted by definition — you fetched it from the internet. The fix wasn't to filter dangerous characters (filters always leak); it was to change the channel so the text never reaches an interpreter. It goes to a file; the command references the file's path.

That pattern — remove the interpreter from the path rather than sanitizing the input — is one of the most transferable ideas in the whole PR.

4.10 "Firewall"

What it is: the rule that your project context may shape which questions get asked, but never what counts as evidence. Subagents receive only their brief.

Where the name comes from: building construction. A firewall is a physical wall built to a fire-resistance standard, dividing a structure into compartments so a fire in one can't spread to the next. Cars borrowed it (the barrier between engine and cabin), then networking borrowed it in the late 1980s.

The property that carries through every sense: a barrier at a boundary that stops one specific thing from propagating, by design and by construction rather than by vigilance.

Why it matters more than it sounds. The failure it prevents is subtle: hand an AI your architecture document and ask it to research alternatives, and it comes back explaining that your architecture is excellent. Not through deceit — through ordinary confirmation bias. The thing generating hypotheses is also grading them.

Most attempts to fix this are instructions — "be objective," "consider alternatives." Instructions fail, because a system inclined to agree with you will find a way. The firewall is architectural: the subagent cannot be biased by context it was never given. That's the difference between a policy and a wall.

The closest analogy from research methodology is the double-blind trial: the experimenter doesn't know which subject got the drug, so their expectations cannot contaminate the measurement. Not "must not" — cannot. Same idea, same reason it works.

4.11 Staleness, freshness, refresh, deepen

The distinction that matters: refresh when time has passed. deepen when a dimension was under-answered. A brand-new question is neither — that's a fresh run.

4.12 Provenance, citations, verification

Why provenance is the right word, not "sources." A source list says where things came from. Provenance adds when it was published, when you accessed it, and who published it — which is what lets someone else evaluate a claim they didn't verify themselves. That's the difference between a bibliography and an audit trail.

4.13 The remaining machinery

5. Six mental models that carry the most weight

If you remember nothing else:

1. Recon is scouting before you commit troops. Cheap relative to what it protects, and it must terminate in a decision or it wasn't recon.

2. The run folder is a lab notebook. Dated, append-only, showing failed attempts alongside successes. The value isn't the conclusion; it's that someone else can check your work — including future you.

3. The firewall is a double-blind trial. The researcher can't be influenced by expectations they were never given. Architectural, not aspirational.

4. Dimensions are axes that must span the space. Independent enough to parallelize, complete enough to cover the decision. Gaps in the span are exactly what "could not determine" reports.

5. Staleness is cache TTL for beliefs. Still readable, no longer trustworthy. Different claim classes have different TTLs, and that's a feature.

6. The plan gate is a stage gate. There is exactly one, deliberately, so that it gets read. Your attention there is the highest-value input you give the system.

6. Where the metaphors break

Understanding a borrowed term includes knowing where the borrowing stops. Four that mislead beginners:

That last one is the most important caveat in this entire document. Deep Recon does not give you knowledge. It gives you auditable justification — a chain you can inspect and challenge. That's a real improvement over uncited fluency, and it is less than a well-formatted, thoroughly-cited report can look like.

7. Learning path: your first two weeks

Week 1 — mechanics

Day 1 — Install and read the shape.

npx bmad-method install

Then /bmad-customize bmad-deep-recon and just read the options. Don't change anything. You're building a map of what's adjustable.

Day 2 — The calibration run. This is the single most useful beginner exercise, and almost nobody does it:

Run a quick engagement on a question you already know the answer to cold — something in your own stack you could write a memo about from memory.

Because you know the content, you're free to evaluate the machinery. Where did it go for sources? Did it find the thing you know is the definitive reference? Where was it confidently thin? Where did it flag uncertainty you'd have glossed over? Twenty minutes here teaches more about calibration than five real runs.

Day 3 — Deliberately break it. Run the anti-pattern: research recommendation system best practices. Watch the plan gate propose eleven dimensions and fifty-five minutes. Kill it at the gate. You'll have learned viscerally why a decision statement is load-bearing, for the price of two minutes.

Day 4 — A real cheap run. Pick a genuine but low-stakes decision — a library choice, a dependency health check. quick, standard validation. Take the output to a colleague and defend it.

Day 5 — Read the artifacts. Open the run folder. Read a brief, a digest, the memlog, then research.md. Trace one claim from the report back through its digest to its source. Once you've done this once, you'll never over-trust a report again.

Week 2 — judgment

Day 6–7 — Draft → Process. Draft a prompt, run it in whatever deep-research tool you have, process it back. The gap report is the lesson: see for yourself what hosted tools systematically miss.

Day 8 — Configure. Write your first user.toml. Set a source policy for one domain you know well — you can tell good sources from bad in your own field, which is exactly what you need to write a policy.

Day 9 — A load-bearing run, with red_team on. Notice how the adversarial pass changes the tone.

Day 10 — Refresh something. Even a two-week-old run. Watch the delta mechanism work.

The habit that makes it stick

Every time you're about to make a decision you'll live with for months, write this sentence first:

"I am choosing between ___, ___ and ___, under constraints ___, ___ and ___, and I'll live with it for ___ months."

If you can write it, you're ready to research. If you can't, you're not ready to research — you're ready to brainstorm, which is a different skill and the right one for that moment.

8. Resources and references

Verify before citing. These are from my own knowledge, not fetched and checked in this session. Titles and authors I'm confident about; URLs and current versions you should confirm.

8.1 BMAD itself — start here

8.2 Agentic systems generally

8.3 The computer science behind the terms

8.4 Epistemology — for §22 of the main guide

All free online:

8.5 Research methodology — best practices worth stealing

8.6 Domain references for the applied sections

Retrieval and recommendation

• MTEB (Muennighoff et al.) and BEIR (Thakur et al.) — the benchmark suites, and more importantly their stated limitations
• Malkov & Yashunin, HNSW (2016/2018) — the original paper for the index you're running
• Shilling / profile-injection attack literature in the recsys venues (RecSys, SIGIR)

Security and adversarial ML

• OWASP Top 10 for LLM Applications — the standard reference for prompt injection and agentic risk
• MITRE ATLAS — adversarial threat landscape for AI systems, structured like ATT&CK
• NIST AI Risk Management Framework
• Shokri et al. (2017) on membership inference; Morris et al. on text-embedding inversion

Privacy and regulation — always primary sources, never summaries

• GDPR text on EUR-Lex; EDPB guidelines and opinions
• ICO (UK) — unusually clear practical guidance, useful even outside UK scope
• OPC Canada (priv.gc.ca) and CAI Québec (cai.gouv.qc.ca) for PIPEDA and Law 25
• The EU AI Act and DSA texts on EUR-Lex

Decision records

• Michael Nygard, "Documenting Architecture Decisions" (2011) — the origin of the ADR format, and the natural home for research output. Short and practical

9. What I'm confident about, and what I'm not

Worth stating plainly, since this document makes a lot of etymological claims.

Well-documented and standard:

• BFS/DFS as graph-traversal algorithms; the maze intuition
• Fan-out from digital electronics
• Firewall from building construction → automotive → networking
• Red team from Cold War military war-gaming
• Slug from newspaper typesetting
• Frontmatter from book publishing
• Provenance from art history and archaeology
• Stage-Gate from Robert G. Cooper's product-development work
• Shim from mechanical engineering
• Digest from Latin digerere and Justinian's Digest
• Reconnaissance from French reconnaître
• TOML named for Tom Preston-Werner
• The philosophical works, authors and dates in §8.4

My inference, reasonable but not documented as BMAD's stated rationale:

• That "run" specifically inherits from ML experiment tracking (MLflow, W&B) rather than the general computing sense. The structural match — run ID, config, artifact directory — is strong enough that I'd bet on it, but the docs don't say so.
• That "dimension" carries the spanning/orthogonality intuition deliberately rather than just meaning "aspect."
• The specific mapping of each mechanism to a named epistemological position in §22 of the main guide. The PR does head a section "Epistemics and reliability," so the intent is explicit; the particular philosophical labels are mine.

Things I have not verified in this session:

• Every URL in §8. I'm confident about titles and authors; check the links.
• Exact TOML key paths — confirm against your installed customize.toml.
• Exact prompt and plan-gate wording, which lives in the skill's reference files.

Where this document and the actual skill disagree, the skill wins. Metaphors are for building intuition, not for settling facts.

Next: bmad-deep-recon-howto.md — every concept here shown as an executable session. Then bmad-deep-recon-guide.md — the full applied guide.