explain-step-by-step

Step-by-Step Explanation Skill

You explain complex things progressively, building understanding layer by layer.

Philosophy

• Progressive disclosure - Start with the big picture, then details
• Logical ordering - Present steps in the order that builds understanding
• Efficient - No filler words, no over-explanation
• Domain-agnostic - Works for code, PRs, documents, concepts, anything

Process

1. Identify What to Explain

Determine the subject:

• PR/commit changes
• Code file or function
• Architecture or system
• Document or spec
• Concept or process
• Error or behavior

2. Gather Context

For PRs/code changes:

# Get the diff
git diff main...HEAD  # or specific commits
gh pr diff <number>   # for GitHub PRs

For code:

• Read the relevant files
• Use LSP for definitions/references if helpful

For concepts:

• Draw on your knowledge
• Research if needed (WebSearch)

3. Structure the Explanation

Always start with a 1-2 sentence summary:

This PR adds rate limiting to the API by introducing a Redis-backed
token bucket and applying it to all authenticated endpoints.

Then break into logical steps:

Subject Type	Step Ordering
PR/changes	By logical dependency, not file order
Code flow	By execution order
Architecture	Outside-in (boundaries -> core) or inside-out
Process	Chronological or causal
Concept	Simple -> complex, concrete -> abstract

4. Present Each Step

Format each step as:

## Step N: [What This Step Accomplishes]

[1-2 sentences explaining the step]

[Code snippet or relevant excerpt if applicable]

**Key insight:** [One sentence on why this matters or what to notice]

5. Connect the Steps

After all steps, optionally add:

• How the pieces fit together
• What to watch out for
• Questions the reader might have

Example: Explaining PR Changes

Input: "Explain this PR"

Output:

## Summary

This PR adds user session management with automatic timeout and refresh.

---

## Step 1: New Session Model

Adds `Session` struct with user ID, expiry, and refresh token.

```rust
pub struct Session {
    user_id: Uuid,
    expires_at: DateTime<Utc>,
    refresh_token: String,
}

Key insight: Sessions are stored server-side, not in JWT claims.

---

Step 2: Session Middleware

New middleware checks session validity on each request.

async fn session_check(req: Request, next: Next) -> Response {
    let session = get_session(&req)?;
    if session.is_expired() {
        return Err(Unauthorized);
    }
    next.run(req).await
}

Key insight: Expired sessions return 401, forcing re-auth.

---

Step 3: Refresh Endpoint

Adds /auth/refresh to extend sessions without re-login.

Key insight: Refresh tokens are single-use and rotated on each refresh.

---

How It Fits Together

Request -> Middleware checks session -> If valid, proceed -> If expired, client calls refresh -> New session issued

Watch out for: The refresh token rotation means clients must store the new token after each refresh.