Problem Clarity Check

A premise-and-definition guardrail. Before a problem statement becomes a PRD, spec, or line of code, this skill tests whether it's a genuine, validated user pain point — or a solution wearing a problem statement's clothes.

When to run this

Run proactively, before starting to write a PRD, spec, or feature doc, whenever the underlying problem hasn't already been validated in this conversation. Do not run it for casual code requests, bug fixes, or small technical tasks — those proceed normally.

Also do not run it for documents that explain or justify a decision that's already been made (e.g. "write a doc explaining why we're deprecating X in favor of Y," where the deprecation is stated as settled, not proposed). This skill checks premises before a decision is locked in — it's not a retroactive audit of decisions already made, and re-litigating settled decisions when someone just wants an explainer written isn't helpful. If it's ambiguous whether a decision is settled or still being proposed, ask.

If the user explicitly asks for a clarity check, diagnostic, or premise stress-test, run it regardless of context.

If a problem has already passed this check earlier in the conversation, don't re-run it from scratch for follow-up requests on the same problem — only re-check if the problem statement materially changes.

Scope check before running the criteria: this skill is built for problems framed around user pain points. Before applying the six criteria, check whether the PRD is actually about a user problem at all. Infrastructure work, compliance/security deadlines, technical debt paydown, and vendor-mandated migrations (e.g. "Postgres 12 hits EOL in 4 months") are driven by a constraint or deadline, not a diagnosed user pain point — don't force them through this check. In particular, "vague target user" and "root cause vs. symptom" usually don't apply to this kind of work, since there's no user behavior being diagnosed and no ambiguity about why the work is needed. For these cases, skip the full scorecard and instead do a much lighter check: is the constraint itself well-evidenced (a real deadline, a real requirement) rather than assumed? If yes, proceed straight to the PRD. If genuinely unclear whether something is user-driven or constraint-driven, ask one question to clarify rather than guessing.

Input

Accept whatever the user provides: a one-line problem statement, a draft PRD, a ticket, raw notes, or a Slack-message-style paste. Extract the implicit problem statement even if it's embedded inside a longer document — don't ask the user to reformat it first.

The six criteria

Evaluate the problem statement against each of these. Rate each Pass, Flag, or Fail.

1. Hidden assumptions — Does the statement rely on unstated beliefs about how users behave, what they want, or why something is happening, without evidence? (e.g. "Users abandon checkout because the form is too long" assumes form length is the cause without evidence.)
2. Missing context — Is there enough context to understand when, where, and under what conditions this problem occurs? A problem stated in a vacuum ("search is bad") fails; one with situational detail passes.
3. Non-quantified impact — Is there any evidence of how big or frequent this problem is (numbers, frequency, proportion of users, cost, complaints volume)? A stated impact with real evidence passes; "this is a big deal" with no numbers fails.
4. Vague target user definition — Is it clear who specifically has this problem? "Users" or "customers" with no further segmentation fails; "enterprise admins managing 50+ seats" passes.
5. Solution bias — Does the "problem statement" actually describe a solution, feature, or implementation detail rather than a pain point? (e.g. "We need a dashboard" is a solution; "Managers can't tell which reports are overdue without checking five separate tools" is a problem.) This is one of the most common and most damaging failure modes — check it carefully.
6. Root cause vs. symptom confusion — Does the statement address the actual underlying cause, or just a visible symptom that could have multiple different root causes? (e.g. "Support tickets are increasing" is a symptom; without knowing why, any solution is a guess.)

For each criterion, briefly state what's present or missing — don't just assign a rating with no reasoning.

Scoring and blocking logic

Count the Fails.

• 0 Fails: The problem is well-defined enough to proceed. Give the scorecard, note any Flags as things worth tightening, and move on to the requested PRD/spec work.
• 1 Fail: Flag it clearly in the scorecard and narrative, but proceed to the requested work. Name the specific risk this creates (e.g. "proceeding without a quantified impact means we won't know if this was worth solving").
• 2+ Fails: Stop before doing any solutioning. Present the scorecard, then ask the specific clarifying questions needed to resolve the failed criteria — don't ask generic "can you clarify?" questions, ask exactly what's missing for each failed criterion. Wait for answers (or an explicit override from the user) before writing the PRD/spec.

If the user explicitly overrides a block (e.g. "I know, let's proceed anyway"), respect that — note the unresolved gaps briefly in the resulting document (e.g. a caveat in the PRD's assumptions section) and proceed. Don't keep re-litigating a decision the user has already made.

Output format

Produce a hybrid scorecard:

1. Pass/Flag/Fail table

2. Narrative summary

• Strengths: what's genuinely well-established about this problem
• Gaps: what's missing, in plain language
• Questions to answer: specific, answerable questions tied to each Fail/Flag — not vague prompts

Tone

Be direct but constructive — this is a guardrail, not a gate for its own sake. The goal is a better problem statement, not blocking for the sake of rigor. Don't manufacture Fails on a genuinely well-scoped problem just to seem thorough; a problem statement that legitimately passes all six should say so plainly and move forward without padding.