Imported from nandnijaiswal/wtfismyrepo (SKILL.md). Install upstream with npx skills add nandnijaiswal/wtfismyrepo. Copyright stays with the author.

name: wtfismyrepo description: Onboarding companion that explains an unfamiliar codebase using the ADHD diverge→score→deepen engine (github.com/UditAkhourii/adhd). Use whenever someone is new to a repo, lost in a codebase, or asks: "where do I start", "how does this work", "explain this repo", "I'm new to this codebase", "walk me through", "give me a tour", "what is going on here", "where is X handled", "what breaks if I touch this", "what should I work on first", "how do I run this", "trace this request", "onboard me", "ramp up", "understand this project", "wtf is this". Trigger aggressively on any codebase confusion.

wtfismyrepo skill

Engine: ADHD diverge→score→cluster→deepen loop (MIT, github.com/UditAkhourii/adhd) Data layer: wtfismyrepo deterministic analysis — import-graph PageRank, git-churn fragility, GitHub PR/issue signals

How this skill works

Most "explain my code" approaches are linear: read the code, summarize it, done. That anchors on whatever angle the first pass happens to take.

This skill treats codebase onboarding as an ideation problem using the ADHD two-phase architecture:

1. DIVERGE — Generate N independent onboarding angles under deliberately different cognitive frames (new-grad, archeologist, security researcher, on-call engineer…). Zero cross-talk between frames during generation so no anchoring.
2. SCORE → CLUSTER → DEEPEN — A critic pass scores each angle for this developer's situation (novelty to them, viability for their goal, fit to the codebase's actual complexity). Cluster angles by underlying approach. Deepen the best one into a full walkthrough.

The hard data (entry points, spine, fragility, hot zones) comes from wtfismyrepo --json. The ADHD loop decides how to explain it given who's asking and why.

Step 0 — Get the hard data first

Before any explanation, run the deterministic engine to get ground-truth:

wtfismyrepo . --json --no-color    # full analysis: PageRank, churn, history
# or from GitHub without a local clone:
npx github:nandnijaiswal/wtfismyrepo . --json --no-color

If the CLI is unavailable, use these tools directly:

• gh repo view --json name,description,languages
• gh pr list --state open --json number,title,files
• gh issue list --state open --label "good first issue"
• git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -20
• File read + import parsing for the dependency graph (manual)

Store the JSON. Every explanation you give should be anchored to it — not guessed.

Step 1 — DIVERGE: generate onboarding angles across frames

This is the ADHD diverge phase. Run each frame as a separate, isolated reasoning thread. Do NOT let one frame's output influence another while generating. No evaluation during generation — pure ideation only.

For each frame below, generate 3–5 distinct onboarding angles: different ways of entering and explaining this codebase. Each angle is one sentence describing the approach.

The onboarding frames (select 4–6 per run, always include one wild)

Diverge output format (per frame, before any scoring):

Frame: [label]
Angles:
- [one sentence: a distinct way to enter/explain this codebase from this vantage]
- ...

Step 2 — SCORE each angle

Critic phase. Now evaluate every generated angle on three axes:

For each angle, also flag traps: onboarding approaches that look helpful but waste the developer's time — e.g., "read all the tests first" when there are 800 tests and none document the domain model; "trace the codebase top-down" when the codebase has no clear entry point.

Score format:

Angle: [text]
  Novelty: N/10 — [one clause]
  Viability: N/10 — [one clause]
  Fit: N/10 — [one clause]
  Total: N.N
  Trap: [if applicable, one-line reason] | CLEAN

Step 3 — CLUSTER

Group the top (non-trap) angles by their underlying approach, not surface keywords. Name the cluster by the strategy, e.g.:

• "Follow-the-data plays" (data engineer, performance engineer angles)
• "Read-the-history plays" (archeologist, contrarian angles)
• "Blast-radius-first plays" (CTO, on-call, refactorer angles)
• "User-value plays" (PM, domain expert angles)

Report: cluster label → angles in it.

Step 4 — NON-OBVIOUS PICK + DEEPEN

Select the highest novelty × viability scorer (not just the highest total — the goal is to escape the obvious). This is the non-obvious pick.

Then deepen it:

1. Sketch — exactly how to execute this onboarding angle on this codebase (4–8 sentences, cite real files from the analysis data).
2. Load-bearing risk — what makes this approach fail (e.g., "only works if the git history is informative; shallow clones break it").
3. First concrete step — the exact file to open or command to run.
4. Child angles — 3–5 variations or combinations with other frames that this approach unlocks.

Step 5 — DELIVER the walkthrough

Execute the deepened winning angle as an actual onboarding walkthrough. Ground every statement in the wtfismyrepo data:

• Always link to real files (path/to/file.ext:line where known).
• Cite the history — pull reasoning from PR/issue data, not invented.
• One layer at a time — explain one component, check understanding, then go deeper.
• Surface the traps — flag the winning angles the developer should skip, and why.

End every session with "Your first move":

1. The exact file to open.
2. The exact first safe change or issue to pick up.
3. The blast-radius warning: "Before touching X, know that A and B depend on it."

The three questions that must be answerable after this skill runs

1. "This system exists to ______, and it works by ______."
2. "If I need to change ______, I start in ______ and watch out for ______."
3. "The riskiest/most fragile part is ______, because ______."

If the developer can't finish these sentences, the skill hasn't finished. Go deeper.

Anti-patterns (do NOT do these)

• ❌ Single-frame explanation — pick one angle and explain. Run the diverge pass.
• ❌ Explaining code without the data — run the CLI first. No guessing at structure.
• ❌ Dumping the whole directory tree — one layer at a time.
• ❌ Skipping "Your first move" — a lost dev needs a first step, not a lecture.
• ❌ Letting frames cross-contaminate during generation — diverge is isolated, critic is separate.

Engine: ADHD parallel divergent ideation framework, MIT license, by Udit Akhouri (github.com/UditAkhourii/adhd). Data layer: wtfismyrepo by Nandni Jaiswal (github.com/nandnijaiswal/wtfismyrepo).