branchmind-deep-think

name	branchmind-deep-think
description	Repeatable flagship workflow for long, deep problem solving with BranchMind (branch/think/merge): frame the problem, branch by orthogonal lenses, red-team, plan falsification experiments, synthesize via merges, and promote the best result into main. Use for hard design/research/architecture work that benefits from durable, multi-path reasoning across sessions.

BranchMind Deep Think ($branchmind-deep-think)

Overview

Use BranchMind as a Git-like reasoning ledger:

• Branches are lanes of investigation (orthogonal lenses).
• Commits are atomic thought steps (claims, evidence, decisions, tests).
• Merges are explicit syntheses (what is kept, dropped, and why).

Keep main as “best current answer”, not as a scratchpad.

Safety (short)

BranchMind is persistent (local storage) — treat it as a durable log. Do not put secrets / tokens / PII into commits or merge bodies.

Tool contract (do not fight it)

• Use only the three tools: branch, think, merge (Codex calls them via mcp__branchmind__branch, mcp__branchmind__think, mcp__branchmind__merge).
• Provide exactly two top-level arguments: { workspace, markdown }.
• Put exactly one fenced block inside markdown (no text outside).

Template:

```bm
<verb> key=value key2="quoted value"
<optional body lines>
```

Do not rely on tool-name namespaces (branchmind/..., bm.*): tool names are strict.

References (use these, do not reinvent)

• references/SNIPPETS.md — canonical copy/paste ```bm ... ``` blocks (branch/think/merge).
• references/CHECKLISTS.md — promotion gates, red-team + experiment + synthesis checklists.
• references/EXAMPLES.md — 3 end-to-end flagship examples (architecture, science, incident).

Quick start (minimal, repeatable)

Pick one stable workspace id per problem, e.g. acme-authz-v1.

1. Initialize main:

• Run branch.main (see references/SNIPPETS.md).

2. Write the north star:

• Run think.commit in main (north star template in references/SNIPPETS.md).
• Use the checklist in references/CHECKLISTS.md to keep it falsifiable.

3. Create the minimal lanes:

• frame, arch-a, red-team, experiments, synth-v1 (snippets in references/SNIPPETS.md).

4. Work lanes with atomic commits:

• Use the lane commit template from references/SNIPPETS.md.
• Follow the lane checklist in references/CHECKLISTS.md.

5. Synthesize:

• Merge lanes into synth-v1 with merge.into (synthesis template in references/SNIPPETS.md).
• Use the synthesis checklist in references/CHECKLISTS.md.

6. Promote:

• Merge synth-v1 back into main (promotion snippet in references/SNIPPETS.md).
• Apply the promote-to-main checklist from references/CHECKLISTS.md.

Workflow (default, minimal)

Step 0 — Initialize main and write the “north star”

1. branch.main
2. think.commit in main (north star)

Step 1 — Create orthogonal exploration lanes (minimal set first)

Create only as many lanes as you can actively maintain.

Minimal set (start here):

• frame — clarify goal, constraints, stakeholders, and “what would surprise us”.
• arch-a — first candidate mechanism/architecture.
• red-team — kill criteria + failure modes.
• experiments — fastest falsification/proofs.
• synth-v1 — synthesis lane.

Optional lanes (add only if needed):

• first-principles — invariants and lower bounds.
• arch-b, arch-c — genuinely different candidates.

Step 2 — Work each lane with atomic commits (no essays)

Rule: 1 commit = 1 claim / decision / test plan / derived constraint.

Keep commit messages stable and short. Put detail in the body.

Use checkpoints:

• every ~5–10 commits per lane, add a checkpoint-* commit summarizing current best.

Step 3 — Red-team continuously (do not “save it for later”)

Write explicit kill criteria early:

• “If X is true, this lane is dead.”
• “If we can’t get Y in Z budget, this is dead.”

Record counterexamples and failure modes as first-class commits.

Step 4 — Synthesize into synth-vN (merge is a written synthesis, not a button)

Create synth-v1 from main, then merge in the best lanes.

Use merge body as the synthesis spec:

• kept / dropped
• assumptions accepted
• contradictions resolved
• risks + mitigations
• next experiments

Step 5 — Promote to main only when it is the best known answer

Promotion gate (typical):

• constraints satisfied (or explicitly traded off)
• red-team hazards addressed (or explicitly accepted)
• a falsification/validation plan exists (even if not executed yet)

Step 6 — Iterate

If new evidence breaks the synthesis:

• branch from main again (synth-v2),
• redo the merge with updated evidence,
• keep main as “best today”, not “perfect forever”.

Anti-patterns (avoid)

• Create 10+ branches “just in case”.
• Dump unstructured essays into single commits.
• Merge lanes without writing a synthesis.
• Promote to main before red-team and test plan exist.
• Treat branch.checkout as a default selector (always pass branch= explicitly).