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.

- **The skill orchestrates and synthesizes; the agents discover, 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: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.
- **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 purpose, flow, and context sections at the level of what the code does and why. 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 target string given** → **PR mode** against the current branch's changes (the local diff). This requires git, not a remote pull request.

**Handle the unresolvable and empty cases** (state the problem plainly and stop; never guess):

- A path or symbol that resolves to nothing, or a symbol ambiguous across several definitions → report what could not be resolved and ask the user to disambiguate.
- No target given and the working tree is clean with no branch changes → ask the user for a code target rather than producing an empty overview.
- No target given and git is unavailable → tell the user PR mode and the bare-invocation default need git to read changes, and ask for a named code target (code mode still runs without git).

**Resolve project context.** If `CLAUDE.md` is present, read its `## Project Discovery` section for conventions; fall back to `project-discovery.md`. These resolve language and framework questions so the explorers infer less. If neither exists, note that surrounding-code inference applies and pass that into the briefs.

## Step 2: Classify Size and Announce

**Classify the target's size. Default to small**; escalate only on a clear signal, and stay at the smaller band when a signal is borderline.

- **Small** *(default)* — a single file, a single symbol, or a small change set (a few files in one subsystem).
- **Medium** — a directory or module, or a moderate change set (several files across one or two adjacent subsystems).
- **Large** — multiple subsystems, or a large change set (many files across several subsystems).

**Apply the size override.** If `$size` is not `none provided`, use it as the band and skip the signal-based classification; a conversational override ("give me a large overview") is equivalent.

**Announce the chosen mode and size in one line before dispatching any exploration** — for example, `Code mode, size medium: directory \`src/auth/\` spanning the session and token subsystems.` State tool degradation in the same line when it applies (`git unavailable