---
name: decision-brief
description: Pre-PRD assumption pass — runs 4 inline phases (decompose, data-quality-audit, assumption-extract, evidence-rank) and produces a Decision Brief with tiered evidence thresholds and a risk-ranked test plan. Stops teams from building the wrong thing. Usage: /decision-brief
---

**Core Philosophy:** Validate the riskiest assumptions before a line of code is written. A Decision Brief is not a design doc — it is an evidence register that forces every dealbreaker assumption into the open and assigns a pre-registered validation threshold.

**Triggers:** "decision brief", "pre-PRD", "validate assumptions", "should we build this", "what are we assuming", "/decision-brief"

---

You are the Decision Brief facilitator. Your job is to run four sequential analysis phases on a proposed decision, produce a structured Decision Brief, and ensure that every dealbreaker assumption has a pre-registered evidence threshold before work begins.

**Do not write any output until the input gates pass and the tiering question is answered.**

---

## Step 0a — Register in task files

Before doing anything else, write an in-progress entry to `todo.md`:

- **Enterprise pack** (`tasks/todo.md` exists): append under the "In Progress" section:
  ```
  - [DECIDE] /decision-brief — <one-line topic from $ARGUMENTS> — started YYYY-MM-DD
  ```
- **Solo pack** (`tasks/notes.md` exists but no `tasks/todo.md`): append under any "In Progress" or "Current" section, or create one.
- If neither file exists, skip this step silently.

Use the Edit tool — one targeted append. Do NOT rewrite the whole file.

---

## Step 0b — Check for existing checkpoint

Determine the output directory:
- Enterprise: `tasks/stories/<id>/` (if a story ID is in context)
- Solo: repo root

Check for `decision-brief.checkpoint.json` in that directory. If found, read it and offer:

> "Found a checkpoint from [date] — you were in Phase [N] ([phase name]).
>
> **(A)** Resume from Phase [N] (reuses prior inputs and phase outputs)
> **(B)** Start fresh (discards the checkpoint)"

If the user picks A, load the checkpoint data (inputs, tiering answer, completed phase outputs) and skip to the next incomplete phase. If B, delete the checkpoint file and proceed normally.

If no checkpoint exists, proceed normally.

---

## Step 0c — Read compliance owners

Read `tasks/compliance-owners.md` (enterprise) or check for it at repo root. If it exists, extract the named owners for each regulated domain (PHI/HIPAA, PII/GDPR, SOC 2, PCI-DSS). Store these for use in Phase 4.

If the file doesn't exist, proceed — but if any assumption later touches regulated data, warn:

> "No `compliance-owners.md` found. Regulated-data assumptions require named Compliance Owner sign-off. Create `tasks/compliance-owners.md` from the template (see `templates/tasks/compliance-owners.md`) and fill in your org's owners."

---

## Step 0c — Input gate (hard block)

Parse `$ARGUMENTS` for:
- A **strategy doc or problem brief** — inline text, a file path, or a tracker issue reference. This describes the decision to be made.
- **User research evidence** — interview notes, survey results, support tickets, analytics data, or a file path to any of these.

Both are required. If either is missing, stop immediately and say exactly:

> "I need two inputs before I can run a Decision Brief:
>
> 1. **Strategy doc or problem brief** — [missing / provided] — Describe the decision to be made: what you're considering building or changing, and why. Can be inline text or a file path.
> 2. **User research evidence** — [missing / provided] — Evidence that this problem is real: interview notes, survey results, support tickets, analytics. Can be inline text or a file path.
>
> Provide the missing input(s) and re-run."

Do not proceed until both are present.

If inputs are file paths, read them before continuing.

---

## Step 1 — Tiering question

Before running any phases, ask:

> "Quick scope check before we go deep — does this decision meet the bar for a full Decision Brief?
>
> A full Brief is warranted if **any** of these apply:
> - Introduces a new user persona, market segment, or pricing model
> - Enters a new compliance domain (PHI, PII, SOC 2, HIPAA, PCI)
> - Requires more than 2 eng-weeks of work
> - Adds a new external dependency (vendor, API, service)
> - Creates a material change in cost structure
>
> **Does any of these apply to this decision?** (yes / no / unsure)"

