code-overview

## Project Context

- git installed: !`which git`
- gh installed: !`which gh`
- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`

## Operating Principles

Read these before doing anything. They constrain every step below.

- **"Why" is the organizing question.** The overview exists to answer one question first: *why does this code exist?* — and the answer is the real problem it solves or the goal it accomplishes for the business or a user, never the technical mechanics. Why it exists, why it works the way it does, why it is the current solution to a real need: that is the spine of the whole document. Everything else the overview carries — what it does, how it flows, where it connects, where to start — flows out of the why and exists to give the reader the context to understand it. "What", "how", "where", and "when" are not dropped or diminished; they are framed by and subordinated to the "why" they serve. BECAUSE a reader who knows what code does but not why it exists cannot make sound decisions about it — the why is the load-bearing understanding, and the rest is scaffolding around it. State the why as a solution to a need, and never invent a business rationale the evidence does not support; when the why can only be inferred, mark it as inferred.
- **The skill orchestrates and synthesizes; the agents discover, validate, then refine.** The skill resolves the target, classifies size, dispatches exploration, and writes the overview. `han-core:codebase-explorer` agents gather the surrounding code and context the synthesis draws on — they do not write the overview. After the draft is written, `han-core:adversarial-validator` re-reads the code to challenge the draft's claims for accuracy, and `han-core:information-architect` and `han-core:junior-developer` review it for progressive disclosure and readability; the skill applies their recommendations. The skill itself produces the grouping, the charts, the orientation, and the final rewrite.
- **Read-only, always.** The skill explains; it never edits the target. It writes only its own scratch overview file. BECAUSE the job is understanding, not modification — this keeps the skill safe to point at unfamiliar code.
- **Accurate to the code, always.** Every claim the overview makes — the why it states (grounded in commit and PR/issue intent, comments, and what the code visibly does toward a goal), what the code does, each flow step, each named entry point, each change grouped by intent — must be grounded in the actual code and its intent, never inferred past the evidence or invented. BECAUSE a confidently wrong overview is worse than none: it sends the reader to the wrong file with false confidence and silently corrupts the mental model the skill exists to build. The adversarial validation pass (Step 7) exists to catch this. It is accuracy control on the *description*, NOT a quality judgment about the code — the two are different lines, and crossing into the second is still forbidden.
- **No quality judgment, ever.** The overview raises no findings, severities, or recommended changes — including in the PR-mode "what to watch" section, which is navigational only. BECAUSE reviewing a PR's quality is `code-review`'s job; this skill only helps the operator understand the PR before they review it. Crossing this line collapses the boundary between the two skills.
- **No PR statistics, ever.** The overview never states lines changed, files changed, additions/deletions, commit counts, or any other diff-stat figure — not in the intro, not in a section, not anywhere. BECAUSE these numbers go stale the instant the PR is updated and add no understanding; describe what changed and why, never how big the diff is.
- **Ephemeral, not documentation.** The overview is written to a scratch file outside the repository and is never committed into the repository's documentation tree. BECAUSE durable feature and system docs are `project-documentation`'s job; this skill is an understand-now orientation aid.
- **Default to small.** Start size classification at small and escalate only when a higher-band signal is clearly present. BECAUSE under-dispatching is recoverable by re-running larger; over-dispatching burns tokens and dilutes the overview.
- **Minimal technical detail, scoped per section.** Keep the why, flow, and context sections at the level of why the code exists and what it does — the why is told as a problem solved or goal met, not as technical mechanics. The where-to-start / what-to-watch handoff is the one exception — it must name concrete entry points or it is not actionable.
- **The output template lives at [references/overview-template.md](./references/overview-template.md).** Render that template; do not invent a structure inline.

# Produce a Code Overview

## Step 1: Resolve the Target and Select the Mode

**Bind `$size`.** If the user passed `small`, `medium`, or `large` as the first positional argument, bind `$size` to it. Anything else is part of the target, not a size; bind `$size` to the literal `none provided`.

**Note tool availability.** Read `git installed` and `gh installed` from Project Context. If `git installed` is empty, git is unavailable — see the degraded paths below.

**Resolve the target and mode by this fixed precedence**, so an ambiguous string never silently selects the wrong mode:

1. **An explicit pull request reference or URL** (e.g. `#82`, `https://github.com/owner/repo/pull/82`) → **PR mode** against that pull request. Requires `gh`; if `gh installed` is empty, tell the user `gh` is needed to read a named pull request and offer code mode against a local target instead.
2. **An existing file or directory path** (confirm it resolves with Glob or find) → **code mode** on that path.
3. **A symbol** (a function, class, type, or other named code entity) → **code mode** on that symbol. Resolve it with Grep across the repository.
4. **No targ