{
  "version": "act 2.1.1",
  "slug": "health-check",
  "name": "health-check",
  "description": "Use when asked about code health, quality trends, what's getting worse, or for a periodic quality check. Depth 1 \u2014 fast, trend-aware. Produces a health snapshot with hotspots, cohesion issues, test gaps (evidence-labeled: lcov or convention), and trend comparison if prior runs exist. Replaces the codebase-analysis skill.",
  "url": "https://act101.ai/docs/skills/health-check",
  "body_md": "# Health Check\n\n**Depth:** Level 1 (Explore).\n\nSee `../analysis-protocol/references/protocol.md` for: artifact directory structure,\nthe investigation loop, depth levels, summary format, token budget rules, and project\nmap structure. Read that document before proceeding.\n\n## Phase 1: Parallel Tool Dispatch\n\nDispatch all available tools in a **single parallel batch**.\nEach subagent runs one tool, saves raw JSON to `raw/<tool-name>.json`, returns a\nstructured summary.\n\n**Must-have tools:**\n\n| Tool | Purpose | MCP call |\n|------|---------|----------|\n| `analyze_hotspots` | Complexity ranking (H1) | `analyze_hotspots` |\n| `analyze_patterns` | Tier 1 structural smells | `analyze_patterns` (use `--tier fast`) |\n\nIf neither must-have tool is available, report that and stop.\n\n**Extended tools (use if available, skip and note in manifest if not):**\n\n| Tool | Purpose | MCP call |\n|------|---------|----------|\n| `analyze_coupling` | Instability overview | `analyze_coupling` |\n| `analyze_cohesion` | Module cohesion (H2) | `analyze_cohesion` |\n| `analyze_test_gaps` | Test coverage gaps; supply `coverage_report` for evidence-based statuses (evidence: lcov), else convention-based | `analyze_test_gaps` |\n| `analyze_inconsistencies` | Sibling pattern divergence (H5) | `analyze_inconsistencies` |\n| `scan` | AI-Code Health Score (security) + AI-config-backdoor / MCP-RCE findings | `scan` (pass `baseline` if `.act/baseline.json` is committed \u2014 see Trend Comparison). Scan auto-discovers lcov reports (coverage/lcov.info, lcov.info, target/coverage/lcov.info): when one is found, TestGap statuses are evidence-based and the `test_gaps` coverage record names the report (and flags it `stale` when older than the newest source). Repeat that record's `evidence:` clause in the report \u2014 never present convention-based statuses as coverage facts. |\n| `analyze_clones` | Duplication mass snapshot | If `scan` already ran in this workflow, source the Duplication row from its findings (cheaper \u2014 no re-run needed); otherwise call `analyze_clones` directly. Report `summary.duplicated_tokens` and `summary.clone_class_count` from the result. |\n\n## Phase 2: Follow-up (Explore depth)\n\nFrom summaries, identify the top 3-5 findings and run one targeted follow-up each:\n\n- For each top hotspot: run `skeleton` to characterize what's wrong\n- For untested high-coupling files: note the compound risk (untested + high blast radius)\n\nKeep follow-ups to one round \u2014 this is a health check, not a full audit.\n\n## Trend Comparison\n\n**Score/class trend (scan history):** if `.act/scan-history.jsonl` exists in the\nrepo, do not hand-compare scan scores across runs \u2014 run `act trends --root <repo>`\n(add `--format markdown` for the report artifact). It renders the score series,\nper-class count deltas, top movers, and an Improving/Stable/Degrading verdict with\ndocumented bands. Encourage repos without a history file to adopt\n`act scan --history-append` in CI (full scans only \u2014 scoped runs are rejected).\nCount deltas are not identity tracking; the baseline mechanism below remains the\nidentity-level security trend.\n\nCheck `docs/act/` for a prior Health Check run: look for a `manifest.json` with\n`\"skill\": \"health-check\"`. If found:\n\n1. Load the most recent prior run's `raw/hotspots.json` and `raw/coupling.json`\n2. Report deltas:\n   - New hotspots since last run (files that appeared or moved up)\n   - Resolved hotspots (files that disappeared or moved down)\n   - Coupling changes (improving = lower instability, degrading = higher)\n   - Test coverage trend (if `raw/test_gaps.json` exists in both runs; note whether statuses are lcov evidence-based or convention-based via the `evidence` field)\n\n**Security trend (scan):** do not hand-diff finding lists from a prior run's\n`raw/scan.json` \u2014 the baseline mechanism computes the deltas. If the repo has a\ncommitted `.act/baseline.json`, pass it on the Phase 1 call:\n`scan(root=<repo>, baseline=\".act/baseline.json\")`. The report's `baseline`\nsection IS the security trend:\n\n- `new` \u2014 findings not in the baseline (regressions since it was written)\n- `fixed` \u2014 baseline entries no longer found (remediated debt)\n- `baselined` \u2014 acknowledged debt still present\n\nIf no baseline exists yet, record one with `baseline_write`\n(CLI: `act scan --baseline-write`), commit it, and the next health check gets\nreal deltas. Score comparability is what the tools report: scores compare only\nacross identical scan semantics \u2014 a diff-scoped scan (`base_ref`) is never\ncomparable to a full-repo scan.\n\n**Duplication trend:** `summary.duplicated_tokens` is the comparable scalar across runs \u2014 but only when both runs used the same `min_tokens` value. Cross-threshold comparisons (e.g. a 50-token run vs. a 100-token run) are invalid and must not be stated as a trend.\n\nVerdict must reflect the trend: **Improving** / **Stable** / **Degrading** \u2014\nwhen `act trends` ran, adopt its verdict unless the artifact-diff evidence\ncontradicts it (say so explicitly if it does).\n\n## Report Structure\n\n```markdown\n# Health Check: <project name>\n\n## Health Summary\nVerdict: **Improving** / **Stable** / **Degrading**.\nOne-paragraph assessment.\nIf `scan` ran, lead with its **AI-Code Health Score** (security sub-score, 0\u2013100)\nand list any `ai_config_backdoor` / `mcp_config_rce` findings as critical items.\n\n## Duplication Snapshot\n`duplicated_tokens`: N \u2014 `clone_class_count`: N \u2014 `min_tokens`: N (sourced from scan Duplication findings or direct `analyze_clones` call).\n\n## Top Hotspots\nRanked list with skeleton context from follow-up. Severity and recommended fix.\nPer-hotspot: file path, complexity score, what skeleton revealed, recommended action.\n\n## Cohesion Issues\nLow-cohesion modules with split recommendations.\nPer-issue: module, cohesion score, suggested split boundary.\n\n## Pattern Inconsistencies\nSibling files that diverge from group conventions.\nPer-divergence: what's expected in the group, what's different in this file.\n\n## Test Gaps\nUntested files ranked by risk (coupling \u00d7 blast radius if available, else coupling alone).\nPer-gap: file path, risk factors, suggested test type.\n\n## Trend\n(Present only if prior run data exists)\n| Metric | Previous | Current | Change |\n|--------|----------|---------|--------|\n| Top hotspot score | N | N | \u2191/\u2193/= |\n| Hotspot count (top 10) | N | N | \u2191/\u2193/= |\n| Mean instability | N | N | \u2191/\u2193/= |\n| Test gap count | N | N | \u2191/\u2193/= |\n| Duplicated tokens (same min_tokens only) | N | N | \u2191/\u2193/= |\n\nWhat improved, what degraded, what's new since last run.\nIf `scan` ran with a baseline, lead the security line with the `baseline`\ncounts: `new` = regressions, `fixed` = remediated debt, `baselined` =\nacknowledged debt still present.\n\n## Suggested Fixes\nPrioritized list of specific act MCP tool calls or skills to run.\n```\n\n## Worked Example: Duplication Snapshot\n\nCall (when no prior scan in workflow):\n\n```\nanalyze_clones(min_tokens=50)\n```\n\nSummary from act repo (2026-06-12, min_tokens 50):\n\n```json\n{\n  \"summary\": {\n    \"files_analyzed\": 5392,\n    \"clone_class_count\": 8156,\n    \"duplicated_tokens\": 5067066,\n    \"min_tokens\": 50,\n    \"test_files_excluded\": 47488\n  }\n}\n```\n\nSnapshot row: `duplicated_tokens`: 5,067,066 \u2014 `clone_class_count`: 8,156 \u2014 `min_tokens`: 50. On the next health check, compare `duplicated_tokens` only if that run also uses `min_tokens=50`; a run at 100 produces a different floor and the delta is not comparable.\n\n## Project Map Updates\n\nUpdates the **\"Health Snapshot\"** section only. Appends to the Analysis History table."
}