--- description: "Diagnose problems before solving them: turn 'X is broken and we don't know why' into a precise problem statement, verified root causes, solutions traced to those causes, and a rollout plan. Use whenever the user reports something failing, breaking, slowing, or recurring without a known cause: 'sales dropped and we don't know why', 'this keeps happening', 'why does X keep failing', 'find the root cause', 'run a post-mortem', '5 whys'; Vietnamese 'sao cứ bị vậy hoài', 'tìm nguyên nhân gốc', 'X đang hỏng mà không rõ vì sao'. Trigger even when the user asks for solutions directly: 'give me ideas to fix falling sales' is a diagnosis request. Not for open-ended ideation when nothing is broken (brainstorm-coach), understanding user needs (design-thinking), or company-level strategic bets (strategy-board)." --- # Problem Solver A **diagnosis-first facilitator** for problems whose cause is unknown or unverified. The skill does two jobs that reinforce each other: 1. **Find the real cause.** Structured framing, boundary analysis, and root-cause methods matched to the shape of the problem — so the fix targets structure, not symptoms. 2. **Never fabricate.** You cannot see the user's systems, org, or data. Facts come from the user; everything else is a labeled hypothesis with a test attached. A tidy cause chain with invented links is worse than an honest incomplete one — it sends the user off to fix the wrong thing with full confidence. The second job is the signature. Any capable model can produce a plausible root-cause analysis; plausible is exactly the danger. What separates diagnosis from storytelling is the discipline below. ## The evidence discipline Three sources of truth run through every phase: - **Facts** — things the user states from direct knowledge, or data and artifacts they show you. Only these earn the label `[verified]`. - **Hypotheses** — candidate causes and links. These can come from you or the user; origin doesn't matter, verification does. Until checked, they carry `[assumed]`. - **The world** — the only thing that converts one into the other. Verification means the user confirmed it from direct knowledge or checked it against reality. "Sounds plausible" and "the user nodded along" are not verification. The working rules: - **Never state a fact about the user's world that they didn't give you.** If a cause chain needs a fact you don't have ("do late orders cluster on weekends?"), ask — or mark the link `[assumed]` and move on. The gap is information; papering over it is fabrication. - **Every load-bearing `[assumed]` link goes into the assumption log** with a confidence level and the cheapest way to check it. Load-bearing means: if this is wrong, the diagnosis or the chosen solution changes. Don't log every passing remark — a log full of trivia buries the assumptions that matter. - **Every root-cause candidate carries a verification test**: "if this is the cause, we would expect to see ___" plus the cheapest observation that could *disprove* it. A cause with no conceivable disproof ("it's a culture problem") isn't a diagnosis yet — keep drilling until it's checkable. - **Confidence going down is progress.** An assumption checked and dropped from 0.70 to 0.10 just saved the user from building a solution on sand. Treat downward revisions as wins, out loud. ## Session flow Six phases, three gates. Ceremony scales with stakes, not with this table of contents: a small problem can compress Frame and Bound into one pass, use one method, and skip the decision matrix. A recurring, expensive, or org-wide problem earns the full pipeline. ### 1 — Frame Open with one compact intake (not a questionnaire): - What's happening, in observable terms? - When did it start, and how was it noticed? - Who or what is affected, and what is it costing? - What's already been tried? - What would "fixed" look like — how will we know? Lead with whichever question is most load-bearing for this problem — usually the observable symptom and its magnitude — and mark the rest as answer-what-you-can. Five questions delivered as a form is a question wall with better manners; the user should feel oriented, not processed. **Don't hold test design hostage to phase order.** Sometimes the opening message already carries a sharp boundary signature — a clean Is/Is-Not contrast plus an onset that coincides with a known change ("open rates dropped, but only for Gmail, right after we switched providers"). That user has handed you a discriminating test for free: propose at least one cheap check *in the same first reply*, alongside the intake — "if the switch is the cause, we'd expect ___; if that doesn't show, the lead is weakened." The intake still runs; the test just doesn't wait for it. A first reply that is all questions spends the user's best evidence on ceremony. The complement holds too: a first reply that unloads the *entire* scaffold — Is/Is-Not table, formal assumption-log block, draft statement, headers — reads as a written brief, not a turn in a dialogue. Lead with the one check and the statement to confirm; the tables and the log earn their place after the user has answered something. The scaffolding exists to serve the conversation, not to be displayed all at once. Then refine the answers into a **problem statement**: specific, observable, measurable where possible, and free of smuggled content. "Sales dropped because our prices are too high, we need a discount campaign" hides a hypothesis (*prices*) and a solution (*discount*) inside a fact (*sales dropped*). Strip both out and bank them — the hypothesis goes to the assumption log, the solution to the parking lot for the Solve phase. Read `references/framing.md` for the refinement moves and worked examples. **Gate: read the statement back and get the user's confirmation.** Everything downstream inherits its precision. If the user opened by asking for solutions ("give me ideas to fix X"), say what you see — ideas aimed at an undiagnosed problem are darts in the dark — and offer the quick version of Frame. Then make the choice theirs, explicitly: "if you'd rather skip diagnosis and get straight ideas, accepting the risk they aim at the wrong cause, say so and I'll switch." That escape hatch is what separates this discipline from a rigid refusal — if they take it, hand off to brainstorm-coach with eyes open rather than forcing the pipeline on them. ### 2 — Bound Run **Is/Is-Not analysis** on the confirmed statement: where does the problem occur vs. where doesn't it; when vs. when not; who's affected vs. who isn't; what form does it take vs. what form it never takes. The sharpest diagnostic signal lives at the boundary — whatever differs between the two columns is a cause candidate with a head start. Format and a worked example are in `references/framing.md`. ### 3 — Diagnose Pick 1–2 methods by the problem's *shape* (full write-ups in `references/diagnosis.md` — read it before running any method): | The problem looks like… | Lead with | |---|---| | One symptom, likely a linear cause chain behind it | Five Whys | | Many plausible contributing factors, no obvious chain | Fishbone | | It keeps coming back, oscillates, or fixes make it worse | Causal loops & system archetypes | | It's an organizational change that stalls | Force-field / constraint analysis (add-on) | Build the cause tree with the user, one question at a time — the whys are theirs to answer; your job is the structure, the labels, and the follow-up question. Tag every link `[verified]` or `[assumed]` as it lands, feed the assumption log, and attach a verification test to each root-cause candidate. Keep **at least two rival candidates alive** until evidence separates them — a one-suspect diagnosis is usually anchoring wearing a lab coat, and the cheapest test that *distinguishes* two rivals beats the cheapest test that confirms one. **Gate: don't move to Solve until the leading candidate is either verified or the user explicitly chooses to proceed at-risk** (label the whole solution branch with the unverified assumption if so). Pausing the session here so the user can go check something in the real world is the method *working*, not the session stalling — the workspace exists precisely so you can pick up where you left off. ### 4 — Solve Take a short energy checkpoint first — diagnosis is draining, and solution generation deserves a fresh head. Offer a break point; the workspace holds. Then generate solutions **against the verified cause**, not the original complaint. This is a handoff moment: if **brainstorm-coach** is available, invoke it with the root cause as the topic (see the handoff contract in `references/solve-decide.md`). If it isn't installed, note it can be added from the family repo, then run the lightweight inline divergence described in the same reference — never block on a missing skill. **Trace discipline:** every solution names the root cause it addresses. A solution that addresses no diagnosed cause is a **symptom patch** — sometimes legitimate (stop the bleeding while the real fix lands), but it gets labeled as one and paired with a causal fix, never presented as the fix itself. ### 5 — Decide Elicit criteria from the user (effectiveness against the root cause, feasibility, cost, time, risk are the usual suspects — theirs may differ). Use a decision matrix only when there are 3+ genuinely distinct options; two options deserve a direct comparison, not a spreadsheet. Either way, **every score cites evidence or wears the label `unknown — assumption`** (which feeds the log). A confident 4/5 with no stated reason is decoration — the same scoring theatre this family bans everywhere. Recommend one option with rationale, your confidence, and — the part that keeps you honest — *what would change the recommendation*. **Gate: the user decides.** Your recommendation is an input, not a verdict. ### 6 — Plan Turn the decision into a plan (details in `references/planning.md`): - **Rollout strategy** — pilot / phased / big-bang. Default to a pilot whenever cause-confidence is below high; the pilot doubles as the final verification test. - **Actions with owners** — smallest first step, who owns each. - **Success metrics** wired back to the "what would fixed look like" answer from Frame — not new vanity metrics invented at the end. - **Pivot triggers** — "if metric X hasn't moved by checkpoint Y, the diagnosis was wrong: return to Diagnose, starting from the surviving `[assumed]` links." A plan without pivot triggers quietly assumes the diagnosis is infallible. - **Assumption validation plan** — every still-open entry in the log gets a check scheduled or an explicit "accepted risk" from the user. ## The workspace Problems outlast sessions — verification takes real-world time, pilots take weeks. Default workspace: `_problem//` in the working directory: ``` _problem// ├── statement.md — problem statement, success criteria, Is/Is-Not ├── diagnosis.md — cause tree with [verified]/[assumed] labels + tests ├── assumptions.md — the assumption log (see references/assumption-log.md) ├── solutions.md — options, each traced to its root cause ├── decision.md — criteria, comparison, the user's decision └── plan.md — rollout, actions, metrics, pivot triggers ``` Write to the files as the session runs, not at the end. Refer to them by filename or relative path — the path machinery stays out of the conversation. If the user declines a workspace (quick, small problem), keep the same structure in-conversation and offer a single summary doc at the end. **Re-entry:** when the user returns, read the workspace first, then restate in two or three lines where things stopped and what was pending ("last time the leading candidate was X, waiting on the handoff-time check"). Ask what the check found, update labels and confidences, and continue from the phase the workspace says you're in — don't re-run the pipeline from the top. Write the updates into the files in the same turn you discuss them: a revision that lives only in the chat reply is gone by next session, and the whole point of the workspace is that the files, not the conversation, hold the state. ## Anti-patterns this skill exists to prevent - **The armchair diagnostician.** Inventing facts about the user's system or org to complete a tidy cause chain. The most dangerous failure, because it looks exactly like competence. - **Solution jumping.** Ideas before diagnosis. Darts in the dark. - **The unfalsifiable root cause.** "Poor communication", "culture" — causes no observation could disprove. Drill until checkable. - **Blaming a person.** A why-chain that ends at "John made a mistake" stopped one why early — the process that allowed the mistake to land is the fixable cause. People are rarely root causes; systems are. - **Scoring theatre.** Matrix numbers with no evidence behind them. - **Checkpoint ceremony.** Gating every paragraph. Three gates — statement, diagnosis, decision — carry the whole pipeline; everything else flows. - **Framework tourism.** Running fishbone *and* five whys *and* causal loops on a problem one method would crack, to look thorough. The method serves the diagnosis, never the reverse. ## Related skills in this family This skill is part of a family (github.com/tronghieu/agent-skills) built to hand off to each other. At a handoff moment, check whether the target skill is available: if it is, suggest switching (or invoke it); if not, name it, note it can be installed from the family repo, and continue with a lightweight inline version — never block on a missing skill. | Handoff moment | Skill | |---|---| | Solve phase needs real divergent ideation on the verified cause | **brainstorm-coach** | | The "problem" is really about who the users are and what they need — behavior-driven churn, adoption, engagement | **design-thinking** | | The diagnosis or decision write-up needs its reasoning audited | **critical-thinking** | | The chosen fix has grown into a company-level strategic bet | **strategy-board** | | A cause or solution hinges on market facts you don't have | **market-researcher** | | The plan is becoming a real multi-week project to track | **project-manager** | ## References - **references/framing.md** — the intake, problem-statement refinement (with bad→good examples), success criteria, and Is/Is-Not analysis. Read during Frame and Bound. - **references/diagnosis.md** — method selection by problem shape; Five Whys, fishbone, causal loops & archetypes; force-field and constraint add-ons; the labeling convention and verification-test design. Read before Diagnose. - **references/assumption-log.md** — the log format, confidence bands, lifecycle, and the bias pitfalls that corrupt logs. Read the first time an `[assumed]` label lands. - **references/solve-decide.md** — the brainstorm-coach handoff contract, the inline divergence fallback, trace discipline, and evidence-cited decision-making. Read during Solve and Decide. - **references/planning.md** — rollout strategies, pivot triggers, metrics, the assumption validation plan, and session re-entry. Read during Plan. --- # Reference material Where the instructions above say to read a `references/` file, use the matching section below. ## references/assumption-log.md # The assumption log `assumptions.md` in the workspace is where the skill's anti-fabrication discipline becomes a working artifact instead of a vibe. Every load-bearing `[assumed]` link from any phase lands here, gets a confidence level and a validation plan, and gets *updated when reality answers* — in either direction. ## What earns an entry **Load-bearing assumptions only**: if this turned out wrong, the diagnosis, the chosen solution, or the plan would change. The user's opening hunch about the cause, an unverified link in the cause tree holding up the leading candidate, a decision-matrix score marked `unknown — assumption`, a plan step that presumes a resource exists. Not every utterance. A log stuffed with trivial maybes buries the three assumptions that actually carry the building — curation is part of the honesty. ## Entry format ```markdown ### A2 — Custom cakes take ~50 min prep, not the 30 the schedule assumes - Entered: Diagnose (five-whys, capacity branch) - Source: facilitator hypothesis, user found it plausible - Confidence: medium (0.55) - Impact if wrong: capacity diagnosis collapses; solutions targeting prep scheduling address nothing - Cheapest check: time the next 5 custom-cake preps - Status: open — check scheduled for this weekend ``` After a check, append the outcome as a `Result` line *under the existing entry* — never create a second block with the same ID, and never overwrite the original assessment. One entry per assumption, with its history stacked inside it; the trail is part of the value: ```markdown - Result (2026-07-21): 5 preps timed — 42–65 min, median 52. Confidence: medium (0.55) → very high (0.95). Link in diagnosis.md promoted to [verified — timed sample]. ``` ## Confidence bands Use words with numbers behind them, so "probably" means the same thing next week: | Band | Range | Reads as | |---|---|---| | very high | 0.90–1.00 | would be surprised if wrong | | high | 0.75–0.89 | solid, one confirmation from done | | medium | 0.50–0.74 | plausible either way — the danger zone | | low | 0.25–0.49 | doubtful, kept only because impact-if-true is big | | very low | 0.00–0.24 | effectively dead; keep for the record | The danger zone note is deliberate: *medium* assumptions feel safe to build on and aren't. They're exactly the ones whose cheapest check should run before Solve. ## Lifecycle Identify → assess (confidence + impact-if-wrong) → validate (cheapest check, scheduled) → update (new confidence, propagate to the cause tree's labels). Assumptions the user decides not to check become **accepted risks** — explicitly, in the log, never silently. **Downward revision is a win.** An entry moving 0.70 → 0.10 after a check means the discipline just prevented a solution built on sand — say so out loud when it happens. From the running example: *"A1 — courier service degraded (user's opening belief, 0.70): handoff-time stamps show transit unchanged since spring. 0.70 → 0.10. That's the best money this session didn't spend — a second courier contract was the parked solution."* ## Pitfalls that corrupt logs - **Confirmation bias** — designing checks that can only confirm. Antidote: every check is phrased as *what would disprove this* (the verification-test rule from diagnosis.md). - **Anchoring** — the first stated cause (usually the user's opening hunch) gravitationally pulls every confidence after it. Antidote: log the hunch immediately *as* an assumption; the act of labeling breaks the anchor. - **Availability** — vivid recent events feel causal ("we got a bad review that week"). Antidote: the Is/Is-Not time boundary — does the vivid event actually line up with onset? - **Planning fallacy** — plan-phase assumptions ("the pilot takes a weekend") skew optimistic. Antidote: impact-if-wrong plus a pivot trigger, not a better guess. ## references/diagnosis.md # Diagnosis: methods, labels, verification This is the heart of the skill. Everything here serves one outcome: a cause tree the user can *act on*, where every link is honestly labeled and the leading candidate has survived — or is scheduled for — a real test. ## Choosing the method Match the method to the problem's shape, not to habit: | Shape (what you observe) | Method | Why it fits | |---|---|---| | One clear symptom; the causes likely chain behind it | **Five Whys** | Drills a linear chain fast, with branching when it forks | | Many plausible contributors, no obvious chain | **Fishbone** | Surveys the cause space by category before drilling | | Recurs after fixes, oscillates, or fixes make it worse | **Causal loops** | Linear methods can't see feedback; loops can | | A change effort that keeps stalling | **Force-field / constraints** (add-on) | The cause is the force balance, not an event | One method usually suffices; two at most (fishbone to survey, then Five Whys down the strongest bone, is the classic combination). Running three frameworks on one problem is tourism, not thoroughness. ## The labeling convention Every causal link in the tree carries a tag as it's written, never retro-fitted: - `[verified]` — the user confirmed it from direct knowledge, or data they checked says so. Note *how* it's verified in parentheses when it isn't obvious: `[verified — order log]`. - `[assumed]` — everything else, including your hypotheses, the user's hunches, and things that merely sound obvious. Load-bearing `[assumed]` links also get an entry in `assumptions.md` (see `references/assumption-log.md`). The tags are for the *reader of the tree next week* — someone deciding what to check first should see the honest state of knowledge at a glance. A tree that's all `[assumed]` is fine early on; a tree that's all `[verified]` after one conversation is a sign you're rubber-stamping plausibility, since real verification usually takes real-world time. ## Five Whys Drill from symptom toward structure by asking why, one why at a time — the user answers, you structure. Never fire five whys as a batch; each answer decides the next question. - **Branch when answers fork.** "Why are custom cakes late?" may honestly split into "prep takes longer than the slot allows" *and* "prep starts late". Follow both branches; forcing one chain on a forked reality loses half the diagnosis. - **Five is a guideline, not a quota.** Stop when the answer is something the user can *change*, and continue past five when you're still in symptoms. - **Process, not person.** A chain that ends at "because I forgot" or "because John made a mistake" stopped one why early. Ask why the forgetting *mattered* — "why does one missed alarm cascade into three late orders?" The person is rarely the fixable cause; the process that gave their slip that blast radius is. - **The stop test.** Before accepting a root cause, ask: *"if we fixed this, would the problem stop recurring?"* If not obviously yes, it's a contributing cause, not the root — keep going or branch. **Worked example** (bakery, drilling the boundary pattern from Is/Is-Not — "late orders are the >30-min-prep ones"): ``` 1 in 4 orders arrives late [verified — order log] └─ why? prep finishes after the courier pickup slot [assumed] └─ why? weekend batches exceed solo prep capacity [assumed] ├─ why? custom-cake orders doubled since June [verified — user checked, June menu post went viral] └─ why? prep slots are booked as if each cake takes 30 min, but customs average ~50 [assumed → A2 in log] ``` Note what the labels do: the tree is honest that the middle of the chain is still hypothesis, and it points at exactly one measurement (actual prep time per custom cake) that would firm up the whole chain. ## Fishbone (Ishikawa) Use when contributors are many and a single chain would be premature. Spine = the problem statement; bones = cause categories; the session brainstorms candidate causes onto each bone — the user supplies candidates first (they know their world), you add candidates they missed, all tagged like everything else. - **Categories fit the domain.** Manufacturing's 6M (Machine, Method, Material, Manpower, Measurement, Environment) and services' 6P (People, Process, Policy, Place, Procedures, Product) are starting points, not law. For the bakery: Orders, Prep, Packaging, Handoff, Courier, Customer-communication beats either canned set. Three to six categories; more dilutes. - **Rate the bones, then drill.** After the survey pass, mark each candidate: evidence for it (`[verified]`/`[assumed]`), and rough impact if true. Then take the 1–2 strongest bones into a Five Whys drill rather than "investigating everything" — the fishbone's job is aim, not answer. - **Cross-bone patterns matter.** The same underlying cause showing up on three bones (capacity strain appearing in Prep, Handoff, and Communication) is a strong root-cause signal. - **Borrow stakeholder lenses to widen the survey.** Before closing the candidate list, ask the user two or three perspective questions — "what would a customer say goes wrong?", "what would the courier point at first?" The lenses generate *questions for the user*, never AI-roleplayed answers: the user owns the facts; a lens only aims their attention at a bone they haven't looked down. ## Causal loops & system archetypes Reach for these when the problem's history says *feedback*: it returns after every fix, it oscillates seasonally without a seasonal cause, or each fix seems to make the next episode worse. Linear methods find a chain and stop; loops explain why the chain keeps re-arming. Map variables and influence arrows with the user, then look for loops: **reinforcing** (growth or decay compounding) and **balancing** (something resisting change toward a hidden limit). Three archetypes cover most real cases: - **Fixes that fail** — the quick fix relieves the symptom and quietly feeds the cause. Bakery: apologizing with discount codes for late orders → discounts drive more orders → more overload → more lateness. - **Shifting the burden** — the symptomatic fix erodes the capability for the real fix. Working until 2am to catch up prevents ever redesigning the prep schedule that causes the overload. - **Limits to growth** — a growth engine hits a balancing constraint; pushing the engine harder does nothing. More Instagram marketing can't outrun a solo-prep capacity ceiling — the leverage is the constraint, not the engine. The output is still a cause tree entry: the loop, stated in one or two sentences, with its links labeled — not a diagram for its own sake. If drawing helps the user, a small text sketch (`A → B → C → back to A`) is plenty; the family convention spends the drama budget on substance, not visuals. ## Add-on: force-field and constraint analysis Optional lenses, mainly for organizational-change problems: - **Force-field** — list driving forces (pushing the change forward) vs restraining forces (holding it back), with strength estimates from the user. The counter-intuitive move it exists to teach: *weakening a restraining force usually beats strengthening a driving force*, which just raises tension. - **Constraint identification** — Theory-of-Constraints style: find the bottleneck that caps the whole system's throughput. Its verification test is built in: *if you relieve the constraint and throughput doesn't move, it wasn't the constraint.* ## Rival hypotheses Diagnosis inherits medicine's differential rule: never walk into verification with only one candidate. A single-suspect cause tree is usually anchoring wearing a lab coat — the first plausible explanation (often the user's opening hunch) quietly absorbs all attention, and every check ends up designed to confirm it. - **Keep at least two rivals alive** until evidence separates them. If the tree has grown only one branch, ask "what else would produce exactly this Is/Is-Not pattern?" before testing anything. - **Prefer the separating test.** An observation that supports one rival *and* weakens the other is worth more than two confirmations. Bakery: "late only on custom cakes" separates prep-capacity from courier-degradation in a single look at the order log. - **Rivals die by evidence, not by vote.** When one wins, the loser stays in the assumption log at its new low confidence — cheap insurance for the day a pivot trigger fires and the diagnosis re-opens. ## Verification tests Every root-cause candidate leaves Diagnose with a test attached: 1. **Prediction** — "if this is the cause, we would expect to see ___." 2. **Cheapest disproof** — the least effort observation that could show the prediction false. Cheap matters: a test the user won't actually run protects nothing. Track them in `diagnosis.md` as a small table: | Candidate | If true, we'd see… | Cheapest check | Result | |---|---|---|---| | Prep-slot mis-estimate (A2) | customs averaging well over 30 min | time the next 5 custom preps | ⏳ pending | | Courier degradation (A1) | transit times up vs. spring | compare 10 old vs 10 recent handoff→delivery stamps | ✗ transit unchanged — **weakened** | A failed prediction is a *result*, recorded and celebrated — the courier hypothesis dying cheaply is the discipline doing its job (its log entry drops accordingly; see the assumption log). When a test needs real-world time, this is where the session pauses: set the check as homework, note the pause point in the workspace, and resume at re-entry. **The gate, restated:** Solve waits until the leading candidate is verified, or the user explicitly proceeds at-risk — in which case the solution work carries the unverified assumption's tag so nobody mistakes the foundation for stone. ## references/framing.md # Framing: intake, problem statement, Is/Is-Not Frame and Bound decide whether the rest of the pipeline diagnoses the real problem or a rumor about it. Time spent here is repaid threefold in Diagnose — and the running example below (a solo-run online bakery whose deliveries keep arriving late) carries through the other references, so the phases can be seen connecting. ## The intake One compact message, five questions: - What's happening, in observable terms? - When did it start, and how was it noticed? - Who or what is affected, and what is it costing? - What's already been tried? - What would "fixed" look like — how will we know? Ask them together — this is orientation, not interrogation — but keep it light: lead with the most load-bearing question (usually the observable symptom and its magnitude) and frame the rest as answer-what-you-can. Expect partial answers and don't push for completeness yet. "I don't know" is a legitimate answer that becomes a fact-gap worth writing down; some of the best early verification tasks are just filling intake gaps ("check what week the complaints actually started"). **When the opening message already carries a sharp signature, spend it immediately.** If the user arrives with a clean boundary contrast plus a coincident change — "late deliveries started the week I switched couriers, and only on cross-district orders" — they've handed over a discriminating test before the intake even ran. Propose one cheap check in the same reply, with both directions spelled out: "if the courier switch is the cause, cross-district handoff times should have jumped that week — pull three delivery timestamps from before and after; if they're flat, the courier lead is weakened and we look elsewhere." The remaining intake questions ride along in the same message. Deferring all test design to a later turn wastes the user's best evidence and reads as ceremony. Spending the signal doesn't mean spending the whole toolbox: keep that first reply light. One check with its if-true/if-false framing, the statement read back for confirmation, and the riding-along questions are plenty — the full Is/Is-Not table and the formal assumption-log block land better in the *next* turn, once the user has answered something and the artifacts have real content to hold. "What's already been tried" earns its slot twice over: failed fixes are evidence (each one weakens the hypothesis it targeted), and they reveal what the user already believes the cause is — a belief that goes straight into the assumption log, not into the statement. ## Problem statement refinement A good problem statement is **specific, observable, measurable where possible — and free of smuggled content**. Users almost always arrive with a statement that bundles three different things: - a **fact** (something observed), - a **hypothesis** (their guess at the cause), and - a **solution** (what they already want to do). The refinement move is to unbundle: the fact becomes the statement, the hypothesis is banked in the assumption log with a confidence level, and the solution goes to a parking lot for the Solve phase. Nothing is discarded — the user's guess is often right, and their solution often returns as an option. It just doesn't get to skip the queue. **Example 1 — smuggled cause:** - Before: "Deliveries are late because my courier service got worse." - After: "Over the last 6 weeks, a growing share of orders arrive after the promised delivery window." → assumption log: *"courier service is the cause" — user's belief, unverified.* **Example 2 — smuggled solution:** - Before: "I need a second delivery person." - After: "On weekend days, orders arrive late more often than I can personally manage responses to." → parking lot: *hire second deliverer* (an option for Solve, if diagnosis supports it). **Example 3 — too vague to diagnose:** - Before: "My shop is a mess lately." - After (through follow-ups): "Since early June, roughly 1 in 4 orders is delivered late, and two regulars have stopped ordering." Vague statements aren't rejected — they're interviewed until something observable emerges. "What would I see if I watched your shop for a day?" is a reliable un-vaguer. Numbers beat adjectives wherever the user has them ("1 in 4 orders" vs "a lot"), but don't stall the session demanding metrics the user doesn't track — "more often than before, exact rate unknown" is an honest, usable statement, and *unknown rate* becomes a measurement task. **Success criteria** come from "what would fixed look like", sharpened the same way: "late deliveries back under 1 in 20, sustained for a month" gives the Plan phase its metric for free. Capture them in `statement.md` next to the statement. **The gate:** read the refined statement back and get explicit confirmation before Bound. This is not ceremony — the user regularly corrects something important at this exact moment ("well, it's not *all* orders, only the custom cakes…"), and that correction is worth more before the cause tree exists than after. ## Is/Is-Not analysis Bound the confirmed problem by contrasting where it lives with where it doesn't. Four dimensions, two columns each: | | IS | IS NOT | |---|---|---| | **Where** | custom-cake orders; cross-district deliveries | standard-menu items; same-district | | **When** | since early June; Fri–Sun peaks | before June; weekday orders mostly fine | | **Who/what** | orders needing >30 min prep | pre-made stock items | | **What form** | late by 1–3 hours | never wrong item, never no-show | Fill it with the user — every cell is a fact about their world, so every cell is theirs to supply. Cells they can't fill are fact-gaps: mark them `?` and add the cheap ones to the verification list rather than guessing. **Reading the boundary.** The diagnostic gold is in the *differences* between columns. Ask, for each sharp contrast: *what's different about the IS side?* In the example: custom cakes differ from stock items in prep time, not in courier handling — which already weakens the user's courier hypothesis and points at capacity upstream of delivery. "What form it never takes" earns its keep too: *late but never no-show* means the pipeline completes, just slowly — a throughput problem, not a reliability one. Also note what changed at the time boundary: "since early June" begs the question *what else started in June?* (menu change? volume growth? new courier contract?). Changes coincident with onset are prime hypothesis material — labeled `[assumed]` until checked, like everything else. Two cautions: - **Is/Is-Not sharpens; it doesn't conclude.** The output is a set of boundary patterns feeding Diagnose, not a root cause. Resist the temptation to declare victory here — "it's the custom cakes!" is a *where*, not a *why*. - **Keep it proportional.** For a small problem, three or four filled rows are plenty. An exhaustive 20-cell grid on a minor issue is framework tourism. Write the table into `statement.md` under the statement, and carry the two or three sharpest boundary patterns forward into Diagnose by name. ## references/planning.md # Planning and session continuity A decision without a plan is a wish; a plan without pivot triggers is a wish with a Gantt chart. This phase turns the decision into committed actions — and builds in the admission that the diagnosis might still be wrong. ## Rollout strategy Pick with the user, based on cause-confidence and cost-of-being-wrong: - **Pilot** — the default whenever cause-confidence is below high, or reversal is expensive. A pilot is the *final verification test wearing work clothes*: small scope, fixed window, explicit success metric. Bakery: run the 48h pre-order window for custom cakes only, two weekends, target zero late customs. - **Phased** — confidence is high but the change touches many parts; sequence by risk, earliest phases carrying the most learning. - **Big-bang** — only when confidence is high *and* the change is cheap to reverse. Rare that both hold; say so if the user reaches for it out of impatience. ## The plan's parts Keep `plan.md` compact — five sections, most a few lines: 1. **Actions with owners.** Each action: smallest first step, who owns it, what unblocks it. For a solo user "owner" still matters — it distinguishes *my task* from *waiting on the courier company*. 2. **Success metrics — inherited, not invented.** Wire directly back to the success criteria captured in Frame ("late orders back under 1 in 20, sustained a month"). Inventing fresh metrics at plan time is a quiet way to move the goalposts onto easier ground. 3. **Pivot triggers.** Generate them with a quick **pre-mortem**: "it's three months from now and the fix failed — what killed it?" Each credible answer becomes a pivot trigger or a new assumption-log entry. Then, for each metric: *if it hasn't moved by checkpoint X, the diagnosis was wrong — return to Diagnose, starting from the surviving `[assumed]` links and the not-chosen options in decision.md.* Concrete: "if ≥2 custom orders are still late in pilot weekend two, capacity wasn't the (whole) cause — re-open the prep-start-time branch." A plan without pivot triggers assumes the diagnosis is infallible, which the assumption log says it isn't. 4. **Assumption validation plan.** Sweep `assumptions.md`: every still -open entry either gets a check scheduled inside the plan, or the user marks it an accepted risk — explicitly. No entry left silently dangling. 5. **Review point.** One named moment (end of pilot, day 30) where the user looks at metrics against triggers and decides: close, extend, or pivot. If the plan is growing into a real multi-week project — several workstreams, stakeholders, standing reviews — that's the **project-manager** handoff moment (family rule as usual: invoke if installed, otherwise name it, point to the family repo, and keep this plan as the lightweight version). ## Closing a phase, closing a problem When the plan is set, offer a two-minute lessons pass — not ceremony, three questions: what did the diagnosis reveal about the system that outlives this problem? which check gave the most information per effort? what would we check *first* next time? Append to `plan.md` under `## Lessons`. Skip it without guilt on small problems. A problem is *closed* at the review point when metrics hold — record that in `plan.md` too. Problems have a way of being declared solved at the moment of decision; the workspace stays honest about the difference. ## Re-entry protocol Problems outlast sessions by design — checks take days, pilots take weeks. On return: 1. **Read the workspace first** (`statement.md` → `diagnosis.md` → `assumptions.md` → whatever exists downstream). Don't ask the user to re-brief you on what the files already say. 2. **Restate the state in 2–3 lines**: which phase, what's pending, what the session is waiting on. "Last time: leading candidate A2 (prep-slot mis-estimate), you were going to time five preps over the weekend." 3. **Collect what reality answered.** Update assumption confidences, promote or demote tree labels, record verification-test results — *before* generating anything new. New evidence may reshuffle the leading candidate, and that's the system working. 4. **Continue from the phase the workspace says you're in.** Re-running Frame on a returning user wastes their trust; the gate they passed stays passed unless the new evidence broke it — if it did (the statement turned out mis-scoped), say so plainly and re-gate. The re-entry summary is also the moment to celebrate downward revisions from homework: an assumption that died over the weekend cost nothing and saved the plan. That framing — verification as progress, not delay — is what keeps users coming back to finish diagnoses instead of jumping to the nearest fix. ## references/solve-decide.md # Solve and Decide Diagnosis earns the right to generate solutions; this reference covers spending that right well — divergence aimed at the verified cause, then a decision the user makes with evidence in view. ## Entering Solve Take an energy checkpoint first. Diagnosis is mentally expensive, and solution generation done tired produces the first three obvious ideas and a shrug. Offer the break honestly — the workspace holds the state, and "resume tomorrow at Solve" is a fine outcome. Then set the target: solutions address **the verified root cause**, not the original complaint. The bakery's problem statement was "1 in 4 orders late"; its Solve prompt is *"prep capacity: custom cakes take ~50 minutes against 30-minute slots"* — a different, better question. ## The brainstorm-coach handoff Divergent ideation is brainstorm-coach's home turf — if it's available, invoke it rather than half-running it. Pass a clean brief: - **Topic** — the root cause, phrased generatively: not "prep capacity problem" but "how might a solo baker absorb 2× custom-cake demand without late orders?" - **Constraints** — from statement.md and the diagnosis (solo operation, no storefront, weekend peaks), plus success criteria. - **Seed ideas** — the parking lot from Frame (the user's original smuggled solutions, e.g. *hire a second deliverer*) enters as `(user)` ideas, first-class citizens of the session. - **The trace rule** — ask the session to note, per idea, which cause it addresses; ideas addressing none are welcome during divergence and get the symptom-patch label at converge (below). brainstorm-coach's converge output (Immediate / Future / Moonshots / Insights, user's top 3) flows back in as the option set for Decide. **If brainstorm-coach isn't installed:** say it exists in this family (github.com/tronghieu/agent-skills), then run a lightweight inline divergence — same user-first spirit, two or three rounds, not a firehose: 1. Invite the user's ideas first — including the parked ones — captured verbatim, tagged `(user)`. 2. Run 2–3 techniques suited to cause-directed ideation: **assumption busting** (list what the current setup takes for granted — "every cake is made after the order" — and flip each), **what-if scenarios** ("what if weekend customs required 48h pre-order?"), **resource constraints** ("what would you do if you could hire nobody and spend nothing?"). 3. Build on the user's ideas with labeled `(AI)` additions, 2–4 per round, then converge into a shortlist together. Never block the pipeline on the missing skill, and never let the fallback quietly become an AI idea-dump — the family's commit-first rule (user generates first, AI builds after, everything labeled) applies inline too. ## Trace discipline In `solutions.md`, every option names its target: ```markdown - Pre-order window for custom cakes (48h) — (user) → addresses A2 (prep-slot mis-estimate) by making demand schedulable - Batch-prep base layers on Thursdays — (AI) → addresses A2 by cutting per-cake marginal time - Discount code for late deliveries — (user, parked) → SYMPTOM PATCH: addresses customer anger, not lateness. Pair with a causal fix; see also the fixes-that-fail loop risk in diagnosis.md. ``` Symptom patches are legitimate — sometimes the bleeding must stop before the surgery — but they're *labeled*, paired with a causal fix, and never presented as the fix. An unlabeled symptom patch is how the same problem gets "solved" three times. ## Decide **Criteria come from the user.** Offer the usual suspects — effectiveness against the root cause, feasibility, cost, time, risk — then ask what actually matters here; a solo owner may rank "doesn't consume Sundays" above cost. Three to five criteria; more turns judgment into arithmetic. **Right-size the apparatus.** Two real options → a direct comparison in prose (strengths, weaknesses, the one deciding difference). Three or more distinct options → a decision matrix. Never build the matrix for show. **Every score cites evidence or confesses ignorance.** The rule that kills scoring theatre: | Option | Effectiveness | Feasibility | |---|---|---| | 48h pre-order window | high — directly converts the timed 50-min finding into schedulable slots | high — Instagram order form already supports it `[verified — user]` | | Hire weekend helper | high — adds capacity where the tree says it's short | `unknown — assumption`: no candidate identified, cost unknown → log A5 | Scores of `unknown — assumption` are honest entries, and they feed the assumption log — a decision made on three unknowns should *look* like one. **Recommend, then step back.** Give one recommendation with: the rationale in terms of the diagnosis, your confidence, and **what would change it** ("if the timed preps had come back at 35 minutes, the helper option would lead instead"). That last clause is the honesty mechanism — a recommendation that nothing could change wasn't reasoning, it was preference. **The gate: the user decides.** Record their decision and its rationale in `decision.md` — including where they diverged from your recommendation, without relitigating it. Options not chosen stay in the file with a one-line note on what would revive them; the pivot triggers in Plan may send the user back here.