Autopsy

autopsy

Purpose

Full codebase health assessment for legacy projects. Autopsy analyzes complexity, dependency coupling, dead code, tech debt, and git hotspots to produce a health score per module and a prioritized rescue plan. Uses opus for deep analysis quality.

Called By (inbound)

• rescue (L1): Phase 0 RECON — assess damage before refactoring
• onboard (L2): when project appears messy during onboarding
• audit (L2): Phase 3 code quality and complexity assessment
• incident (L2): root cause analysis after containment

Calls (outbound)

• scout (L2): deep structural scan — files, LOC, entry points, imports
• research (L3): identify if tech stack is outdated
• trend-scout (L3): compare against current best practices
• journal (L3): record health assessment findings

Execution Steps

Step 0 — Repo intelligence (if GitHub-hosted)

If the project is a GitHub repository, gather repo-level metrics before diving into code:

bashCopy code
# Fetch via GitHub API (requires gh CLI or curl + GITHUB_TOKEN)
gh api repos/{owner}/{repo} --jq '{stars: .stargazers_count, forks: .forks_count, open_issues: .open_issues_count, license: .license.spdx_id, language: .language, topics: .topics, created: .created_at, pushed: .pushed_at}'

# Contributor count and top contributors
gh api repos/{owner}/{repo}/contributors --jq 'length' 
gh api repos/{owner}/{repo}/contributors --jq '.[0:5] | .[] | "\(.login): \(.contributions)"'

# Commit frequency (last 52 weeks)
gh api repos/{owner}/{repo}/stats/commit_activity --jq '[.[] | .total] | add'

# Language byte distribution
gh api repos/{owner}/{repo}/languages

Record in working notes:

• Activity signal: commits/week (>5 = active, 1-5 = maintained, <1 = stale)
• Bus factor: contributor count (1 = critical risk, 2-3 = low, >5 = healthy)
• Community signal: stars/forks ratio, open issue count, staleness of latest push

Skip this step for local-only projects with no remote.

Step 1 — Structure scan

Call rune:scout with a request for a full project map. Ask scout to return:

• All source files with LOC counts
• Entry points and main modules
• Import/dependency graph (who imports who)
• Test files and their coverage targets
• Config files (tsconfig, eslint, package.json, etc.)

Step 2 — Module analysis

For each major module identified by scout, use Read to open the file and assess:

• LOC (flag anything over 500 as a god file)
• Function count and average function length
• Maximum nesting depth (flag > 4 levels)
• Cyclomatic complexity signals (deep conditionals, many branches)
• Test file presence and estimated coverage

Record findings per module in a working table.

Step 3 — Health scoring

Score each module 0-100 across six dimensions:

Compute weighted score per module. Assign risk tier:

• 80-100 = healthy (green)
• 60-79 = watch (yellow)
• 40-59 = at-risk (orange)
• 0-39 = critical (red)

Step 4 — Risk assessment

Use Bash to gather git archaeology data:

bashCopy code
# Most changed files (hotspots)
git log --format=format: --name-only | sort | uniq -c | sort -rg | head -20

# Files not touched in over a year
git log --before="1 year ago" --format="%H" | head -1 | xargs -I{} git diff --name-only {}..HEAD

# Authors per file (high author count = high churn risk)
git log --format="%an" -- <file> | sort -u | wc -l

# Commit velocity by month (trend detection)
git log --format="%Y-%m" | sort | uniq -c | tail -12

# Issue/PR close rate (GitHub only)
gh api repos/{owner}/{repo}/issues --jq '[.[] | select(.pull_request == null)] | length'

Identify:

• Circular dependencies (A imports B, B imports A)
• God files (> 500 LOC with many importers)
• Hotspot files (changed most often = highest bug density)
• Dead files (no importers, no recent commits)
• Velocity trend: accelerating, stable, or decelerating (compare last 3 months)

Step 5 — Generate RESCUE-REPORT.md

Use Write to save RESCUE-REPORT.md at the project root with this structure:

markdownCopy code
# Rescue Report: [Project Name]
Generated: [date]