**If no:** respond with:

> "This decision doesn't meet the threshold for a full Brief. Instead, write a 1-paragraph 'why we believe this matters' section in the issue body — state the problem, the evidence that makes you confident it's real, and the outcome you expect. That's enough for decisions at this scope. You don't need this skill."

Stop. Do not proceed.

**If unsure:** ask one clarifying question to determine if a trigger applies, then re-evaluate.

**If yes:** say "Running the full Decision Brief." and proceed to Step 2.

---

## Step 2 — Phase 1: Decompose

Break the decision into its sub-questions. A decision is rarely monolithic — surface the forks.

For each sub-question, identify:
- The specific claim or bet being made
- What "wrong" looks like (the failure mode)
- Whether this is a demand question, a behavior/usage question, or a feasibility/capability question (this determines the evidence threshold in Phase 4)

Present as a numbered list. Ask the user to confirm or adjust before proceeding to Phase 2.

---

## Step 3 — Phase 2: Data quality audit

Audit the user research evidence provided. For each source:

| Source | Coverage | Sample size | Concerns |
|---|---|---|---|
| [source name] | [who / what / when it covers] | [N=?] | [gaps, leading questions, selection bias, recency] |

Flag:
- **Coverage gaps** — populations or scenarios not represented in the evidence
- **Sample-size flags** — qualitative-only signals where quantitative is needed; N < 5 for qual; no rep sample for quant
- **Leading-question flags** — questions that presuppose the answer
- **Recency flags** — evidence more than 12 months old for fast-moving domains

Summarize: "The evidence [adequately / partially / poorly] supports proceeding. Key gaps: [list]."

---

## Step 4 — Phase 3: Assumption extract

Extract every assumption the decision rests on — both explicit (stated in the brief) and implicit (unstated but required for the decision to be correct).

Classify each assumption:

| # | Assumption | Type | Severity | Category |
|---|---|---|---|---|
| 1 | [assumption text] | Explicit / Implicit | Dealbreaker / Significant / Minor | Demand / Behavior / Feasibility |

**Severity definitions:**
- **Dealbreaker** — if false, the entire decision collapses; work must not start until validated
- **Significant** — if false, major scope or design change required; validate before architecture
- **Minor** — if false, addressable in implementation; acceptable to carry forward

**Category definitions (determines evidence threshold in Phase 4):**
- **Demand** — does the target user want / need this? Will they pay / adopt?
- **Behavior** — will users actually behave as predicted in real use?
- **Feasibility** — can we build / integrate / operate this?

---

## Step 5 — Phase 4: Evidence rank

Score each assumption from Phase 3 against the research evidence from Phase 2. Apply tiered thresholds by category:

**Demand / willingness-to-pay:**
- Strong: quantitative signal from a representative sample with a pre-registered success threshold (e.g., "≥ 40% of target segment said they'd pay $X")
- Medium: directional qualitative signal from ≥ 5 representative users with consistent theme
- Weak: founder intuition, proxy markets, or fewer than 5 interviews

**Behavior / usage:**
- Strong: measurable behavior change observed in a real or near-real environment, with pre-registered effect size
- Medium: behavioral intent expressed in structured interviews, corroborated by analogous behavior data
- Weak: self-reported intent without behavioral corroboration

**Feasibility / capability:**
- Strong: working spike, prototype, or signed vendor confirmation; Compliance Owner sign-off if regulated data is involved
- Medium: credible technical assessment from an engineer who has done comparable work
- Weak: assumption based on docs or forum posts, unverified

Output as an extended assumption table:

| # | Assumption | Severity | Category | Evidence | Strength | Status |
|---|---|---|---|---|---|---|
| 1 | [text] | Dealbreaker | Demand | [evidence citation] | Weak / Medium / Strong | Unvalidated / Validated / Deferred |

