| name | explore-report |
| description | Use when generating the explore plugin's HTML codebase report. Holds the fixed design system (template.html) and the content rules: two-pass prose-then-visuals discipline, node budgets, evidence requirements, confidence labels, and how to fill every slot. The report's look and structure never vary between repos; only the content does. |
The explore report
The report is a single self-contained HTML file: no CDN scripts, no build step, no runtime libraries. Pure black and white, system monospace. It must open offline, print to PDF, and still render in ten years. All styling, layout, and behavior live in template.html in this skill's directory. Copy it and fill the SLOT: comments; never restyle, never add libraries, never invent new sections. Every repo the user explores gets the identical artifact shape, so they can read any report in seconds.
This skill has no render.py or workflow.js: the agent hand-fills the SLOT: comments and {{...}} placeholders directly inside the copied template.html. Filling the template is the only editing allowed. Before opening the report, diff its <style> block against the shipped template.html and confirm they are byte-identical. If they differ, you restyled the template; revert the style block.
No em dashes (U+2014) in any text you write into the report. The title, thesis, prose, slot content, and badges all render to the user. Use a colon, comma, period, or parentheses.
The two-pass rule
Write the prose for each section before building its visual, and derive the visual from the prose, never the reverse. If a node or arrow is not mentioned or implied by the prose, it does not belong in the visual. This prevents hallucinated boxes and decorative complexity.
Hard budgets
- Architecture tree: ≤ 24 nodes total, ≤ 3 levels deep (container → component → selected key files). High-signal overview, not inventory. Every node path must exist in
git ls-files output.
- Design choices: 5–10 cards, no more.
- Trace: 6–12 steps.
- Watch out: 3–8 items.
- Detail-panel code excerpts: ≤ 8 lines each, at most one per node.
When the repo is large, cut nodes. Never shrink the font, never add a scrollbar, never exceed the budget.
Evidence and confidence
Every claim in the report cites its grounding: a file:line path, a commit SHA, or a config line. The three confidence labels on decision cards are fixed vocabulary:
documented: stated in the repo's own docs/ADRs/comments.historical: visible in git history (commit messages, dependency swaps, deleted code).inferred: deduced from code shape alone. Honest guesses, flagged as such.
An item with no evidence available gets cut, not hedged.
Filling the slots
| Slot | Rule |
|---|
THESIS | 2-4 sentences: what kind of system, and the one organizing idea. The hardest sentence in the report; draft it last, after all analysis. |
RUNCARD | Only commands verified to exist (in Makefile/package.json/CI/docs). Never guess a command. |
LANGBAR | Percent of LOC; compute from git ls-files + wc -l by extension (or cloc if present). |
ARCH_PROSE | Must state the dependency direction / layering rule in one sentence ("ui imports core; nothing imports ui"). |
TREE + DETAILS | Every data-d matches a detail div id. Each detail: WHAT (1 short para), WHY IT EXISTS (1 short para of design intent, not a restatement), 2-5 key file paths. Badges only where earned: entry (a real entry point), hotspot (top-decile churn), loadbear (top fan-in), fossil (untouched > 18 months but still imported). |
DECISIONS | Schema and rules in the [[decision-inference]] skill. |
TRACE_STEPS | One sentence per step + file:line in the .where span. Follow one real use case end to end. |
ICICLE | flex = LOC of each top-level dir. Fill computed at generation time on a 3-stop greyscale by share of commits in the last 12 months: dormant #e6e6e6, mid #999, hot #000 (interpolate by hand; inline the hex). On light fills add color:#000; text-shadow:none so the label stays legible. |
SEAMS | Co-changed file pairs (≥ 50% of one file's commits shared) with no import edge. Omit the subsection when none exist. |
DATA_PROSE | Omit the whole section for repos with no meaningful persistent state. |
WATCH | Bold claim + evidence path. Invariants and their violations, cycles, fossils that look load-bearing. |
Output location
Write to .explore/report-<shortsha>.html inside the target repo, then open it (open on macOS, xdg-open on Linux). The output lives in-repo (under .explore/), unlike map/investigate which write to ~/.anu/atlas/. If .explore/ is untracked, leave it that way; mention once that the user can commit or gitignore it. Reports are per-SHA so old ones remain valid snapshots.
Related: [[decision-inference]].
