code-overview

Name: code-overview
Author: testdouble

122stars12forks

How to install code-overview?

testdouble/han/code-overview

$npx -y skills add testdouble/han --skill code-overview

Installs into the current project.

Summary

Produces a human-readable, progressive-disclosure overview of unfamiliar code or a pull request's changes — why it exists (the real problem it solves or goal it serves for the business or a user), and from there what it does, how it flows, and where to start — so you can get up t

Files · 1

View on GitHub

SKILL.md

1	## Project Context
2
3	- git installed: !`which git 2>/dev/null \|\| echo "not installed"`
4	- gh installed: !`which gh 2>/dev/null \|\| echo "not installed"`
5	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
6	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
7
8	## Operating Principles
9
10	Read these before doing anything. They constrain every step below.
11
12	- "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.
13	- 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:readability-editor` rewrites the corrected draft against the shared readability standard, preserving every fact; the skill applies the validator's corrections and the editor's rewrite. The skill itself produces the grouping, the charts, the orientation, and the final rewrite.
14	- The overview applies the shared readability standard. As it writes and refines the overview, the skill loads and applies [`../../references/readability-rule.md`](../../references/readability-rule.md), holding the default audience frame: a capable reader who did not do this work and lacks the author's context. The standard governs how the overview reads (main point first, descriptive headings, one idea per paragraph, progressive disclosure), never whether a required fact about the code appears. Its dedicated `han-core:readability-editor` pass (Step 7) replaces the older information-architect / junior-developer readability review; the accuracy validator is a separate pass and stays.
15	- 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.
16	- 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 t

People who liked this also viewed

6 picks

Type

code-overview

122stars12forks

View on GitHub

How to install code-overview?

testdouble/han/code-overview

$npx -y skills add testdouble/han --skill code-overview

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Project Context
2
3	- git installed: !`which git 2>/dev/null \|\| echo "not installed"`
4	- gh installed: !`which gh 2>/dev/null \|\| echo "not installed"`
5	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
6	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
7
8	## Operating Principles
9
10	Read these before doing anything. They constrain every step below.
11
12	- "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.
13	- 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:readability-editor` rewrites the corrected draft against the shared readability standard, preserving every fact; the skill applies the validator's corrections and the editor's rewrite. The skill itself produces the grouping, the charts, the orientation, and the final rewrite.
14	- The overview applies the shared readability standard. As it writes and refines the overview, the skill loads and applies [`../../references/readability-rule.md`](../../references/readability-rule.md), holding the default audience frame: a capable reader who did not do this work and lacks the author's context. The standard governs how the overview reads (main point first, descriptive headings, one idea per paragraph, progressive disclosure), never whether a required fact about the code appears. Its dedicated `han-core:readability-editor` pass (Step 7) replaces the older information-architect / junior-developer readability review; the accuracy validator is a separate pass and stays.
15	- 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.
16	- 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 t

People who liked this also viewed

6 picks

Type