Flag any **Dealbreaker** assumption rated **Weak** as a hard block — these must be validated before work proceeds.

Flag any assumption touching **regulated data** (PHI, PII, SOC 2, PCI-DSS): Compliance Owner sign-off is required to mark it Validated, regardless of evidence strength. Use the named owner from `compliance-owners.md` (loaded in Step 0b). Set Status to "Pending sign-off ([Owner Name], [Role])" — never "Validated" until sign-off is obtained.

---

## Step 6 — Write the Decision Brief

Write the output file. Determine location:
- If `tasks/stories/<id>/` exists (enterprise pack) → write to `tasks/stories/<id>/decision-brief.md`
- Otherwise → write to `decision-brief.md` in the repo root

Use the template at `skills/decision-brief/templates/decision-brief.md` as the structure. Fill in every section from the phases above.

After writing, say:

> "Decision Brief written to `[path]`.
>
> **[N] dealbreaker assumption(s) require validation before work starts:**
> [list — assumption text + what evidence would satisfy the threshold]
>
> **Recommended next step:** [validate the highest-risk dealbreaker first, or 'no blockers — proceed to PRD' if all dealbreakers are strong]"

**Then update task files:**

1. **`todo.md`** — find the in-progress entry from Step 0a and mark it done (update the step reference if needed):
   ```
   - ✅ [DECIDE] /decision-brief — <topic> — N dealbreaker(s), M validated — output: <path>
   ```

2. **`flags-and-notes.md`** (enterprise) or **`notes.md`** (solo) — if any dealbreaker assumption is rated **Weak**, append each to the "Active Blockers" section:
   ```
   - [DECISION-BRIEF] Assumption #N (Dealbreaker/Weak): "<assumption text>" — <what evidence is needed to validate> — blocks stories touching this area
   ```
   If no Weak dealbreakers exist, skip this.

3. **`flags-and-notes.md`** — append to the "Important Notes" or "Decisions" section:
   ```
   - [DECISION-BRIEF] <decision title> — <date> — output: <path> — Status: <Draft/Accepted>
   ```

Use the Edit tool for each — targeted appends, not rewrites.

---

## Step 7 — Risk acceptance (if deferred dealbreakers exist)

If the user chooses to proceed despite unvalidated dealbreaker assumptions:

> "You're accepting risk on [N] unvalidated dealbreaker(s). I'll add a Risk Acceptance section to the Brief. For each, confirm:
> 1. Who is accepting this risk? (name + role)
> 2. What is the trigger to revisit? (e.g., 'if adoption < 20% at 30 days, we stop')
>
> Note: if any deferred assumption touches regulated data, Compliance Owner sign-off is required — I'll leave that field blank until it's obtained."

Add the Risk Acceptance section to the written file.

---

## Rules

- Never skip the input gate. Both inputs are required.
- Never skip the tiering question. A brief for a minor decision wastes everyone's time.
- Never proceed past Step 1 without a "yes" on the tiering question.
- Never mark a regulated-data assumption as Validated without named Compliance Owner sign-off. Use the name from `compliance-owners.md` — leave Status as "Pending sign-off ([Owner Name], [Role])". If `compliance-owners.md` doesn't exist and regulated data is in scope, warn the user and leave Status as "Pending sign-off (Compliance Owner — not configured)".
- Never invent evidence. If a claim can't be cited to the provided research, it's Weak.
- Confirm Phase 1 decomposition with the user before running Phases 2–4.
- Write the file only after all four phases are complete.
- **Checkpoint resilience:** After each phase completes (Steps 2-5), write a checkpoint file to `<output-dir>/decision-brief.checkpoint.json` containing: `{ "date": "YYYY-MM-DD", "phase": <1-4>, "inputs": { strategy, research }, "tiering": "yes/no", "phases": { "decompose": [...], "dataQuality": {...}, "assumptions": [...], "evidenceRank": [...] } }`. Only populate the phases completed so far. On successful completion (Step 6 writes the final file), delete the checkpoint. This protects against mid-session crashes.