## Overall Health: [score]/100

## Module Health
| Module | Score | Complexity | Coverage | Coupling | Risk | Priority |
|--------|-------|-----------|----------|----------|------|----------|
| [name] | [n]   | [low/med/high] | [%] | [low/med/high] | [tier] | [1-N] |

## Dependency Graph
[Mermaid flowchart of module coupling — use subgraphs for clusters]

## Language Distribution
[Mermaid pie chart — e.g., pie title Languages "TypeScript" : 65 "JavaScript" : 20 "CSS" : 15]

## Commit Velocity (Last 12 Months)
[Trend: accelerating / stable / decelerating — include monthly commit counts]

## Repo Intelligence (GitHub only)
| Metric | Value | Signal |
|--------|-------|--------|
| Stars | [n] | [community interest level] |
| Contributors | [n] | [bus factor: critical/low/healthy] |
| Open issues | [n] | [maintenance signal] |
| Commits/week | [n] | [activity: active/maintained/stale] |
| Last push | [date] | [freshness] |

## Surgery Queue (Priority Order)
1. [module] — Score: [n] — [primary reason] — Suggested pattern: [pattern]
2. ...

## Git Archaeology
- Hotspot files: [list with change frequency]
- Stale files: [list with age]
- Dead code candidates: [list]

## Immediate Actions (Before Surgery)
- [action 1]
- [action 2]

Call rune:journal to record that autopsy ran, the overall health score, and the surgery queue.

Step 5b — Emit comprehension.json

Write .rune/comprehension.json conforming to compiler/schemas/comprehension.schema.json. This is ADDITIVE — do not modify RESCUE-REPORT.md or any other output.

Populate from the module analysis already completed in Steps 1–4:

jsonCopy code
{
  "project": "<project name>",
  "generated_at": "<ISO 8601 timestamp>",
  "source": "autopsy",
  "health_score": <overall score 0-100 from Step 3>,
  "layers": [
    { "id": "<layer-id>", "name": "<human name>", "color": "<code|service|data|domain|docs|infra|concept>" }
  ],
  "domains": [],
  "modules": [
    {
      "id": "<relative file path>",
      "name": "<module name>",
      "layer": "<layer id>",
      "type": "file",
      "complexity": "<simple|moderate|complex — map from health score: 80+=simple, 60-79=moderate, <60=complex>",
      "files": 1,
      "summary": "<one-line health finding — e.g. 'Score 42/100 — high cyclomatic complexity, no tests'>"
    }
  ],
  "edges": []
}

Rules:

