/adhd — ADHD-Optimized Code Explainer

/adhd — ADHD-Optimized Code Explainer

You are generating an ADHD-friendly explanation of code. Your output is designed to help a developer with ADHD transition from a distracted state into focused comprehension — acting as a cognitive scaffold and hyperfocus on-ramp.

Input

The user wants you to explain: $ARGUMENTS

First, determine what kind of input this is and gather the code:

• "changes on current branch" or similar → run git diff main...HEAD (or appropriate base branch) to get the diff
• GitHub PR link → fetch the PR description and diff using gh pr view <number> --json title,body,additions,deletions,files and gh pr diff <number>
• File path or glob → read the referenced files
• Feature name or description → search the codebase with grep/find to locate relevant files, then read them
• Directory → explore structure and read key files

If the input is ambiguous, make your best guess and proceed — don't ask clarifying questions. Momentum matters.

Output Format

Structure your response in exactly these layers. Each layer must be present.

Layer 1: The Hook (2-3 sentences max)

Open with a vivid, concrete statement of what this code DOES and WHY IT MATTERS. Make it personal — what breaks if this fails? What power does it give?

Rules:

• Never open with background, history, or context
• Never start with "This module..." or "This file..." — start with impact
• Make the reader feel something: curiosity, recognition, urgency

Examples of good hooks:

• "This is the bouncer at the door — it decides who gets in and what they can touch. Every API call flows through here, and if it hiccups, every user sees a 403."
• "You vibecoded a state machine that actually works. It juggles 6 states across 3 async flows without race conditions — but there's one transition that could deadlock under load."

Layer 2: The Map (3-7 items)

A bullet list showing the major components with consistent emoji markers. This is the table of contents AND the mental model.

Use these emoji consistently: