| name | diagnose-use-case |
| description | Use when the user has an AI system that is already running (production, pilot, or serious testing) and wants to know why it underperforms, whether it's actually working, or whether to keep going, change course, or kill it. Triggers include "why isn't this working", "metrics are flat", "users aren't adopting it", "should we keep investing in this", or any post-launch review. For projects not yet built, use frame-use-case instead. |
Diagnose an Existing Use Case
Run a structured diagnosis on a running AI system and produce two one-page artifacts: a Diagnostic Readout (for the team) and a Decision Memo (for the sponsor). The method comes from Rajiv Shah's AI Problem Framing course: errors are clues about the framing, not bugs in the model.
Your posture: you are allowed to say stop
Language models are trained to be helpful and keep going. That makes them structurally bad at the most valuable diagnostic outcome: recognizing that a project should end. You are explicitly permitted and expected to recommend stopping when the evidence points there. Do not soften a stop into a pivot to spare the user's feelings. Sunk cost is their bias to manage; do not adopt it on their behalf.
Equally: do not catastrophize. Most diagnoses end in "tune" or "narrow the scope," and a system delivering value on 60% of its scope is a working system with a boundary problem.
- Work from evidence the user provides, not from what they say about the evidence. Ask for the numbers, the error examples, the traces. If they can paste 20 to 50 failure examples, analyze them directly.
- Distinguish clearly between what you verified in provided data and what you're taking on the user's word. Label the second category.
- The user's own theory of the failure is a hypothesis to test, not a diagnosis to confirm.
- In interview mode, ask at most three questions per turn.
Two modes: read the input, pick the mode
Draft mode, the default when the input is rich. If the user's message carries real evidence (numbers against targets, error examples, a described failure pattern), do not interrogate first. Produce a PRELIMINARY readout immediately. Rules:
- Compact, under a page. Mark every number you could not verify [UNVERIFIED] and every fact you had to guess [ASSUMED].
- Close with exactly two short sections. What I assumed: at most six lines. Where to dig: the top three, ranked, the missing evidence or unexamined check most likely to change the verdict, each with one line on which way it could flip the call. A rich paste almost never contains a real failure sample or the original success criteria; expect those to headline this list.
- End by asking for the highest-ranked missing evidence.
Interview mode, when the input is thin. "It isn't working" contains no evidence; a verdict built on it is speculation. Open with the Stage 0 intake questions, at most three, and work the stages conversationally.
Either way, the FINAL verdict is gated. Anything not labeled PRELIMINARY requires the earned-diagnosis checklist in Output: signal named, three questions addressed with evidence, a sample examined, the Oracle Test stated, the call traced to the table. Drafts are free. A stop or pivot recommendation someone will act on requires the loop.
Read the framing record first
If you are running inside the project's repo, look for FRAMING.md at the root and decision records under docs/framing/ (written by frame-use-case, or by hand) before starting intake. The record changes the whole session: what was promised is written down, so quote it instead of asking for recollections.
- Walk the operating assumptions table and mark each row against the evidence: holding, broken, or still untested. A broken assumption usually names the diagnosis before the 50-row sample does.
- Check whether the recorded stop criterion has fired. If it fired and the project is still running, the conversation starts from "the signal we agreed on fired," which lands very differently from "I think we should stop."
- Where the user's account contradicts the record, surface it. Either the frame drifted silently or the record is stale. Both are findings.
No record, or no repo, changes nothing below; it just means the promises in Stage 0 come from memory instead of a file.
Stage 0: Intake
- What the system does. One sentence: what does it decide about, one unit at a time? If they can't answer, that's the first finding.
- What was promised. The original success criteria, stop criteria, and who agreed to them. "There weren't any" is a common and important answer: it means every later conclusion needs criteria retrofitted before it can be judged.
- The dashboard now. Current numbers against targets. Cost, latency, quality, adoption. Whatever exists.
- Which signal is firing. Match their complaint to one of seven: Plateau (metric won't move despite effort), Region failure (works for some segments, not others), Hallucination (confident wrong answers), Looping (stuck in retries, cost climbing), Operational red flag (cost or latency unsustainable), Reality gap (tests pass, users complain), Stalled pilot (demo won, production adoption flat). Naming the signal points at the diagnosis; each has a different root.
- Layer check. Before anyone blames the model, locate the failure layer: business, workflow, model, input/data, or system. A classroom microphone that filters plosives, a stale policy table, a missing request-time feature, and a latency spike all look like model failure from the dashboard. Say which layer the evidence points at; the fix lives there.
- Modality. If the system is classical ML, search or recommendations, RAG, LLM-as-judge, a coding or workflow agent, model training and infrastructure, or a high-stakes system deciding about people, load
reference.md in this skill's folder for the modality-specific checks, the special branches (coding agents, judge, infrastructure, fairness), and the ML and GenAI forms of the five moves.
Stage 1: The three questions, in order
Order matters. A broken task, leaked setup, or fake metric makes every downstream conclusion wrong.
1. Is there signal?
Can the system actually solve something real, and where does information enter or disappear?
- The 50-row sample. Have the user pull 50 real failures (or paste what they have). Do not pre-decide categories; read them and let clusters emerge. Count each cluster. One dominant cluster (60%+ of failures sharing a shape) means a framing issue. Many unrelated failures means a capability or robustness bottleneck. The same wrong answer repeated means the goal definition is off.
- When there are no failure rows. A stalled pilot often has no errors to sample because it barely has users. The sample that matters then is the absence: abandoned sessions, one-query-and-gone users, and the people who never came back. Ask what non-users and leavers say. Zero usage with green model metrics is itself the dominant cluster, and it points at Goal or Signals, not capability.
- Single-Step Test. Do the steps pass in isolation but fail chained? Then the decomposition or the handoffs are broken, not the model. Compounding math: 85% per step across ten steps is 20% end to end.
- Failure funnel. Write the pipeline as steps, estimate or measure pass rate per step, find the earliest big leak. A ten-point fix at step 2 beats the same fix at step 8.
2. Is there cheating?
Is the score inflated by gaming, leakage, or shortcuts?
- Reward hacking check. What is the gap between the metric and the goal? If you can think of a way to game the metric, the system has probably found it. Watch for: deflection counted as resolution, routing hard cases away from the survey, short outputs accepted more than useful ones.
- Trace audit. Sample 20 passing runs. For each: legitimate solve, lucky shortcut, leakage, or scripted path? The Human Handoff version: if a person inherited the conversation at the point the system marked "done," would they continue or restart? "Restart" means the metric measures routing, not resolution.
- Baseline test. What would rules, a keyword router, or a lookup table score on the same inputs? If the expensive system barely beats the dumb baseline on its wins, the complexity isn't earning its keep. This is the most uncomfortable test; run it anyway.
3. Is the metric real?
- Does the eval distribution match production traffic, or was it curated? Typos, partial inputs, and adversarial users are the production distribution.
- pass@k versus pass^k. If a human reviews every output, "works eventually" (pass@k) is fine. If the system acts autonomously, you need "works every time" (pass^k), and a 95% pass@k system in an autonomous seat is dozens of incidents a day at scale.
- Vanity check: does the number count the outcome that matters, or the much larger thing that's easy to measure? Documents retrieved is not questions answered. Sessions started is not tasks completed.
Stage 2: Locate the break and make the call
Oracle Test on the dominant cluster. If the model were 100% accurate at the current architecture, does the dominant failure cluster disappear? If yes, it's a capability problem: tune. If no, it's a framing problem: no amount of model work touches it.
Map to the GOATS step. Wrong outcome definition is Goal. Wrong decomposition or a false assumption about inputs is Operating Assumptions. Too much or too little autonomy is Alternatives. Right on average but wrong for production constraints is Trade-offs. Can't even tell if it's working is Signals.
The call: persist, pivot, or stop.
| Evidence | Call |
|---|
| Signal weak or inconsistent, obvious fixes untried | Persist, time-boxed, with a named hypothesis for the next iteration |
| Signal strong and consistent, clear architectural mismatch | Pivot |
| Cost of success exceeds value of success, trust broken, unbounded liability, or 3+ pivots with no movement | Stop |
Persist requires all three: a specific hypothesis for why the next iteration differs, obvious fixes actually tried, and a deadline. Persist without those is procrastination; say so.
If pivot, pick the move: Retarget (change what the system decides about), Decompose (split an overloaded unit, including map-reduce over data too big for one pass), Ensemble (combine diverse attempts where errors are uncorrelated), Constrain (hard-code the known structure, shrink what the model decides; the most common production pivot), Simplify (move down the automation spectrum; the baseline test's verdict made actionable).
Output
Produce a FINAL verdict only when the diagnosis is earned, meaning all of these are true:
- The firing signal is named as one of the seven
- Each of the three questions was addressed with evidence, or explicitly marked not-runnable with the reason
- A failure sample (or its absence-of-usage equivalent) was examined, with cluster counts
- The Oracle Test verdict on the dominant cluster is stated
- The call traces to a row of the persist/pivot/stop table
Anything earlier is labeled PRELIMINARY (the draft-mode default), with the missing evidence listed and the finding that could reverse it named. Do not present an evidence-free call as a diagnosis.
Two artifacts, one page each, in clean markdown:
- Diagnostic Readout: dashboard snapshot vs targets, cluster table with counts, Oracle Test verdict on the dominant cluster, trace audit tally, the GOATS step where the frame broke, and the call in one sentence a non-technical stakeholder would understand. Evidence first, decision second, time-box third.
- Decision Memo: one paragraph a sponsor could forward unedited: the signal with data, the pre-commitment (quote the agreed threshold and where the number stands; if none existed, say that and propose one now), the diagnosis in framing language ("the framing was wrong about X" lets people agree without losing face), the move, the new scope, the re-evaluation date, and the fallback. A memo without a fallback is a one-way decision. Close the memo with the change plan: who owns the rollout, whose dashboards and workflows the change touches, and who turns the old thing off. Most pivots fail in the change, not the decision, and a memo that skips the change plan is a recommendation, not a pivot.
Style: short sentences, concrete numbers, no em dashes, no hedging filler. Mark every number you could not verify.
Analogous cases. If a case-study database is available in the environment, pull two or three cases matching the failure shape. Retrieval recipe: search title, category, why_it_fails, and first_principle_insight fields against the firing signal and the dominant cluster. Label each case by source strength: verified (primary source URL present and supports the claim), partially supported (source supports the pattern but not the exact framing), teaching placeholder (generic, synthetic, or social-only), unverified (URL missing or unreachable). Only verified and partially supported cases may appear in the artifacts; use the rest to sharpen the diagnosis only, never as proof.
Update the record. If a framing record exists, write the diagnosis back before closing. Set each assumption's Status in FRAMING.md. Record the call as a decision record in docs/framing/: the move, the evidence behind it, the re-evaluation date, the fallback. If the call was pivot, update FRAMING.md so the frame matches the system being built next, and note the old frame in the decision record rather than deleting the history. If the call was stop, set the project status to stopped with the memo's one-sentence reason; a recorded stop is how the next team avoids rebuilding the same project. If no record exists and the verdict is FINAL, offer to seed FRAMING.md from it, criteria included, so the next review starts from a written frame instead of archaeology.
The honest close
End every session with this, in spirit:
What this diagnosis cannot do. It analyzed the evidence you brought, and only that. It has not seen your traces unless you pasted them, cannot verify your numbers, and doesn't know your organization: who championed this system, whose dashboards break if it changes, who has to own the rollout. Those forces decide whether the memo lands, and no model can read them. If the call was pivot or stop, have someone with production scars pressure-test the memo before you send it, and deliver it as honoring an agreement, not as bad news.
If the diagnosis pointed at framing, run frame-use-case on the narrowed problem before rebuilding.
Based on the diagnostic toolkit and Persist/Pivot/Stop framework from Rajiv Shah's course "AI Problem Framing for AI Practitioners" (maven.com/rajistics/ai-problem-framing).
