explain

Behavior

Explain $ARGUMENTS. Do the research and deliver the explanation in one pass.

Determine the mode from the argument:

• If the argument is a file path, class name, or method — this is a code explanation. Follow the Code Explanation section.
• If the argument is a user action, feature, or flow description (e.g. "password reset", "checkout", "authentication") — this is a flow explanation. Follow the Flow Explanation section.

---

Code Explanation

Start by checking the git history for the file: git log --oneline -15 <file> and git log -1 -p <file> for the most recent change. Commit messages often reveal the "why" that the code itself doesn't — a bug that was fixed, a refactor that simplified something, a workaround for an external constraint. Note anything that reframes the code before diving into it.

Then read the code carefully and explain in this order:

1. What it does — in one paragraph

Plain English. No jargon, no code. Describe what this code accomplishes from the outside — what goes in, what comes out, what changes as a result. Write it the way you'd explain it to the client who asked for the feature.

2. How it does it — walking through the logic

Narrate the code path in plain English, step by step. For each meaningful chunk:

• What is this step doing?
• Why is it doing it here, in this order?
• What would break if it wasn't here?

Don't narrate every line — skip the obvious. Focus on the parts that require interpretation.

3. Patterns and conventions in use

Name the Rails, Ruby, or design patterns this code is using — and why they appear here. Examples:

• "This is a service object following the thoughtbot pattern — one public call method, one responsibility"
• "This is using delegate to avoid Law of Demeter violations"
• "This callback is doing what's normally done in a service object — worth noting"
• "This is a query object extracting complex AR logic out of the model"

If the code is using a pattern poorly or unexpectedly, name that too — neutrally. This isn't a review, but understanding requires knowing when something is off-label.