Code Overview

Step 5: Synthesize the Overview

Invoke han-communication:readability-guidance to surface the shared readability standard into your context before you write. Then invoke han-communication:explanation-guidance, which surfaces Han's standard for explaining technical work to a reader who will not implement it: that standard governs the closing restatement this step writes and the closing message Step 8 prints, BECAUSE both go to someone who will not open the code. Both run inline and hand control straight back; continue with this step as soon as they return. Then draft the overview against both. Read references/overview-template.md and render the structure for the resolved mode, drawing on the explorers' findings and the input from Step 3. The skill writes the overview; the explorers' raw findings are not pasted in.

Open the document with a title and a short intro paragraph naming what is being examined — the file, directory, symbol, pull request, or branch, and the part of the system it belongs to. Do NOT emit a Mode:, Generated:, or bare Target: metadata block; that metadata does not help the reader. Never state PR statistics — lines changed, files changed, additions/deletions, or commit counts — anywhere in the document; they go stale the moment the PR changes and add no understanding. Fold anything worth keeping into the intro sentence.

Lead with the why, and let everything else flow from it. The first section after the intro answers why this code (or this change) exists — the real problem it solves or the goal it accomplishes for the business or a user, then why it works the way it does and why it is the current solution to that need. Tell the why as a solution to a need, not as technical mechanics. Then frame every section that follows as serving that why: the flow shows how the code delivers on it, the context shows what it depends on to meet the need, the handoff shows where to start working on it. When the why is not recoverable from the code and its intent (commit messages, PR/issue text, comments, naming, tests), state what the code demonstrably does toward a goal and mark the inferred why as inferred — never invent a business rationale the evidence does not support.

Say when the code does not support the stated reason (PR mode). You already read the code to ground the why. When that reading shows the code already satisfies the stated motivation, or shows the change is not needed for the reason given, say so in the why section itself, in one or two sentences, as a fact about the stated reason. Raise no finding, assign no severity, recommend no change; the rest of the overview proceeds as normal. Three states, and only the first gets the sentence:

1. You checked and the code contradicts the stated reason. Say so.
2. You checked and the code supports it. Say nothing extra.
3. The code says nothing either way. That is the inferred-why case above: mark the reason as inferred and claim no discrepancy.

NEVER report a contradiction you did not check and find, BECAUSE that is a stronger claim than the evidence carries and the honest weaker claim already has a home in state 3. This is the highest-value sentence a change overview can carry, and it is also the easiest one to get wrong by reaching.

Code mode renders, in order: the title and intro paragraph; a coverage note only if coverage was partial; Why it exists (the problem the code solves or goal it serves, then briefly what it is and why it works the way it does — all flowing from the why); Context used (the context ledger, rendered per the rules below); Main flow (a Mermaid chart with a one-line scope label, read as how the code delivers on the why); Context and uses (context and uses kept distinguishable, framed as what it depends on to meet the need and where that need is served from); Where to start (the entry points numbered in the order a reader opens them, each with one line on what the reader learns there, and one runnable example call on any entry point that is an interface other code calls); What this code does, in plain language (the closing restatement).

PR mode renders, in order: the same title and intro paragraph; the same conditional coverage note; Why this change exists (the problem the change solves or goal it advances, then briefly the bottom line of what it does, plus the unsupported-reason sentence when it applies — see below); Context used (the context ledger, rendered per the rules below); Changes by intent (grouped by the reader-visible outcome each group delivers — the why each group serves — not by file, layer, or author motivation; a single logical change is one narrative with no grouping header); How the change flows (a Mermaid chart with a scope label, placed after the grouped changes BECAUSE the reviewer must know what changed before that chart is meaningful); What to watch when reviewing (navigational only — where the change is hardest to follow and why; never a quality or risk judgment); What this change does, in plain language (the closing restatement).

