problem-clarifier

A guided interview for clarifying a bug, problem, or feature request before investigating or planning a solution.

In plain words
What is it for?
Use it to capture the intended result, observed behavior, triggers, and other details through a reflect-back conversation.
Why use it?
It prevents work from starting with an incorrect understanding of what the user expected and what actually happened.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/recusive/skills/problem-clarifier
Any agent
npx skills add Recusive/Skills --skill problem-clarifier
Clone the repo
git clone --depth 1 https://github.com/Recusive/Skills

Made for: Claude Code, Codex.

Per session 108 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,590 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00108 $0.01590
Opus 5 $0.00054 $0.00795
Sonnet 5 $0.00022 $0.00318
Haiku 4.5 $0.00011 $0.00159

Measured 2d ago against content hash 29ec0dfe986a, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

problem-clarifier scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

problem-clarifier/SKILL.md · 120 lines

How it starts

The opening of the file, as written. The whole thing — 120 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Problem Clarifier

You are about to help someone articulate a problem they're experiencing. Your job is NOT to solve it, NOT to investigate code, and NOT to start planning. Your only job right now is to understand exactly what the problem is by reflecting it back until you and the user are on the same page.

Why this matters

When someone describes a problem in natural language, the words they use rarely capture the full picture. They might say "it's not turning blue" when the real issue is "it turns blue but then reverts on the next keystroke." If you plan based on the first description, you'll build a plan for the wrong problem. That wastes everyone's time and erodes trust.

The fix is simple: before planning anything, play back what you heard and let the user correct you. Do this until they say "yes, that's exactly it."

The Reflect-Back Loop

This is the core mechanic. It works like this:

1. Listen to the initial description

The user will describe their problem. Read it carefully. Pay attention to:

  • What they're trying to do (the intent)
  • What they expected to happen
  • What actually happened instead
  • Any specific triggers or steps they mention ("when I press space", "after I click submit")

2. Explore the relevant code

Before reflecting back, quickly explore the codebase to understand the area the user is talking about. This makes your reflect-back much more precise — you can use actual component names, function names, and file paths instead of vague descriptions. The user doesn't need to know the exact file path — that's your job.

Use Glob, Grep, and Read to understand the relevant code area. Keep this fast — you're building context, not debugging.

3. Reflect back with precision

Now restate the problem in your own words, using specific technical details from the code. Use the AskUserQuestion tool with a detailed restatement and ask if you've got it right.

The restatement should be:

  • Specific: Include the actual UI element, component, file, or flow involved
  • Step-by-step: Describe the exact sequence of user actions and what happens at each step
  • Clear about the gap: State what SHOULD happen vs what DOES happen

Read the full file on GitHub · 120 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 120 lines · 108 tokens per session scan A 29ec0dfe986a

Subscribe to this mod's changes

problem-clarifier is a skill published in the GitHub repository Recusive/Skills (2 stars, last pushed 4mo ago), licensed MIT. It adds 108 tokens to every session and 1,590 once invoked, about $0.0005 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.