clarify

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.