Explain

For each change (or group of related changes), explain:

• What problem it solves
• Why this approach was chosen over alternatives
• What would happen if this change was NOT made

Connect the dots between changes. If file A was changed because of file B, say so.

Step 4: Explain — How does it work?

This is the deep dive. Explain the logic step by step:

• Walk through the code flow as if you are tracing execution
• Use numbered steps: "First this happens, then this, then this..."
• Use simple analogies where helpful (e.g., "Think of this like a to-do list where...")
• If the logic involves data flow, show it visually with ASCII diagrams:

  User clicks button
       |
       v
  handleClick() runs
  API call to /api/save
  Response updates state
  Component re-renders with new data

• If there are important patterns (hooks, context, middleware, etc.), explain what they are and why they are used here
• Define any technical terms the first time you use them

Step 5: Key takeaways

Summarize with 3-5 bullet points:

• The most important thing to remember
• Any gotchas or edge cases to watch out for
• Related concepts worth learning more about

Writing Rules

• Use simple English. Short sentences. No jargon without explanation.
• Write like you are explaining to a teammate on their first week.
• Prefer concrete examples over abstract descriptions.
• Use "you" and "we" to keep it conversational.
• Use code snippets, ASCII diagrams, and step-by-step flows wherever they help.
• Do NOT assume the reader knows framework-specific concepts — explain them briefly.

Step 6: Ask about saving

After the explanation is complete, ask:

"Want me to save this explanation to a markdown file for future reference? (default: no)"

• If the user says no or does not respond, do nothing. Stop here.
• If the user says yes, ask where they want to save it. Suggest a sensible default path based on the project structure (e.g., docs/explanations/ or .notes/).
• Save the explanation as a clean markdown file with a descriptive filename based on the topic (e.g., auth-flow-explanation.md).

User Arguments

$ARGUMENTS