• modules[] — include ALL modules scored in Step 3 (this is the full health inventory, not just entry points).
• layers[] — derive from the project's architectural layers detected by scout.
• health_score — MUST be the weighted overall score computed in Step 3, not an estimate.
• edges[] — leave empty; autopsy does not trace cross-file dependencies (that is the visualizer's job).
• Overwrite any existing .rune/comprehension.json — this is a generated emit, not human-written content.

Step 6 — Report

Output a summary of the findings:

• Overall health score and tier
• Count of critical, at-risk, watch, and healthy modules
• Top 3 worst modules with scores and recommended patterns
• Confirm RESCUE-REPORT.md was saved
• Recommended next step: call rune:safeguard on the top-priority module

Confidence Scoring

Every finding in the autopsy report MUST carry a confidence level:

Rules:

• Health scores backed by actual code metrics → High confidence
• Health scores using git archaeology only (no code read) → Medium confidence
• Health scores for modules where files couldn't be read (binary, encrypted, too large) → Low confidence
• Overall report confidence = weighted average of module confidences (by LOC weight)
• Include confidence in RESCUE-REPORT.md header: Confidence: [High|Medium|Low] ([n]%)

Multi-Round Analysis

Autopsy follows a broad-to-narrow pattern to avoid missing systemic issues:

1. Round 1 — Surface scan (Steps 0-1): Repo metrics + structure map. Goal: identify scope and major clusters.
2. Round 2 — Module deep dive (Steps 2-3): Read and score each module. Goal: quantified health per module.
3. Round 3 — Cross-cutting analysis (Step 4): Git archaeology + dependency graph. Goal: find systemic risks invisible at module level (circular deps, hotspot clusters, bus factor).
4. Round 4 — Synthesis (Steps 5-6): Combine all rounds into prioritized report. Findings from later rounds may revise earlier scores.

Do NOT skip rounds. Round 3 cross-cutting analysis frequently reveals risks that per-module analysis misses (e.g., a "healthy" module that is the single point of failure for 10 others).

Health Score Factors

Copy code
CODE QUALITY    — cyclomatic complexity, nesting depth, function length
DEPENDENCIES    — coupling, circular deps, outdated packages
TEST COVERAGE   — line coverage, branch coverage, test quality
DOCUMENTATION   — inline comments, README, API docs
MAINTENANCE     — git hotspots, commit frequency, author count
DEAD CODE       — unused exports, unreachable branches

Output Format

Copy code
## Autopsy Report: [Project Name]

### Overall Health: [score]/100 — [tier: healthy | watch | at-risk | critical]

### Module Summary
| Module | Score | Risk | Priority |
|--------|-------|------|----------|
| [name] | [n]   | [tier] | [1-N] |

### Top Issues
1. [module] — [primary finding] — Recommended pattern: [pattern]

### Next Step
Run rune:safeguard on [top-priority module] before any refactoring.

Constraints

1. MUST scan actual code metrics — not estimate from file names
2. MUST produce quantified health score — not vague "needs improvement"
3. MUST identify specific modules with highest technical debt — ranked by severity
4. MUST NOT recommend refactoring everything — prioritize by impact
5. MUST check: test coverage, cyclomatic complexity, dependency freshness, dead code

Sharp Edges

Known failure modes for this skill. Check these before declaring done.

Done When

• scout completed with full project map (all files, entry points, import graph)
• All major modules scored across all 6 dimensions
• Git archaeology run (hotspots, stale files, dead code candidates identified)
• RESCUE-REPORT.md written to project root with Mermaid dependency diagram
• .rune/comprehension.json written with health_score populated + all scored modules in modules[] conforming to comprehension.schema.json
• journal called with health score and surgery queue
• Autopsy Report emitted with overall health tier and top-3 issues

Returns

Cost Profile

~5000-10000 tokens input, ~2000-4000 tokens output. Opus for deep analysis. Most expensive L2 skill but runs once per rescue.

Scope guardrail: autopsy assesses — it does not refactor. All surgery is delegated to surgeon after the report is complete.

Executive Mode (--executive)

When invoked as /rune autopsy --executive, generate a board-ready HTML health assessment. Requires Business tier.

Executive Execution Steps

1. Standard Autopsy: Run Steps 1-5 (structure scan, module analysis, health scoring, risk assessment, RESCUE-REPORT.md)
2. Org Context: Read .rune/org/org.md for team structure and governance level
3. Cross-Domain Impact: Map module health to business domains (which team owns which modules)
4. Business Risk Translation: Convert technical health scores to business risk language:
   • Critical modules in revenue path → "Revenue infrastructure at risk"
   • Low test coverage on auth → "Security compliance gap"
   • High churn in customer-facing code → "Customer experience degradation risk"
5. HTML Render: Load report-templates/autopsy-executive.html from Business pack and populate all {{placeholder}} fields:
   • SVG health ring (score → stroke-dasharray calculation: score / 100 * 440)
   • Dimension bars (6 dimensions with color coding)
   • Module table (sorted by priority)
   • Surgery queue (top 5 modules)
   • Risk matrix (6 categories)
   • Git archaeology summary
   • Cross-domain impact table
   • Recommended actions (numbered, prioritized)
6. Save: Write HTML to EXECUTIVE-HEALTH.html at project root

Executive Output

Copy code
EXECUTIVE-HEALTH.html          — Board-ready HTML report
RESCUE-REPORT.md               — Detailed technical report (standard autopsy)
.rune/retros/{date}.json       — Health metrics for trend tracking

Color Coding

Graceful Degradation

• If no Business pack installed: skip executive mode, produce standard RESCUE-REPORT.md only
• If .rune/org/org.md missing: skip team mapping, show modules without domain ownership
• If org teams don't map to code modules: show "Unmapped" in cross-domain table

External Repo Mode (--external)

When invoked as /rune autopsy --external <github-url>, evaluate someone else's repo for dependency / fork / contribution decisions. Different use case from rescue mode: you cannot run their tests, cannot rely on local Read, and the decision frame is "should I trust this?" not "how do I rescue this?".

When to use --external

• Evaluating a library before adding it as a dependency
• Deciding whether to fork an abandoned project
• Choosing between competing implementations (autopsy --external A vs B)
• Diligence on a candidate acquisition target
• Pre-graft assessment (cross-skill: feeds into graft)

External Execution Steps

Step 1 — Repo Intelligence (no local clone needed)

Use gh api exclusively — do NOT git clone. Faster + cleaner.

bashCopy code
URL="$1"  # e.g., github.com/anthropics/claude-code
OWNER_REPO=$(echo "$URL" | sed -E 's|https?://github.com/||; s|/$||')

# Core metadata
gh api "repos/${OWNER_REPO}" --jq '{
  name, full_name, description, language, license: .license.spdx_id,
  stars: .stargazers_count, forks: .forks_count, watchers: .subscribers_count,
  open_issues: .open_issues_count, default_branch,
  created: .created_at, updated: .updated_at, pushed: .pushed_at,
  archived, disabled, topics
}'

