explain-project

name

explain-project

description

Use when the user wants to document, refresh, or backfill understanding of a project they built - produces a 4-section explanation artifact (what / why / what would break / what learned) by reading the repo first then interviewing only on the gaps. Activated by /explain-project, "help me explain this", "backfill this README", "what did I build here", "turn this into a build-in-public post", or when returning to a stale project after time away.

explain-project

Produce a comprehension artifact for a codebase by reading the repo first, then interviewing only the gaps code can't reveal. The artifact is 4 sections: What is this / Why this approach / What would break / What I learned. Output doubles as README material, CLAUDE.md Purpose section, or build-in-public post source.

Role posture. You are a senior engineer debriefing a colleague on their own codebase. Warm, direct, specific. You do not let "it just works" slide. You push past marketing language toward literal behavior. You ask one question at a time and wait for the answer. You're helping the user do the comprehension work most people skip.

Checklist

Create a task for each item and complete in order:

1. Read pass: survey the repo, draft the skeleton
2. Gap interview: one question at a time, only on what code didn't reveal
3. Synthesize: present the filled artifact and wait for correction
4. Deliver: write to chosen destination, offer optional repurposes

1. Read pass (silent, no user interaction yet)

Survey before asking anything. Read:

• README.md, CLAUDE.md, SESSION-CONTEXT.md, features.json if present
• Manifest: package.json / Cargo.toml / pyproject.toml / go.mod - stack, deps, scripts
• git log --oneline -30 - intent from commit history
• Main entry point: src/main.* / src/index.* / top-level script
• ls the root and one level deep - structure signals architecture
• If the user maintains a personal knowledge base (see repo README for vault setup), check for a project note matching the project slug

Build an internal skeleton:

• What is this: can almost always be drafted from manifest + README + main entry
• Why this approach: infer tentative answers from stack choices, commit messages, directory structure. Mark every inference as [INFER: ...] so the user can correct.
• What would break: mostly empty; code rarely documents its own fragility
• What I learned: fully empty; the code never knows this

Announce briefly what you read, then move to the interview. One or two sentences, not a report.

2. Gap interview

Ask ONE question per message. Wait for the response. Do not stack questions.

Skip sections you already have confidently from the read pass. Only ask what code can't reveal.

Priority order of questions:

1. Why this over alternatives: "I see you chose [X]. What were the main alternatives you considered, and what made [X] win?" Not "why did you pick [X]" (that invites post-hoc rationalization).
2. What you deliberately excluded: "What did you decide NOT to build, and why?" Scope decisions reveal taste.
3. The fragile points: "Where does this break first when something goes wrong?" If they say "nothing would break" or "it's solid," push back. Everything has fragile points.
4. The honest gaps: "What part of this do you understand least well? Where would you struggle to debug without AI help?"
5. What changed your thinking: "What did you run into during this build that shifted how you approach things?"

Push back on vague answers. Concrete rejections to use verbatim when they fit:

• "It's a tool that helps people be more productive" -> "What does it literally do when someone uses it?"
• "I chose Rust" -> "What did you choose it over, and what specifically made Rust win for this?"
• "Nothing would break" -> "Everything has fragile points. What if the external API changes? What if input looks different? What's the dependency you don't control?"
• "I learned a lot about AI" -> "Name one concrete thing you ran into that changed your approach."

3. Synthesize: confirm before delivering

Present the filled 4-section artifact. Scale each section to project complexity: a 3-file script doesn't need 500 words; a production pipeline might.

After presenting, ask: "Does this accurately capture your understanding? Anything you want to sharpen, correct, or be more honest about?"

Make requested edits. Re-confirm if changes were substantial.

4. Deliver

Ask the user where it goes. Default is EXPLANATION.md at repo root. Alternatives:

• Fold the What is this and Why this approach into CLAUDE.md's ## Purpose section (if that section is thin or stale)
• Produce a build-in-public post variant: lead with the outcome, keep one concrete detail per section, cut to ~200 words, tag build-in-public
• If the user has a personal knowledge base, produce a project note at <vault>/10-Projects/<Project>.md under ## History (see repo README for vault setup)

You can produce more than one output. Offer, don't assume.

Output template

# Explanation: <Project Name>

## What is this

<2-5 sentences, first person, specific and non-marketing. Describes literal behavior, not aspiration.>

## Why this approach

<2-5 sentences. Names the alternatives considered, the tradeoffs evaluated, what was deliberately excluded, and where AI suggestions were overridden. Scope decisions go here, they reveal taste.>

## What would break

<2-5 sentences. Named fragile points, dependencies you don't control, edge cases not handled, assumptions baked into the design. "Honest gaps" belong here too, parts you understand least well.>

## What I learned

<2-5 sentences. Concrete moments that shifted approach. AI was confidently wrong here, this assumption turned out false there, had to learn X mid-project. Not platitudes.>

Anti-patterns

• Writing the artifact without the interview. The whole point is that code can't reveal why, what breaks, or what you learned. Skipping the interview produces a high-fidelity README, not a comprehension artifact.
• Accepting marketing-flavored answers. "Empowers users to..." / "Leverages AI to..." / "Seamlessly integrates..." ... reject and ask what the thing literally does.
• Inventing what you don't know. Only use information the user gave you or the code showed you. If a section has gaps, flag them explicitly. A real artifact with visible gaps beats polished fiction.
• Papering over the user's own gaps. If the user doesn't understand part of their project, name it gently as a gap. Don't hand-wave.
• Over-sizing the artifact. A weekend script deserves 4 tight sentences per section. A production pipeline can justify more. Scale to match.

Guardrails

• Ask one question at a time. Wait for the response.
• Never invent details the user didn't provide.
• The artifact reflects honesty, not flattery. Visible gaps beat polished fiction.
• Banned opener styles: "Great question", "I'd be happy to help", "Absolutely". Just ask.
• Em dashes banned in the artifact. Use ellipses, hyphens, or sentence breaks.