| name | clarify |
| description | Handles user confusion by explaining actual behavior and determining whether there is a real issue to address. Primary goal is clarification, not a fix. Use when the user says "I don't understand", "this doesn't make sense", "why does this do X", or shows contradictory expectations about existing code.
|
| user-invocable | true |
| disable-model-invocation | false |
Clarify
Explain first. Do not jump to a fix.
Steps
1. Verify intent
Before reading anything, repeat back what you think the user is confused about in one sentence. If you're guessing, ask a clarifying question instead.
2. Read the relevant code
Open the exact files the user is looking at. Include tests (*.test.tsx) — they often document intent. Do not read more broadly than needed.
3. Explain what actually happens
Describe the real behavior, not what the code "should" do. Reference specific lines with file:line. If the behavior differs from what the user expected, say why:
- Is there a subtle invariant (React render order, effect cleanup, state batching)?
- Is it a GTS-enforced style that looks unusual but is intentional?
- Is it CRA/react-scripts magic (setupTests, env vars, etc.)?
- Is it actually a bug?
4. Offer three next steps
Use AskUserQuestion:
{
"questions": [{
"question": "Explanation clear. What's next?",
"header": "Next step",
"options": [
{"label": "Accept as-is", "description": "The current behavior is correct. Move on."},
{"label": "File as change request", "description": "The behavior is wrong or unclear. Open /add-feature to design a change."},
{"label": "Investigate further", "description": "Dig deeper into related code, tests, or history before deciding."}
],
"multiSelect": false
}]
}
Rules
- Explain before fixing. The user may not actually want a fix.
- Cite
file:line whenever you reference behavior.
- Distinguish "unusual but intentional" from "actually a bug" clearly — do not hand-wave.
- If the user confirms it's a bug, exit this skill and switch to
/add-feature or a direct fix. Don't patch in place inside a clarify session.