Render the Context used section from the context ledger built in Steps 3 and 4, directly after the lead why section in both modes. One line per source, each with a short note on what it contributed. Link every source that has a direct address: a repository file or directory as a Markdown link whose target is its absolute path (the overview file may sit outside the repository, so a relative path would not resolve); a pull request, issue, or commit as its URL (in PR mode with a remote, prefer the remote's file URLs at the PR's head so the links work for a reader outside this machine). A source with no address — the uncommitted diff, the branch's commit messages, context the user supplied in conversation — gets one plain sentence stating what the context was. Never fabricate a URL or link a path that does not exist; deduplicate the list and keep it a reference list, not prose.

Place any captured screenshots inline next to the text they illustrate — embedded as ![caption](url) directly under the Changes-by-intent item or the flow step they depict, BECAUSE a visual next to its description spares the reader a trip back to the PR. Keep the image URL exactly as captured. Omit screenshots entirely when the PR had none; never invent or placeholder an image.

Close with a restatement a person can paste. Both modes end with three or four plain sentences a reader who did not do this work could read aloud, carrying no file paths, no type names, and no symbol names. Write them under the explanation standard sourced above. These sentences are the canonical text: Step 8's message repeats them rather than composing its own version, BECAUSE the reader's next move after an overview is reliably to paste a plain summary into a pull request description or a message to a reviewer, and two texts saying the same thing in different words teach them to distrust the shorter one.

Apply the per-section detail rule from the template: minimal technical detail in the why, flow, and context sections — the why told as a problem solved or goal met, not technical mechanics; concrete named entry points in the handoff section. Give every chart a scope label, and apply the template's diagram rule to every chart you draw: each box names a component or a boundary, and the fields, types, and annotations go into the prose beneath the chart. When coverage is partial, place the coverage note immediately after the intro paragraph so the reader calibrates before investing in the charts.

Step 6: Resolve the Destination and Write the File

The file is named code-overview-{short-target-slug}.md wherever it lands. Only the directory is resolved here.

Resolve the directory in this order:

1. A configured output-directory. When the config read at the top of this skill supplied one, write the overview beneath it. Honor it even when it points inside the repository, and say nothing about that, BECAUSE the person who configured a destination chose it, and this skill's own default is not a veto over their choice. Relative-path resolution, ~ expansion, and precedence between the personal and project files are governed by config-rule.md; do not re-derive them here.
2. No configured value. Write outside the repository — for example ${TMPDIR:-/tmp}/code-overview-{short-target-slug}.md — BECAUSE an unconfigured overview is an orientation aid rather than documentation, and a default inside the repository would land it in a commit sooner or later.

When the resolved directory cannot be written, write to the unconfigured default in 2 instead and record which destination you could not use, so Step 8's message can name it. NEVER abandon the run over this, BECAUSE everything the run produced is finished by the time it writes, and losing all of it to a directory that does not exist is the worse outcome by far.

The next step reviews and rewrites this file in place.

Step 7: Validate Accuracy, then Rewrite for Readability

This step runs two distinct passes, in order: the accuracy validator first, then the readability rewrite. Accuracy is settled before readability so the editor never polishes a claim that is about to be cut.

Pass 1 — accuracy. Dispatch han-core:adversarial-validator over the draft overview. Pass it the overview file's path from Step 6 and the resolved target (and, in PR mode, the changed-file set) so it knows what to re-read.

• han-core:adversarial-validator — assume every claim the overview makes about the code is WRONG until the code and its intent prove it right. Re-read the target (and the diff, in PR mode) and challenge each material claim, starting with the one the document leads on: is the stated why — the problem the code solves or the goal it serves — grounded in real evidence (commit messages, PR/issue intent, code comments, what the code visibly does toward that goal), or is it an invented business rationale, and where the why is inferred rather than stated, is it marked as inferred; does the code actually do what Why it exists / Why this change exists says; where the overview claims the code already satisfies the stated reason or does not support it, does the code show that, or is the code merely silent on the point — silence is not a contradiction, and a discrepancy claimed on silence is an inaccuracy to cut; does the Main flow / How the change flows chart match the real control flow, in the right order, with no invented or missing steps; do the named Where to start entry points exist and are they the right ones; does each Changes by intent grouping describe what that change actually does and the why it claims to serve; does every entry in Context used point at a source that exists (the file path resolves, the PR / issue / commit reference is real) — a fabricated or broken link is an inaccuracy like any other. Surface every claim that is unsupported, overstated, contradicted by the code, or hallucinated — the why most of all, since it is the load-bearing claim — citing the file, line, or commit that disproves it. Validate the accuracy of the description only — do not assess the code's quality and do not raise findings about the code itself. Return a list of inaccurate or unsupported claims, each with the corrected fact or a note that the claim should be cut.

