analyze-repo

Repository Analysis

Produce a standalone HTML audit that makes the repository's architecture, dependency pressure, and highest-impact debt visible. Every claim must trace to measured output or named files; uncertainty stays explicit.

Workflow

1. Build the evidence ledger

Inspect repository guidance and the environment before choosing commands. Exclude generated, vendored, cache, and dependency directories from source metrics. Collect:

• repository shape: source files, languages, top-level modules, entry points
• organization: feature/layer/package ownership and whether the directory layout matches the runtime and domain model
• composition: how modules collaborate, where interfaces and seams live, and whether complexity is concentrated or repeated across callers
• architecture: runtime boundaries, data flow, persistence, external systems
• dependencies: high fan-in modules, dependency direction, seam violations, and cycles when tooling can verify them
• patterns: established frontend, backend, integration, state, persistence, and design patterns; competing implementations and incomplete migrations
• hotspots: large or complex files, mixed responsibilities, TODO/FIXME clusters
• decisions: existing ADRs and consequential choices whose rationale is absent from repository documentation
• verification: test locations, test runner configuration, coverage artifacts, and CI checks

Use deterministic commands or project tooling for counts and graph claims. Record an evidence ledger with these fields:

Field	Requirement
Claim	One falsifiable statement
Evidence	Command output, configuration, or exact file/module paths
Method	How the evidence was collected
Confidence	verified, supported, or unverified

Coverage is a measured value only when a coverage artifact or executed coverage command provides it. Otherwise report test signals and label coverage Not measured.

Load references/architecture-decisions.md when consequential architecture is present. Search existing ADRs and design docs before calling a decision undocumented. Record observed choices separately from inferred rationale; missing business constraints remain questions, not findings.

Delegate broad repository exploration through the available subagent mechanism when useful. Give the explorer the ledger schema and require specific paths for every non-empty category. The parent agent owns verification of returned claims.

Done when every candidate finding has evidence and a confidence label.

2. Synthesize findings

Load the codebase-design skill and use its terms consistently. Assess modules through their interfaces, implementations, seams, adapters, depth, leverage, and locality. Reserve boundary for a domain or deployment boundary; use seam for a place where behavior can vary.

Group verified evidence into architecture, organization, composition, dependencies, patterns, hotspots, decisions, and verification. Identify established frontend/backend patterns before treating variation as inconsistency. Merge duplicate symptoms that share one root cause. Rank findings by:

1. production or security risk
2. change amplification and defect risk
3. developer friction and onboarding cost
4. low-urgency cleanup

Each finding must name the affected scope, explain its impact, and recommend a bounded next action. Separate observed facts from interpretation. Apply the deletion test to suspected pass-through modules, and call a seam real only when multiple adapters or another demonstrated variation justify it.

For consequential undocumented choices, add an ADR candidate rather than inventing rationale. Link recorded decisions to their existing ADR. Hand an unresolved candidate to the architect skill to compare options and recommend a decision; draft the ADR only after that decision is resolved and the user asks for the durable artifact.

Done when the top findings are evidence-backed, use the shared vocabulary, distinguish established patterns from accidental variation, and are ordered by impact.

3. Choose the visualization

Every report needs an architecture visualization, but no renderer is mandatory. Choose the smallest format that communicates the evidence:

• Inline SVG: preferred for a curated architecture, data-flow, or hotspot diagram. Load references/svg-patterns.md.
• Zoomable diagram: use when labels or edges cannot remain legible at report width. Load references/diagram-shell.md; its shell accepts inline SVG, including SVG pre-rendered by a graph tool.
• HTML/CSS structure: use for a simple layer stack or small relationship map that needs no freeform edges.

Generated report text must be HTML-escaped. SVG text and attributes must be XML-escaped. If a graph renderer is used, encode labels for that renderer before rendering and embed the resulting SVG rather than repository-controlled markup.

Done when the chosen visualization exposes real repository boundaries and every highlighted problem maps to a finding.

4. Generate the report

Read these references before writing:

1. references/report-design-system.md
2. references/report-components.md
3. references/html-report-template.md
4. references/architecture-decisions.md when ADRs or ADR candidates exist
5. the visualization reference selected in Step 3

Assign the path once and reuse it:

REPORT_PATH="${TMPDIR:-/tmp}/repo-analysis-$(date +%Y%m%d-%H%M%S).html"

The report must contain:

1. repository identity, analysis date, scope, and one-sentence assessment
2. measured summary with provenance and explicit unknowns
3. architecture visualization and explanatory caption
4. module-design assessment using the shared vocabulary
5. ranked findings with severity, confidence, evidence, impact, and next action
6. decision record linking existing ADRs and listing qualified ADR candidates
7. hotspot/file tour focused on the evidence, not an exhaustive file list
8. prioritized recommendations and a verification checklist

Done when the file exists, contains no unresolved template variables, and every finding rendered in the report has a matching ledger entry.

5. Render-check and deliver

Open the report through available browser automation when possible; otherwise use the platform opener (open, xdg-open, or start). Inspect the rendered page at desktop and narrow widths. Verify:

• no script, style, font, or network errors are required for core content
• architecture labels, edges, legends, and captions remain legible
• tables/cards do not overflow or hide evidence
• keyboard focus is visible on interactive controls
• light and dark color schemes preserve contrast
• zoom controls, when present, keep the caption outside the clipped viewport and work at maximum zoom and every pan extreme

Fix failures and repeat the check. Deliver the report path and summarize the top 3–5 findings with their confidence. Offer a follow-up architectural grilling session; begin it only when the user opts in.

Completion Gate

The analysis is complete only when:

• every reported claim has evidence and a confidence label
• organization, composition, and established frontend/backend patterns were inspected using the shared codebase vocabulary
• consequential choices link to an existing ADR, qualify as an ADR candidate, or state why no decision record is needed
• coverage and complexity are measured or explicitly marked unmeasured
• the report contains a renderer-appropriate architecture visualization
• repository-controlled text is encoded for its output context
• the rendered report passes desktop, narrow-width, and diagram checks
• the top 3–5 findings are ranked by impact and surfaced to the user

References Routing Table

Priority	Load when	Reference
1 — Required	Generating any report	references/report-design-system.md
1 — Required	Building report sections	references/report-components.md
1 — Required	Assembling the final HTML	references/html-report-template.md
2 — Conditional	Existing ADRs or consequential undocumented choices appear	references/architecture-decisions.md
2 — Conditional	Rendering a curated inline SVG	references/svg-patterns.md
2 — Conditional	The diagram needs zoom or pan	references/diagram-shell.md