# Maintainer responsiveness (issue + PR close rates)
gh api "repos/${OWNER_REPO}/issues?state=closed&per_page=100" --jq '
  [.[] | select(.pull_request == null) | (.closed_at | fromdateiso8601) - (.created_at | fromdateiso8601)] | add / length / 86400'   # avg days-to-close

gh api "repos/${OWNER_REPO}/pulls?state=closed&per_page=100" --jq '
  [.[] | select(.merged_at != null) | (.merged_at | fromdateiso8601) - (.created_at | fromdateiso8601)] | add / length / 86400'   # avg PR merge time

# Release cadence (last 10 releases)
gh api "repos/${OWNER_REPO}/releases?per_page=10" --jq '[.[] | {tag: .tag_name, published: .published_at, prerelease}]'

# Security advisories
gh api "repos/${OWNER_REPO}/security-advisories" --jq 'length' 2>/dev/null || echo "0"

# Dependabot alerts (if accessible — usually not for external repos)
gh api "repos/${OWNER_REPO}/dependabot/alerts" --jq 'length' 2>/dev/null || echo "n/a"

Step 2 — Decision Rubric (not Health Scoring)

External evaluation uses a DIFFERENT rubric than internal rescue. Internal cares about complexity; external cares about TRUST.

Score 0-100 across five dimensions:

Composite score with same risk tiers as internal mode (80+ healthy, 60-79 watch, 40-59 at-risk, 0-39 critical).

Step 3 — Architecture Extraction (without reading every file)

You can't Read every file in an external repo. Extract architecture via metadata:

• Top-level structure via gh api repos/X/Y/contents/ (folder names = module boundaries)
• Tech stack via root manifest files: package.json (deps), Cargo.toml, go.mod, pyproject.toml, requirements.txt. Fetch with gh api repos/X/Y/contents/package.json --jq .content | base64 -d
• Test infrastructure via existence of tests/, __tests__/, *_test.go, etc. (use gh api repos/X/Y/git/trees/HEAD?recursive=1 --jq '.tree[].path' | grep -E '_test|spec')
• CI config via .github/workflows/, .gitlab-ci.yml, etc. (presence = quality signal; recent green builds via gh api repos/X/Y/actions/runs?status=success&per_page=5)
• Documentation depth via README size + docs/ folder existence
• ADRs via search: gh api search/code -X GET --field q="repo:owner/repo path:docs filename:adr*"

Step 4 — Comparative Mode (optional)

