self-assess-arch-health

name

self-assess-arch-health

description

Analyzes the real stage/wire graph self-assess-stage-map already built for architecture deficiencies — god-modules (a stage most others depend on, a bottleneck), circular dependencies between stages, and layering violations (a production stage importing a test-only/benchmark/fixture stage). Use this when the user asks to check architecture health, find god-modules or god-objects, detect dependency cycles between modules/packages, find layering or dependency-direction violations, or check whether the module boundaries are healthy. Depends on self-assess-stage-map having run first (it reads that skill's stage_graph.json, never re-deriving the graph). NOT a complexity/size ranking (use self-assess-complexity-score — that never emits pass/fail findings); NOT graph construction (self-assess-stage-map builds the graph, this judges it).

Judge the architecture the current repository actually has — as a set of pass/fail deficiency findings over the stage/wire graph self-assess-stage-map already built. This is deliberately distinct from self-assess-complexity-score (which ranks stages by size with no findings and no verdict) and from self-assess-stage-map itself (which builds the graph and never flags a deficiency in it). Strictly read-only: it reports; it never edits source.

Three deficiency classes, all computed from the graph, then confirmed against the real code:

• God-module — a stage coupled to an outsized share of all other stages (high fan-in/fan-out): a bottleneck every change risks touching.
• Cycle — a set of stages that import each other (a strongly-connected component of size ≥ 2): none can be built, tested, or released independently.
• Layering violation — a production stage importing a test-only / benchmark / example / fixture stage: shipped code reaching into test scaffolding.

Step 0 — Load settings and the graph

Read .claude/self-assess.local.md if it exists (see ${CLAUDE_PLUGIN_ROOT}/references/settings.md). If enabled: false, stop and say so. Note output_dir (default analysis/self-assess) and skip_verification (default false).

Read <output_dir>/stage_graph.json (the full-graph sidecar self-assess-stage-map writes in its Step 2 — the {stages, wires, deadEnds, observations} object, not the viewer-format stage_map.json, which only keeps a 5-edge sample per wire and can't give accurate fan-in/fan-out).

If stage_graph.json does not exist, do not invoke the workflow. Degrade gracefully: write a short ARCH_HEALTH.md and arch_health_summary.json (zero findings) noting this is Ready-with-gaps — run self-assess-stage-map first, and tell the user to run stage-map, then re-run this skill. This mirrors the self-assess-preflight verdict for arch-health.

Step 1 — Run the analysis

Preferred — Workflow orchestration. If the Workflow tool is available in this session (this skill invocation is your authorization):

Before dispatching, resolve or build the shared symbol-index snapshot. Read analysis/self-assess/current.json; if missing or its source_fingerprint no longer matches, run python3 "${CLAUDE_PLUGIN_ROOT}/scripts/build_symbol_index.py" --repo-path . --plugin-name self-assess (single-flight lock makes concurrent callers safe). For a repo well under ~50 tracked files the build overhead may not be worth it — skip this and pass symbolIndexPath: null.

Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT}/workflows/arch-health-scan.js",
  args: { repoPath: "<repo root, usually '.'>", stageGraph: <parsed contents of stage_graph.json>, symbolIndexPath: <resolved snapshot dir, or null>, skipVerification: <from settings, default false> }
})

It computes god-module / cycle / layering candidates deterministically from the graph (degree thresholds, strongly-connected components, production→test edges — the same deterministic-analysis-then-adversarial-confirm split self-assess-stage-map uses for wires), then — unless skip_verification is set — has one adversarial confirmer per candidate read the actual repo to rule out a legitimate shared kernel, an acyclic-after-all relationship, or a mislabeled stage. The confirmers are read-only by design; you write the artifact below from the structured result.

Fallback (no Workflow tool) — spawn an arch-health-auditor subagent: "Here is the stage/wire graph {stages, wires, deadEnds}; find god-modules (high fan-in/out), cycles (mutually-importing stages), and layering violations (production→test edges), then confirm each against the real code." Verify each finding yourself by reading the cited stages before including it.

Step 2 — Write the report

Create <output_dir>/ARCH_HEALTH.md:

• Summary — stages analyzed, findings by severity, findings by category (god-module / cycle / layering-violation), refuted count
• Findings table, sorted by severity: category, stage(s), description, suggested fix
• Refuted candidates — brief list (a useful negative signal: the graph looked deficient here but the code confirmed otherwise)
• If injectionFlags is non-empty, a prominent "⚠ Instruction-shaped content found" section

Also write <output_dir>/arch_health_summary.json — the sidecar self-assess-status aggregates and self-assess-portfolio reads: {"stagesAnalyzed": N, "findingsBySeverity": {...}, "byCategory": {"god-module": N, "cycle": N, "layering-violation": N}, "findings": [...]}. findingsBySeverity is copied straight from the workflow's stats.bySeverity (High/Medium/Low); byCategory from stats.byCategory.

findings is the workflow's own findings array (already computed — do not re-derive it), reshaped to the shared per-finding contract every domain sidecar now uses: {severity, title, evidence, category} — title from category (god-module / cycle / layering-violation), evidence and category copied as-is. Feeds findings-dashboard.html's findings table and self-assess-transform-brief.

Present

Report: stages analyzed, findings by severity and category, refuted count. If you degraded to "run stage-map first", say that plainly. Suggest: glow -p <output_dir>/ARCH_HEALTH.md