Apply the validator's corrections to the overview file first: fix or cut every claim it disproved. A sentence that reads beautifully but describes a flow the code does not follow must still be corrected or removed. If validation removed so much that coverage is now meaningfully partial, add or update the coverage note.

Pass 2 — readability rewrite. Dispatch han-communication:readability-editor over the corrected draft. This dedicated pass replaces the older information-architect / junior-developer readability review; the deliverable gets one readability rewrite, not two overlapping reviews.

• han-communication:readability-editor — rewrite the overview against the shared readability standard for the default reader (a capable reader who did not do this work and lacks the author's context), preserving every fact. Pass it the overview file's path; the editor reads han-communication's own canonical rule, so pass no rule path. It operates on prose regions only: it does not touch the Mermaid chart bodies, code fences, or the embedded screenshot markup, and it leaves every named file, symbol, entry point, and Context used link target exact. It applies the rewrite to the overview file in place and returns a rubric verdict and a fact-preservation ledger. Tell it: rewrite the overview document for readability only — do not review the underlying code, and do not raise findings about it. This skill makes no quality judgment about the code; the validator guards truth, the editor guards clarity, and neither crosses into evaluating the work itself.

Keep the spec-content discipline through both passes: the result is still an orientation aid with no quality findings, led by the why with everything flowing from it, minimal technical detail in the why/flow/context sections, and concrete entry points in the handoff section.

Readability self-check. After the rewrite, run the standardized readability self-check (the shared standard is in your context from han-communication:readability-guidance) over the overview's prose regions only — never inside the Mermaid chart bodies, code fences, screenshot markup, or file/symbol references. Confirm each criterion and fix any failure before presenting:

Run the readability rule's standardized self-check, which is already in your context from the readability-guidance invocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs how the content is said, never whether a required fact about the code appears.

For this skill, the main point the opening line must state is what is being examined and why it exists.

Required-content check. Run this after the readability self-check, and after the accuracy pass, BECAUSE a check that runs before the accuracy pass can confirm content that is about to be corrected or cut. Each item is a yes/no question about the finished document. Fix every failure before presenting; never present a failure as a caveat.

1. Diagrams. Every chart's boxes name components and boundaries, with fields, types, signatures, and annotations in the prose beneath rather than inside a box. This is the one check that reads inside the chart bodies, which the readability self-check leaves alone by design.
2. Starting points. The entry points are numbered in reading order, each carries one line on what the reader learns there, and every entry point that is an interface other code calls carries one runnable example call.
3. Terms the reader cannot look up. Criterion 5 of the readability self-check above carries this one: every outside technology, language runtime, named method, and coined compound noun has its half-sentence explanation at first use. Confirm it passed rather than re-running it.
4. The closing restatement. The final section is present, runs three or four sentences, and carries no file paths, no type names, and no symbol names.

Step 8: Present

Present a short message in this fixed order. The answer leads and the run's own bookkeeping comes last, BECAUSE this message is the first thing the user reads and facts about how the run went are the last thing they need from it:

1. The closing restatement, copied from the overview's own final section. Repeat those sentences; never compose a second version of them.
2. Any divergence from the change's stated purpose, when the overview reported one (PR mode only).
3. The path to the overview file. When Step 6 fell back because the resolved destination could not be written, name the destination it could not use.
4. The run's own facts, last: the mode and size used and why, plus any coverage gap the overview noted.

Do not paste the whole overview into the conversation; point the user at the file, where the Mermaid charts render.