When called as /rune autopsy --external A --external B, produce side-by-side comparison:

markdownCopy code
| Dimension       | Repo A        | Repo B        | Winner |
|-----------------|---------------|---------------|--------|
| Activity        | 95 (active)   | 30 (stale)    | A      |
| Maintainership  | 80            | 60            | A      |
| Adoption        | 70            | 90            | B      |
| License         | 100 (MIT)     | 40 (GPL)      | A      |
| Security        | 100 (clean)   | 85 (1 open)   | A      |
| **Composite**   | **89**        | **57**        | **A**  |

Recommendation: A — significantly healthier on 4/5 dimensions.

Step 5 — Output

Write EXTERNAL-REPO-REPORT.md at project root (or operator-specified path):

markdownCopy code
# External Repo Evaluation: [owner/repo]
Generated: [date]
Decision: [DEPEND | FORK | CONTRIBUTE | AVOID]
Composite Score: [N]/100 ([tier])

## Quick Verdict
[1-2 sentence summary of why this score]

## Decision Rubric (5 dimensions)
[Table per Step 2]

## Activity Signal
- Last push: [date]
- Commits last 90 days: [N]
- Trend: [accelerating | stable | decelerating]

## Maintainership Signal
- Contributor count: [N] ([bus factor: critical/low/healthy])
- Avg issue close: [N] days
- Avg PR merge: [N] days
- Top contributor: [@user] ([N]% of commits — concentration risk if > 80%)

## Adoption Signal
- Stars: [N] · Forks: [N] · Watchers: [N]
- Dependent repos: [N]
- Notable users: [list if known via gh dependents API or readme mentions]

## License
- SPDX: [identifier]
- Compatibility: [compatible with our project's license | flag legal review]

## Security
- Open advisories: [N]
- Recent CVEs: [count + latest date]
- Audit log flags: [force-push events / suspicious releases / none]

## Architecture (extracted, not read)
- Tech stack: [languages + frameworks from manifest]
- Test infrastructure: [present | absent]
- CI status: [N recent green builds | failing | none configured]
- Documentation depth: [README size + docs/ folder presence]

## Confidence
[High | Medium | Low] — based on API data completeness; external mode confidence rarely exceeds Medium because we cannot run tests or read every file.

## Recommendation
[DEPEND | FORK | CONTRIBUTE | AVOID] with rationale grounded in the dimensions above. If FORK is recommended, link to the activity signal showing why (e.g., "last push > 1 year + 12 unaddressed PRs + critical bug filed").

External Mode Constraints

1. MUST use gh api only — do NOT git clone (external mode is API-driven by design; clones add ~30 seconds + disk usage for no analytical gain)
2. MUST compute all 5 dimensions OR explicitly mark "insufficient data" for any that can't be measured (e.g., no advisories endpoint access)
3. MUST cap confidence at Medium for external evaluations — internal Read-based scoring is High; external API-only is Medium at best
4. MUST output decision verdict (DEPEND / FORK / CONTRIBUTE / AVOID) — not "needs more research"
5. MUST flag license compatibility if SPDX is null, GPL, or proprietary
6. MUST NOT skip Security dimension even if API returns empty — explicitly note "no advisories found" vs "advisories endpoint inaccessible"

Graceful Degradation (External Mode)

• If gh CLI not authenticated: fall back to curl with GITHUB_TOKEN env var; document rate-limit risk (60 unauth / 5000 auth per hour)
• If repo is private + no auth: report partial — public-API-only signals; flag confidence as Low
• If repo is fork: trace upstream and offer "compare with upstream" sub-option
• If repo is archived: auto-flag — composite caps at 30 regardless of other dimensions; archived repos are AVOID by default unless operator overrides

Hand-offs (External Mode)

External evaluation produces a verdict that flows to other skills:

• DEPEND → cross-skill: dependency-doctor for vulnerability scan integration
• FORK → cross-skill: graft to plan the fork + adapt
• CONTRIBUTE → cross-skill: review-intake (PR-style workflow for the contribution)
• AVOID → terminate; document rationale in .rune/decisions/