@diottodev/runic 1.0.0 → 1.1.0

package/engineering/grill-me/commands/cs-grill-me.md

@@ -0,0 +1,84 @@
+---
+name: "cs-grill-me"
+description: "/cs:grill-me <path-to-plan> — Start a relentless interrogation of a plan or design. Walks decision tree one branch at a time. One question per turn with recommended answer. Explores codebase before asking."
+---
+
+# /cs:grill-me — Relentless Plan Interrogation
+
+**Command:** `/cs:grill-me <path-to-plan>`
+
+The grill-master persona interrogates a plan one decision branch at a time.
+
+## When to Run
+
+- Stress-testing a plan before commitment
+- Pre-mortem on a design (find weaknesses before they hurt)
+- Onboarding to an existing plan (interrogate what's there)
+- Resuming a grill session from previous turn
+
+## The Six Forcing-Question Patterns
+
+1. **Intent:** "Why X and not Y?" (names the alternative)
+2. **Choice:** "Which side, and what's the deciding constraint?"
+3. **Open:** "What's blocking this decision, and when does the blocker resolve?"
+4. **Tradeoff:** "Which side are you optimizing for, and what's the kill criterion?"
+5. **Dependency:** "Is the upstream decision locked in? If not, that comes first."
+6. **Uncertainty:** "Even at 60% confidence — what's your best guess?"
+
+## Discipline
+
+- **One question per turn.** Never bundle.
+- **Recommended answer attached.** Every question carries a position + rationale.
+- **Codebase before speculation.** `grep` / `Read` resolves before asking.
+- **Depth-first walk.** Finish a branch before opening another.
+
+## Workflow
+
+```bash
+# 1. Extract decision branches from the plan
+python ../skills/grill-me/scripts/decision_tree_extractor.py path/to/plan.md
+
+# 2. Generate forcing questions with recommendations
+python ../skills/grill-me/scripts/question_generator.py path/to/plan.md
+
+# 3. Start session
+python ../skills/grill-me/scripts/grill_session_tracker.py --action start --session NAME --plan path/to/plan.md
+
+# 4. Walk one question at a time:
+#    Persona asks Q1 with recommendation.
+#    User answers.
+#    Record:
+python ../skills/grill-me/scripts/grill_session_tracker.py --action record --session NAME --question-id 1 --answer "..."
+
+# 5. When complete:
+python ../skills/grill-me/scripts/grill_session_tracker.py --action close --session NAME
+```
+
+## When to Stop
+
+- Every branch has an answer
+- 3+ turns with no new questions arising
+- User signals fatigue ("can we move on?")
+- Diminishing returns past ~15 questions
+
+Produce a "decisions locked" summary at close.
+
+## Output Format
+
+```
+Q[i]/[total] (L[line]): [question]
+Recommended: [position] because [1-sentence rationale]
+
+(or: I explored — found [evidence]. Confirm?)
+```
+
+## Related
+
+- Agent: [`cs-grill-master`](../agents/cs-grill-master.md)
+- Skill: [`grill-me`](../skills/grill-me/SKILL.md)
+- Adjacent: `/cs:caveman`, `/cs:handoff`, `/cs:write-a-skill`
+
+---
+
+**Version:** 1.0.0
+**Derived:** Matt Pocock's grill-me (MIT) + this repo's wrapper

package/engineering/grill-me/skills/grill-me/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+license: MIT
+metadata:
+  derived_from: "https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me"
+  original_author: "Matt Pocock (@mattpocock)"
+  original_license: MIT
+  voice: "Matt Pocock — relentless, one-at-a-time, explores-codebase-first"
+  version: 1.0.0
+---
+
+# Grill Me
+
+> Derived from [Matt Pocock's grill-me](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me) (MIT). Matt's interview discipline preserved verbatim. Additions: extraction + question + session tools + references + cs-* wrapper (see [references/companion_tooling.md](references/companion_tooling.md)).
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Rules (preserved + amplified)
+
+1. **One question per turn.** Never bundle.
+2. **Provide a recommended answer with each question.** Defaulting to "what do you think?" is lazy.
+3. **Explore the codebase before asking.** If `grep` / `Read` resolves it, do that first. Saves a turn.
+4. **Walk the tree depth-first.** Finish a branch before opening another.
+5. **Track dependencies.** If decision B depends on decision A, ask A first.
+
+## Workflow
+
+1. User provides a plan or design (or path to one).
+2. Run `scripts/decision_tree_extractor.py` to extract branches.
+3. Run `scripts/question_generator.py` to produce the question list with recommendations.
+4. Start a session: `scripts/grill_session_tracker.py --action start`.
+5. Walk the tree, one question at a time, recording answers in the session.
+6. When all branches resolved: report "shared understanding reached" + the locked-in decisions.
+
+## Output Pattern
+
+Per question turn:
+
+```
+Q[i]/[total]: [question]
+Recommended answer: [your call + 1-sentence rationale]
+
+(Or: I explored the codebase and found [evidence]. Confirm?)
+```
+
+## Tooling
+
+See [references/companion_tooling.md](references/companion_tooling.md). Tools: extractor + generator + tracker. Agent: `cs-grill-master`. Command: `/cs:grill-me`.
+
+---
+
+**Version:** 1.0.0
+**Derived:** Matt Pocock (MIT) + this repo's wrapper

package/engineering/grill-me/skills/grill-me/references/companion_tooling.md

@@ -0,0 +1,65 @@
+# Companion Tooling
+
+Interrogation tools + cs-* wrapper layered on top of Matt's grill-me skill.
+
+## Validation Tools (stdlib Python)
+
+| Tool | Purpose | Run when |
+|---|---|---|
+| `scripts/decision_tree_extractor.py` | Scan a plan doc for decision branches (intent / choice / open / tradeoff / dependency / question) | Starting a grill session — see what's there to interrogate |
+| `scripts/question_generator.py` | Generate forcing questions from extracted branches with recommended answers + dependency-aware ordering | Producing the question list for a grill session |
+| `scripts/grill_session_tracker.py` | JSON-backed session storage in `~/.grill_sessions/` — track answers across turns, resume sessions | Running a multi-turn grill (most real grills) |
+
+All three:
+- Stdlib-only
+- Run with embedded sample if no input provided
+- Output text or JSON (`--output json`)
+
+## Session Storage
+
+`grill_session_tracker.py` persists state to `~/.grill_sessions/<name>.json`. This enables:
+- Resume a grill across days
+- Switch between concurrent grills (e.g., per project)
+- Audit which decisions were resolved when
+- Generate a "decisions locked" summary at end
+
+## cs-grill-master Persona Agent
+
+Lives at `../agents/cs-grill-master.md`. Voice: relentless, one-question-at-a-time, codebase-exploration-first.
+
+The persona's hard rule: **never bundle questions**. Even when there are 10 obvious follow-ups, ask one, wait for answer, then ask the next.
+
+## `/cs:grill-me` Slash Command
+
+Lives at `../commands/cs-grill-me.md`. Activation pattern:
+
+1. `/cs:grill-me <path-to-plan>` — start grill session on plan doc
+2. Persona asks Q1 with recommended answer
+3. User answers
+4. Persona asks Q2
+5. ...continues until all branches resolved
+
+## Why Wrap Matt's Original
+
+Matt's grill-me skill is intentionally minimal (3 sentences). The wrapper adds:
+
+1. **Automatic branch extraction** — manually identifying decision branches is the slow part; the extractor does it deterministically
+2. **Question templating** — consistent question patterns per branch kind (intent / choice / tradeoff)
+3. **Session persistence** — grills span days; persistence prevents re-asking + losing context
+4. **Recommendation defaults** — every question carries a recommended answer (per Matt's "provide your recommended answer" rule)
+
+## Attribution
+
+Original: [matt-pocock/skills/skills/productivity/grill-me](https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me) (MIT).
+
+---
+
+**Source authorities (non-exhaustive):**
+
+- **Matt Pocock — grill-me** (https://github.com/mattpocock/skills/, MIT) — the upstream source
+- **Socratic Method** (5th-century BC) — interrogation as truth-finding; one-question-at-a-time discipline
+- **YC office hours format** (Y Combinator) — forcing questions for founders; "what's blocking this?" + "why this and not Y?"
+- **Cockburn, A. — "Writing Effective Use Cases"** (2000) — exploring decision branches in requirements
+- **Fournier, C. — "The Manager's Path"** (2017) — interview discipline for hard decisions
+- **Larson, W. — "An Elegant Puzzle"** (2019) — engineering manager decision-making patterns
+- **5 Whys (Toyota Production System)** — Sakichi Toyoda — sequential interrogation for root cause

package/engineering/grill-me/skills/grill-me/references/forcing_question_patterns.md

@@ -0,0 +1,152 @@
+# Forcing-Question Patterns for Plan Interrogation
+
+This reference answers exactly one decision: **what makes a question "forcing" vs "soft", and how do we ask forcing questions that resolve decisions?**
+
+Pair with `scripts/question_generator.py` for templated forcing questions.
+
+## What Makes a Question "Forcing"
+
+A forcing question:
+
+1. **Cannot be answered with "yes"/"no"** without follow-up
+2. **Names the alternative** — "X or Y" not "is X right?"
+3. **Demands evidence** — "what's the kill criterion?" not "what do you think?"
+4. **Removes the escape hatch** — asks the trade-off explicitly
+
+Soft questions let the answerer evade. Forcing questions don't.
+
+## Six Forcing-Question Patterns
+
+### Pattern 1: "Why X and not Y?"
+
+When user says "We'll use Postgres" — forcing question: "Why Postgres and not MySQL?"
+
+The forcing element: requires the answerer to articulate the alternative + the rejection reason. Reveals whether the choice was deliberate or default.
+
+**Soft variant (bad):** "Are you sure about Postgres?"
+
+### Pattern 2: "What's the kill criterion?"
+
+When user says "We'll try approach X" — forcing question: "What would convince you X is wrong?"
+
+The forcing element: requires the answerer to commit to falsifiability ahead of time. Prevents motivated reasoning later.
+
+**Soft variant (bad):** "What if it doesn't work?"
+
+### Pattern 3: "What's blocking the decision?"
+
+When user says "TBD" or "open question" — forcing question: "What input is missing, and when does it arrive?"
+
+The forcing element: separates "haven't decided" from "can't decide yet". Most TBDs are decideable now under uncertainty.
+
+**Soft variant (bad):** "Have you thought about that?"
+
+### Pattern 4: "Which side of the trade-off?"
+
+When user says "trade-off between A and B" — forcing question: "Which side are you optimizing for, and what's the deciding constraint?"
+
+The forcing element: requires picking. "Both" is not an option for actual trade-offs.
+
+**Soft variant (bad):** "Have you considered the trade-offs?"
+
+### Pattern 5: "What's the dependency?"
+
+When user says "depends on X" — forcing question: "Is X locked in? If not, that decision comes first."
+
+The forcing element: surfaces dependency chains. Forces depth-first walk of the decision tree.
+
+**Soft variant (bad):** "Have you thought about dependencies?"
+
+### Pattern 6: "Even at 60% confidence — what's your best guess?"
+
+When user hedges — forcing question: "Even uncertain, what would you decide today?"
+
+The forcing element: prevents indefinite deferral. Most decisions can be made under uncertainty + revised later.
+
+**Soft variant (bad):** "When will you decide?"
+
+## The "Recommended Answer" Rule (per Matt)
+
+Every question should carry a recommended answer with rationale. Why:
+
+1. **Models the depth of analysis expected** — answerer sees what "good" looks like
+2. **Accelerates the interview** — answerer can agree/disagree faster than constructing from scratch
+3. **Surfaces interrogator bias** — if the recommendation is wrong, answerer can correct it explicitly
+4. **Prevents "what do you think?" loops** — both sides commit to a position
+
+Format:
+
+> Q: [forcing question]
+> Recommended: [position] because [1-sentence reason].
+
+## One-at-a-Time Discipline (per Matt)
+
+> "Ask the questions one at a time."
+
+Why this matters:
+
+1. **Bundled questions get partial answers** — answerer addresses the easiest one; hard ones get skipped
+2. **Each answer constrains the next** — the second question often changes after hearing the first answer
+3. **Cognitive load** — answerer can focus + give a complete response
+4. **Visible progress** — each Q→A pair locks one decision; bundle masks progress
+
+**Anti-pattern:** "Here are 8 questions: [list]". This is a survey, not an interrogation.
+
+## Codebase Exploration > Speculation (per Matt)
+
+> "If a question can be answered by exploring the codebase, explore the codebase instead."
+
+When to explore instead of asking:
+
+| Question | Action |
+|---|---|
+| "What auth library are we using?" | `grep -r "auth" package.json` — don't ask |
+| "Does X already exist?" | `find . -name "X*"` — don't ask |
+| "What's the current schema?" | `Read path/to/migrations/latest.sql` — don't ask |
+| "Are tests passing?" | Run the test suite — don't ask |
+
+When to ask anyway:
+- Intent: "Why this approach?" can't be grepped
+- Trade-offs: only the human knows which they value
+- Future state: codebase shows current, not desired
+
+## Anti-Patterns
+
+1. **"Are you sure?"** — invites defensive answer; no information value
+2. **"Have you thought about ...?"** — implies "no" is acceptable; doesn't force a decision
+3. **"What if it fails?"** — speculative; better: "what's the kill criterion?"
+4. **"Could you elaborate?"** — passive; better: name the specific gap
+5. **Yes/no questions** without follow-up — wastes the turn
+6. **Stacking questions** — bundles violate one-at-a-time rule
+
+## How `question_generator.py` Implements This
+
+The tool's question templates map each detected branch kind to a forcing-question pattern:
+
+- `intent` → "Why this approach and not the obvious alternative?" (Pattern 1)
+- `choice` → "Which side of the choice, and what's the deciding criterion?" (Pattern 4)
+- `open` → "What's blocking this decision?" (Pattern 3)
+- `tradeoff` → "Which side of the trade-off are you optimizing for?" (Pattern 4)
+- `dependency` → "Is the dependency locked in?" (Pattern 5)
+- `question` → "What's your current best answer, even if uncertain?" (Pattern 6)
+
+Each generated question carries a recommended-answer template per Matt's rule.
+
+## When This Reference Doesn't Help
+
+- **Open-ended exploration** — early-stage ideation needs soft questions; grill-me is for plans not yet committed
+- **Therapeutic/coaching contexts** — forcing questions can feel adversarial; tone matters
+- **Hiring interviews** — different mode; behavioral questions follow different patterns
+
+---
+
+**Source authorities (non-exhaustive):**
+
+- **Matt Pocock — grill-me** (https://github.com/mattpocock/skills/, MIT) — the one-at-a-time + recommended-answer rules
+- **Socratic Method** (5th-century BC) — Plato's dialogues — sequential questioning toward truth
+- **Y Combinator office-hour format** (Garry Tan + Michael Seibel) — founder interrogation pattern
+- **Toyota Production System — 5 Whys** (Sakichi Toyoda) — sequential causal questioning
+- **Cockburn, A. — "Writing Effective Use Cases"** (2000) — decision-branch enumeration
+- **Popper, K. — "Conjectures and Refutations"** (1963) — falsifiability + kill criteria
+- **Galef, J. — "The Scout Mindset"** (2021) — calibrating beliefs under uncertainty
+- **Larson, W. — "An Elegant Puzzle"** (2019) — eng decision-making in practice

package/engineering/grill-me/skills/grill-me/references/when_to_stop_grilling.md

@@ -0,0 +1,142 @@
+# When to Stop Grilling
+
+This reference answers exactly one decision: **when is "shared understanding" actually reached, and how do we know to stop the interrogation?**
+
+Pair with `scripts/grill_session_tracker.py` — the session tracker shows progress and surfaces unanswered branches.
+
+## Matt Pocock's Stopping Condition (Implicit)
+
+> "Interview me relentlessly about every aspect of this plan until we reach a shared understanding."
+>
+> — Matt Pocock, grill-me SKILL.md
+
+"Shared understanding" is the stopping condition. But what does that mean operationally?
+
+## Three Conditions That Mean "Stop"
+
+### Condition 1: Every decision branch has an answer
+
+Track via `grill_session_tracker.py status`. When `percent_complete = 100%`, every detected branch has a recorded answer. Stop grilling.
+
+**Risk:** The extractor missed branches. Run `decision_tree_extractor.py` once more after answers are in — sometimes answers reveal new branches.
+
+### Condition 2: No new questions arise from the last 3 answers
+
+If the last 3 answers all triggered follow-up questions, grilling continues. If 3 answers in a row resolve cleanly with no new questions, the tree is exhausted.
+
+**Pattern:** count the rate of new-question generation per turn. When it drops to zero for 3+ turns, stop.
+
+### Condition 3: The interrogator can predict the answerer's response
+
+If the interrogator can predict, with high confidence, what the answerer will say to the next question — that question doesn't add information. Skip it or stop entirely.
+
+**Test:** before asking the next question, write down your guess at the answer. If the guess matches, you don't need to ask. Move on.
+
+## Three Conditions That Mean "Keep Going"
+
+### Condition A: The answerer is dodging
+
+Signs:
+- "We'll figure that out later" (without a date)
+- "It depends" (without naming the dependency)
+- Answers a different question than was asked
+- Hedges every answer with "probably" / "likely" / "maybe"
+
+Action: re-ask the same question with the same words. If dodged twice, name the dodge: "You said 'we'll figure it out later' — what's the latest moment you can decide and still ship?"
+
+### Condition B: Answers contradict each other
+
+If Q3 answer contradicts Q1 answer, stop the forward progress and reconcile:
+
+> "You said X in Q1 but now Y in Q3. Which is it?"
+
+Reconciliation is a separate grill phase — don't continue forward until resolved.
+
+### Condition C: A new branch surfaces
+
+If the answerer says "but if we do X, then we also need to decide Y" — Y is a new branch. Add to the question queue. Don't stop until Y is resolved.
+
+## The "Recommended Answer Match" Heuristic
+
+When generating questions with `question_generator.py`, each question has a recommended answer. Track:
+
+| Answer matches recommendation? | What it means |
+|---|---|
+| Yes, with same rationale | Strong signal — both interrogator + answerer converged on the same logic |
+| Yes, different rationale | Worth probing — same conclusion via different reasoning could mean one is wrong |
+| No, with strong rationale | Healthy disagreement — record the rationale; this is the value of the grill |
+| No, weak rationale | Push back — "the recommendation was X because Y; your answer rejects Y — why?" |
+
+When 80%+ of answers match the recommendations cleanly, the grill is over-engineered for this plan — stop.
+
+## The "Diminishing Returns" Test
+
+Each grill question costs ~1 turn. After 10-15 questions on a single plan, returns diminish:
+- First 3-5: high value (catches major missing decisions)
+- Questions 6-10: medium value (refines edge cases)
+- Questions 11-15: lower value (catches rare edge cases)
+- Questions 16+: noise (usually the interrogator over-conditioning)
+
+If a plan has 20+ branches, consider splitting into multiple plans rather than one mega-grill.
+
+## When to Stop Even Before Conditions Met
+
+### When the user signals fatigue
+
+> "Can we move on?" / "Let's just decide and revisit if needed" / "Skip ahead"
+
+Stop. Note unresolved branches in the session for later. Don't push through fatigue — answers under fatigue are often wrong.
+
+### When the cost of deciding exceeds the cost of being wrong
+
+For reversible decisions, grilling is overhead. Ship and revisit. For irreversible decisions, grill thoroughly.
+
+Test: "If we're wrong about this, what does it cost to fix?" If the answer is "trivial" or "we just change a flag", stop grilling early.
+
+### When the plan is exploratory
+
+If the plan is "let's try X for a week and see" — don't grill the details. Grill the decision criteria for after the week.
+
+## The Locking-In Pattern
+
+When the grill ends, the session should produce a "decisions locked" summary:
+
+```
+Session: my-plan
+Started: 2026-05-13
+Closed: 2026-05-13
+Status: Complete (8/8 branches resolved)
+
+Decisions locked:
+  1. [L4] Schema-per-tenant chosen for cost reasons; isolation risk accepted.
+  2. [L8] Okta for SSO. Auth0 rejected (less Workday integration).
+  3. ...
+```
+
+The summary becomes the reference document. The grill session is throwaway; the summary is the artifact.
+
+## Anti-Patterns
+
+1. **Grilling forever** — every plan has 100 decideable details; grill stops at "shared understanding", not "complete certainty"
+2. **Grilling reversible decisions** — wasteful; ship + revise
+3. **Grilling without producing a summary** — wastes the answers; lock them in
+4. **Grilling without exploring codebase first** — wastes turns asking questions the code answers
+5. **Re-grilling the same plan** — if the plan was already grilled, don't re-grill the same branches; only grill new branches
+
+## When This Reference Doesn't Help
+
+- **Live-decision grilling in a meeting** — different mode; meetings have time pressure
+- **Code review** — different scope; review is post-decision
+- **Brainstorming** — wrong tool; grilling is for committed plans, not exploration
+
+---
+
+**Source authorities (non-exhaustive):**
+
+- **Matt Pocock — grill-me** (https://github.com/mattpocock/skills/, MIT) — the "shared understanding" stopping condition
+- **Galef, J. — "The Scout Mindset"** (2021) — when to stop seeking more evidence
+- **Kahneman, D. — "Thinking, Fast and Slow"** (2011) — decision fatigue + diminishing returns
+- **Bezos, J. — Type 1 vs Type 2 decisions** (Amazon shareholder letter, 2015) — reversible vs irreversible decisions
+- **YC Founder School — "Decide and move on"** — when grilling becomes procrastination
+- **Larson, W. — "An Elegant Puzzle"** (2019) — engineering decision-making sequencing
+- **Cynefin framework (Snowden)** — different decision domains require different evidence thresholds

package/engineering/grill-me/skills/grill-me/scripts/decision_tree_extractor.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""decision_tree_extractor.py — Extract decision branches from a plan/design doc.
+
+Stdlib-only. Scans a markdown plan and identifies decision branches by detecting:
+
+  1. Modal verbs of intent: "we'll", "we will", "we plan to", "we should", "we could"
+  2. Open questions: sentences ending in "?"
+  3. Choices: "X or Y" / "either X or Y" / "vs"
+  4. TBDs: "TBD", "to be decided", "open question"
+  5. Trade-off markers: "trade-off", "tradeoff", "pros/cons"
+
+Output: numbered list of decision branches with line refs.
+
+NO LLM CALLS. Pure regex + line walking.
+
+Usage:
+    python decision_tree_extractor.py                          # uses embedded sample
+    python decision_tree_extractor.py path/to/plan.md
+    python decision_tree_extractor.py plan.md --output json
+"""
+
+import argparse
+import json
+import re
+import sys
+from typing import Any, Dict, List
+
+
+# Regex patterns that indicate a decision branch
+DECISION_PATTERNS = [
+    (re.compile(r"\bwe\s*(?:'ll|will|plan\s+to|should|could|might|may)\b", re.IGNORECASE),
+     "intent"),
+    (re.compile(r"\b(?:either|or)\b.{0,80}\b(?:or|alternatively)\b", re.IGNORECASE),
+     "choice"),
+    (re.compile(r"\bversus\b|\bvs\.?\b", re.IGNORECASE),
+     "choice"),
+    (re.compile(r"\bTBD\b|\bto\s+be\s+(?:decided|determined)\b", re.IGNORECASE),
+     "open"),
+    (re.compile(r"\bopen\s+question\b", re.IGNORECASE),
+     "open"),
+    (re.compile(r"\btrade-?offs?\b", re.IGNORECASE),
+     "tradeoff"),
+    (re.compile(r"\bdepends?\s+on\b", re.IGNORECASE),
+     "dependency"),
+    (re.compile(r"\?\s*$"),
+     "question"),
+]
+
+
+SAMPLE_PLAN = """# Plan: Multi-tenant SaaS Migration
+
+## Architecture
+We'll move to a single-tenant database per customer. Or maybe we should
+do schema-per-tenant for cost. This is a trade-off between isolation and ops cost.
+
+## Auth
+TBD: SSO provider — Okta or Auth0?
+
+## Migration sequence
+We plan to migrate the largest tenant first. Depends on whether their data fits in 24h.
+Open question: rollback strategy?
+
+## Data layer
+We could use Postgres logical replication, but we might prefer dual-writes.
+Trade-off: complexity vs zero-downtime guarantee.
+
+## Cut-over
+Final decision TBD on whether to flip DNS at midnight or use feature flags.
+"""
+
+
+def extract_branches(text: str) -> List[Dict[str, Any]]:
+    branches: List[Dict[str, Any]] = []
+    seen_lines = set()
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        for pattern, kind in DECISION_PATTERNS:
+            match = pattern.search(line)
+            if not match:
+                continue
+            if line_no in seen_lines:
+                continue
+            seen_lines.add(line_no)
+            branches.append({
+                "line": line_no,
+                "kind": kind,
+                "trigger": match.group(0),
+                "context": line.strip()[:160],
+            })
+            break
+    return branches
+
+
+def analyze(text: str) -> Dict[str, Any]:
+    branches = extract_branches(text)
+    by_kind: Dict[str, int] = {}
+    for b in branches:
+        by_kind[b["kind"]] = by_kind.get(b["kind"], 0) + 1
+    return {
+        "total_branches": len(branches),
+        "by_kind": by_kind,
+        "branches": branches,
+    }
+
+
+def render_text(r: Dict[str, Any]) -> str:
+    lines = []
+    lines.append("=" * 72)
+    lines.append("DECISION TREE EXTRACTOR")
+    lines.append("=" * 72)
+    lines.append("")
+    lines.append(f"Total decision branches found: {r['total_branches']}")
+    lines.append(f"By kind: {r['by_kind']}")
+    lines.append("")
+    lines.append("-" * 72)
+    for i, b in enumerate(r["branches"], start=1):
+        lines.append(f"  [{i:2d}] L{b['line']:>4d} ({b['kind']:11s}) {b['context']}")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Extract decision branches from a plan/design document.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument("path", nargs="?", help="Path to markdown plan (uses embedded sample if omitted)")
+    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
+    args = parser.parse_args()
+
+    if args.path:
+        try:
+            with open(args.path, "r", encoding="utf-8") as f:
+                text = f.read()
+        except (IOError, OSError) as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+    else:
+        text = SAMPLE_PLAN
+
+    result = analyze(text)
+    if args.output == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        print(render_text(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())