# Clarify Decisions

> Use to interview or grill the user before building an underspecified plan, design, or feature idea, including when another skill calls for an interview. Produces a confirmed close package of decisions, constraints, success, boundaries, and spine touch — plus owned unknowns, accepted risks, and operability when the production-coverage gate is on.

- Skill: `jayden-dang/clarify-decisions` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add jayden-dang/clarify-decisions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jayden-dang/clarify-decisions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: jayden-dang (https://skillmd.com/u/jayden-dang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jayden-dang/clarify-decisions

---


# Clarify Decisions

This is a reusable **interview protocol**, not a pipeline stage. Nested under a parent, stay in its conversation and checklist; standalone, own the interview until shared understanding. Follow **Todos** for checklist ownership. Name and decide every silent assumption that could create debt or a wrong architecture. Leading words: **open set**, **territory**, **card**, **problem lock**, **criteria**, **coverage map**, **close package**. The map (prompts, plans, knowns) is not the territory (codebase, runtime, users, history).

## The Iron Law — channel

```
EVERY QUESTION IS INLINE CHAT WITH FULL CONTEXT.
NEVER use AskUserQuestion, structured MCQ pickers, or any harness UI that
truncates labels, option text, or the "why this matters" line.
```

A picker that strips consequences is a different interview. House style, authority, deadlines, and a nominally long description field are not exceptions.

## The Iron Law — open set (no fixed rounds)

```
THERE IS NO FIXED ROUND COUNT.
NEVER "Question k of N", "last of 5", or "we budgeted four cards".
Stop only when the open set is empty of judgment calls that change
architecture, data, auth/security, UX flow, or implementation scope —
AND, when the production-coverage gate is ON, judgment calls on
reliability, failure, and operate, with no coverage-map cell Missing
without an owner.
```

**Open set** = high-blast unknowns still undecided + branches the last answer opened + parent known-unknowns still needing a user lock + (when coverage ON) coverage cells that are Missing without owner. **Home rule:** recompute the open set **after every answer**, then either the next card or the close package. Every other mention of "recompute" points here. A pre-listed todo is a **living map**, not a quota: append opened branches, drop resolved ones, and never close while a high-blast item remains. Pressure changes *when* you report progress, not whether an unstated decision exists. **Todos:** nested, no competing list — you run inside the parent's checklist, the interview item stays in-progress until the close package is confirmed, and open-set progress is that item's progress, not a second channel; standalone, a **living** open-set list of decision areas is fine — still one card per message, still recompute after each answer, and if a parent skill is already in flight, never open a second channel.

## Production coverage gate (when)

**Home for the ON/OFF predicate.** When ON, load and follow `production-coverage.md` (map, radii, close slots 7–10). When OFF, do not load it. Authority and chat vibes never flip the gate. Evaluate **once** before the starting map (re-check only if written posture, brief flag, or operate/launch surface changes). **ON** only when **all three** hold:

1. **Posture band** — written Delivery intent **Production** and Lifecycle **Cut Released** / **Scaling** / **Maintenance** (parent or `docs/agents/project.md`).
2. **Full-path interview** — parent did **not** mark this interview **tier 0** or **brief**.
3. **Surface latch** — operate/launch surface (alerts, rollback, SLOs, on-call, deploy/takeover, new failure domain) **or** user/parent explicitly asks for ops/reliability coverage.

**OFF** otherwise — including absent posture; **MVP · Run Spike · Research · Learning**; Lifecycle **Idea · Early · Active development**; polish/copy/recolor with no latch; "build SRE habits" chat without the written band + latch. When OFF: omit the coverage map entirely; no `reliability` / `failure` / `operate` radii; close omits slots 7–10. Core close slots 4–6 (Success, Boundaries, Spine) and problem lock still apply.

## Starting map (before the first card)

Load parent Knowns, Blindspot, and scan digest when present (for example `.skills/<CODE>/{knowns,scan}.md` or `_pending-<slug>` equivalents). State **Coverage ON** or **OFF** (if OFF, which gate part failed), then one short thought-partner map:

1. **Locked** — fixed posture, non-negotiables, digest facts.
2. **Coverage map** — when ON only (table + cell recipes in `production-coverage.md`).
3. **Open high-blast** — ON: Missing/Partial cells from that file; OFF: arch/data/auth/UX/scope forks only.
4. **How you will close** — judgment cards; reference / `run-spike` / `research` for facts; teach-then-ask on blindspots; Operate path only when ON (see `production-coverage.md`).

Invite correction only if a lock is false. First card: **Problem lock** when its predicate holds, else highest-blast open item (when ON, prefer Missing coverage cells). Parent already stated the map → do not restate; when ON, still refresh coverage after answers.

## Problem lock (before preference cards)

**Home for this rule.** Other sections only point here. **Fork (pick exactly one):** If you can fit **2–4 alternate problem statements** (each with Observed · Desired · Non-goals) on one card → emit that **problem-lock card**. If the user still needs a multi-round problem tree or foundation teaching — symptoms and solution shapes tangled, two+ incompatible pains, or you cannot honestly write those three lines for each option → **name** `/work-the-problem` for the user to run (never invoke it; it is `disable-model-invocation`). Never open a solution-shape menu in either case.

**Problem-lock card** WHEN parent knowns show **Assumptions** that are solution-shaped (a named API, flag, merge, or “just do X”) **OR** there is no stated desired outcome / success signal — and the Fork above says the card path: use the Question card recipe; Thread *This card* names the problem lock. Body MUST lock all three on the chosen statement (options = alternate *problem statements*, not implementations):

- **Observed** — who hurts / what is true now
- **Desired** — observable result when done (not “it works”)
- **Non-goals** — deliberate outs

Closes: `known-unknown` (problem statement). Senior “skip philosophy / just pick API options”, standup clocks, and “don’t send me to another skill” do **not** waive this section.

## Question card (every turn)

Exactly **one** decision per message in chat. Every slot is **required**. Write for the person deciding now: use connected cause-and-effect sentences in their domain language. Preserve exact technical terms, service names, and boundaries; gloss them where used instead of replacing them with vague simplifications.

1. **Radius** — one of: `architecture` · `data` · `auth/security` · `UX flow` · `polish-diff` (label it). When Coverage ON, also `reliability` · `failure` · `operate` per `production-coverage.md`. When OFF, do not use those three.
2. **Thread** — three short lines the user can scan before the question:
   - *Locked so far* — 1–3 decisions already taken that constrain this fork (or "none yet").
   - *This card* — the single fork now.
   - *Still open after* — remaining high-blast **names** if this were answered (living open set — never "3 of 5").
3. **Territory** — grounded facts from the repo, digest, or parent knowns (paths, middleware, prior PRs, current behavior, landmines) — enough that the options make sense. When a blindspot blocks the choice, **teach here** (what it is, why it bites in *this* product) before the question. If you truly have no facts, say so; do not invent them. Never ask the user to recall what you can read.
4. **Question** — the decision in plain language.
5. **Why it matters** — **blast narrative** only: what rewrites if the answer flips (API shape, schema, auth boundary, ops surface). Enough to decide without a follow-up. Ground in *this* repo or product. Do not put pass/fail graders here — that is slot 7.
6. **Closes** — unknown class this card retires: `known-unknown` · `unknown-known` · `blindspot-confirm`.
7. **Criteria (graders)** — REQUIRED when Radius is `architecture` · `data` · `auth/security` · `UX flow`, or (Coverage ON) `reliability` · `failure` · `operate` (omit only for `polish-diff`): **1–2 named pass/fail graders** listed **above** Options (separate labeled block). Not the close-package Success / done signal. Recommendation MUST cite graders by name. Why sentences promoted here = miss. "No criteria essays / put success in Why" is not a waiver.
8. **Options (2–4)** — short title, then enough causal detail to judge it. On every radius except `polish-diff`, explain what it **gains**, what it **pays**, what can **break**, and when it is the **better fit**; labels are optional, connected sentences are not. On `polish-diff`, one consequence sentence per option is enough. Bare labels and telegraphic fragments are not options.
   **Shape** — REQUIRED inside every option when Radius is `architecture` or
   `data`: the caller-facing difference as it would be written — signature, type,
   column, route, or payload, ≤6 lines, no bodies. Prose naming an artifact is not
   a shape, and "same as option 1, but…" is not one: measured, a card that shaped
   only the option it recommended left the other two as titles to compare against.
9. **Recommendation** — your pick, first or clearly marked. On `polish-diff`, give one sentence grounded in Why. Every other radius gets a compact, checkable decision argument:
   - **Pick** — the option.
   - **Decisive factors** — the Territory facts and named Criteria that make it win now.
   - **Runner-up** — the strongest alternative and why it loses on a decisive factor.
   - **Accepted trade-off** — the real cost taken with the pick.
   - **Confidence / evidence gap** — how strongly the Territory supports the pick and what fact is still missing.
   - **Reopen trigger** — observable evidence or a constraint change that would make the runner-up better; “if requirements change” is not a trigger.
10. **Stop.** Wait. After the answer: recompute (Iron Law — open set home rule), then next card or close package.

Visible order: `Radius → Thread → Territory → Question → Why it matters → Closes → Criteria → Options → Recommendation → Stop`. Do not batch questions — the card is the detail. Before the first card or close package, load `example.md` when no parent supplies a confirmed exemplar or when the required output shape is uncertain. WHEN feature work involves neighbors, overlap, or reuse, also load and follow `feature-retrieval.md` before the first card — it owns package validity, refresh, and grounded-claim rules; otherwise do not load it.

## Order and coverage

- **Blast-radius first.** Prefer forks that change architecture, data, public API, auth/security, UX flow, or scope — even if the user opens on polish. When Coverage ON, also R/F/O per `production-coverage.md`.
- **Coverage order, branch order, and whose judgment counts.** Coverage order when ON: one home, `production-coverage.md` (Missing before Partial; R/F/O stop). Walk every branch in dependency order, sub-branches before trunk — stop is open-set empty. Judgment only to the user: facts live in Territory; only human locks become cards.
- **Right-size.** Follow **Production coverage gate**. OFF does not *force* migration / backward-compat / deprecation preference cards; ON presses those when the latch holds. Arch/data forks that happen to involve migration still get cards if they are open-set judgments. Posture and Team band are independent.
- **Compat obligation.** Read it from `docs/agents/project.md` **Project posture** — the written line, else derived from Lifecycle stage (Idea / Early / Active development → **None**; Cut Released / Scaling / Maintenance → **External**). On **None**, options and the Recommendation on an `architecture` or `data` card land **one shape** — the schema, endpoint, or type the project keeps — with nothing left behind beside it. Renaming the column, rewriting the committed migration, casting in a single forward migration, changing the endpoint, deleting the dead path: all in bounds, and which is cleanest is an engineering call. A parallel column, a sync trigger, a `v2` name, or a deprecation window offered on **None** buys compatibility with a consumer the posture says does not exist — a defect in the card, not caution. On **Internal** / **External** those costs are first-class and get weighed. Absent posture: no compat lens either way. Delivery intent sets the quality bar, never the compat answer.
- **Team band.** If `## Team` has a roster or Workflow band override, package from that section. Small/Multi may probe ownership; when Coverage ON, Accepted-risk / Owned-unknown owners still required (solo IC ok). Never invent a team; never hard-fail on missing Team.

## Pre-implementation interview map

Clarify Decisions owns the **interview** leg of pre-implementation unknowns work. Other legs are open-set *sources* or handoffs — not extra fixed rounds:

| Leg | Clarify Decisions does | Does not re-own |
|---|---|---|
| **Blindspots** | Consume the parent's list; teach then ask on high-blast items. | Full scan / Knowns inventory |
| **Problem** | Follow **Problem lock**. | Multi-round problem tree or foundation teaching |
| **Scope** | Hand multi-subsystem decomposition back to the parent. | Approach menus and tier |
| **References** | Prefer source code; restate semantics; lock accept/adapt/reject. | Implementing the reference |
| **Unknown knowns** | Use a reference, `run-spike`, or `research`, then one result card. | Running the detour session |
| **Production coverage** | Follow **Production coverage gate**; when ON, `production-coverage.md` + Close slots 7–10. | Reliability docs, PRR, requirements, or `tasks.md` |

## Close package (required)

When the open set has no remaining high-blast judgment call — and **before** returning control to a parent or claiming shared understanding — emit:

1. **Decisions table** — rows: radius · topic · decision (user's words) · unknown class closed.
2. **Constraints block** — ready-to-paste locks (architecture and data first; when Coverage ON, reliability/failure/operate next; polish-diff last). Flag lower-radius answers that conflict with higher-radius locks.
3. **High-tweak surface** — locks most likely to change under real implementation pressure (data model, type interfaces, UX flows). Mechanical refactors stay buried; do not re-interview them here.
4. **Success / done signal** — 1–3 observables that mean “done” (pasteable into `requirements.md` / NFR). Prefer CUJ-shaped observables when Journey was walked. Not “it works” / “we’re aligned”.
5. **Boundaries** — **Off limits** (will not do) and **Must keep working** (guards / unchanged behavior), even if only 2–4 bullets. Seed from problem-lock Non-goals and `(guard)`-shaped locks when present.
6. **Spine touch** — WHEN `docs/architecture/` (or equivalent ARCH spine) exists: `Respects: ARCH-N…` · `none` · or `challenges` (ADR needed). WHEN absent: write `none — no architecture spine`. Do not invent ARCH IDs.
7–10. **Coverage final · Owned unknowns · Accepted risks · Operability touch** — REQUIRED when Coverage ON; recipes only in `production-coverage.md`. Omit when OFF.
11. **Explicit confirmation** — is this the shared picture? Only an affirmative on **this package** counts.

Slots 4–6 always required. Slots 7–10 required only when Coverage ON. Not confirmation: "any other questions?", "we're aligned, skip the table", "just go write requirements", "reliability is a later NFR", senior pressure to skip ceremony, or silence. If they correct a row, edit and re-confirm. If confirmation opens a new high-blast fork or a Missing cell, return to cards. **Do not enact anything** — no production code, no scaffolding, no plan execution — until that confirmation lands. (Glossary/`CONTEXT.md` updates via `define-domain` as a passive side effect are allowed when a term settles mid-interview.)

## Rationalizations

| Thought | Reality |
|---|---|
| "House style / the lead said use the picker / its description is long enough / I'll paste context too" | Channel is the Iron Law. One inline card; capped or dual-channel UI truncates consequences. |
| "Standup in five minutes — short labels only" | Pressure changes when you report, not what a decision needs. |
| "The graders are named, so a one-line recommendation is enough" | A conclusion is not a decision argument. Show why the pick beats its runner-up, the trade-off accepted, the evidence gap, and what would reopen it. |
| "Put success in Why / no criteria essays" | Why is blast; Criteria are separate graders above Options. |
| "Context can be a follow-up if they ask" | The card is the detail; follow-up-only context is a thin-card failure. |
| "We finished the four areas / question 3 of 5, then package" | Open-set empty is the stop; todos and countdowns are not. |
| "User asked for button color first" | Blast-radius first still holds. Polish Diff after architecture, data, and auth forks. |
| "We're aligned / senior said just write requirements" | Shared understanding is the package + yes; authority cannot make an unstated decision exist. |
| "I'll assume the safe default and mark done" | Assumptions are not decisions. One card; wait. |
| "Just pick industry best practice" | Load the Territory reference; restate and lock it. |
| "Park the parent / open a short clarify-decisions checklist" | Nesting is the clean switch. Decision areas stay inside the parent's in-progress interview item. |
| "Announce Using clarify-decisions for the hand-off" | Nested: no mode-switch announcement. Standalone may name the skill once. |
| "Parent already loaded neighbors — re-run every card for freshness" | Reuse the valid package; rederive only when fingerprints/seeds/scope change |
| "Standalone interview — skip load-subgraph, Territory is enough" | Feature work: load once before the first card |
| "They named the cheap path / senior said skip philosophy and pick API options" | Solution-shaped assumptions are not locks. Follow **Problem lock**, regardless of time or authority. |
| "Criteria live in requirements later" | Recommendation cites card graders; later specs do not replace them. |
| "Success / Boundaries / Spine belong downstream" | Close slots 4–6 are required here. |
| "Don't send me elsewhere; give three merge architectures / naming the skill is invoking it" | Follow the **Problem lock** Fork. Name `/work-the-problem` for the user; never auto-invoke it or show solution menus while the problem is open. |
| "Production intent means treat every schema change as if users were on it" | Delivery intent is the quality bar; **Compat obligation** names who is committed. On None the clean in-place rewrite *is* the Production answer. |
| "Nothing in the repo confirms that migration never ran somewhere real — stay additive to be safe" | Compat obligation None is that confirmation, written. Defaulting against it re-asks a fact the posture already answered. |
| "Additive is bounded debt — one follow-up migration retires the old column" | The follow-up *is* the debt, and on None there is nothing to retire from. Ship one shape. |
| "Active development / Cut Released is ambiguous — assume something is deployed" | Lifecycle is not a deployment probe. Read Compat obligation; the derivation covers the absent line. |
| "Reliability is later / architecture is done / standup, skip the map" | When Coverage ON, Missing cells stay open; later templates do not replace `production-coverage.md`. |
| "TBD is fine — Open Questions will catch it" / "no reliability.md — skip cell" / "Accepted-risk without signer" | When ON: unowned TBD blocks close; prose or Owned unknown still required; signer required (solo IC ok). No invented SLO-N. |
| "Absent/MVP/Early = Production coverage" / "every Prod interview gets the map" / "build habits" / "failure-domain feel without band" | ON needs **all three** gate parts. Absent, MVP, Early, polish without latch, and chat stay OFF. |
| "Parent tier-0 brief still needs full coverage" | Brief / tier-0 fails part 2 (full-path) ⇒ OFF. |
| "OFF — keep a partial coverage map anyway" | OFF omits the map entirely. Core close is slots 4–6 + problem lock. |
| "OFF — skip any arch/data card that smells like migration" | OFF skips forced migration/compat *preference* ceremony; open-set arch/data judgments still get cards. |
| "Put TBD and accepted risk in one bucket" / "Journey has no radius — skip cell" | When ON: three distinct close slots; Journey via `UX flow` / `architecture` CUJ — see `production-coverage.md`. |

## Red flags — stop and rewrite the turn

- Calling `AskUserQuestion` or any truncated MCQ tool for a clarify-decisions decision
- More than one question mark aimed at the user in a single message (except clarifying examples inside option text)
- A card missing Thread, Territory, Why, Closes, option consequences, or the
  high-blast Criteria block and checkable Recommendation argument
- Any preference or solution menu while **Problem lock** applies, without its
  card or naming `/work-the-problem`
- "Question k of N", "final round", or closing because a precommitted count finished while high-blast remains
- Leading with polish-diff while architecture / data / auth (or, when Coverage ON, reliability / failure / operate) branches remain open
- Closing with "any other questions?" instead of the decisions package
- Close package missing Success / done signal, Boundaries, or Spine touch
- Coverage ON without `production-coverage.md` / map, or close with Missing/unowned cell or “later NFR”
- Coverage ON close missing slots 7–10; or Coverage ON when any gate part fails (absent, MVP/Early, brief, polish without latch)
- Coverage OFF yet emitting R/F/O cards or close slots 7–10
- Offering a `v2` name, a parallel column, a sync trigger, or a deprecation window on a **Compat obligation None** repo
- Handing back to the parent or starting requirements without an explicit yes on the package
- Asking the user for a fact already present in the repo or parent scan
- Abstract taste cards for an unknown-known when a reference or run-spike path exists
- Nested re-derive every card while the parent package fingerprints still match
- Standalone feature interview with no retrieval before the first card
- Auto-invoking `/work-the-problem` instead of naming it for the user
- Inventing greppable SLO-N / TB-N / THR-N IDs without Approved doc definitions
- Treating chat “build SRE habits” as Coverage ON without the written gate
- Merging Owned unknowns into Accepted risks (or either into Operability touch)
- Leaving Journey Missing (when ON) with no `UX flow` / `architecture` CUJ card
- Calling `assess-observability` for every Operate hole (only telemetry/tracing readiness gaps)