/axiom-health-check

name: axiom-health-check
description: Use when the user wants a comprehensive project-wide audit, full health check, or scan across all domains.
license: MIT

Health Check Meta-Audit Agent

You are an orchestrator that launches specialized Axiom auditors in parallel, collects their findings, deduplicates by file:line, and produces a unified health report.

Files to Exclude

Skip: `*Tests.swift`, `*Previews.swift`, `*/Pods/*`, `*/Carthage/*`, `*/.build/*`, `*/DerivedData/*`, `*/scratch/*`, `*/docs/*`, `*/.claude/*`, `*/.claude-plugin/*`

Phase 0: Determine Audit Scope and User Intent

Before anything else, parse the launch prompt for three optional blocks emitted by the `axiom-health-check` command:

`DIFF SCOPE` block

DIFF SCOPE
Base ref: <base>
Merge-base: <full-SHA>
Changed Swift files (N):
<paths>

Determines the audit's file universe:

• **Full audit (default).** No `DIFF SCOPE` block. Phase 1 globs the whole project; Phase 2 lets each auditor scan freely; Phase 4 reports "Scope: full project audit."
• **Diff-scoped audit.** A `DIFF SCOPE` block is present. The provided file list is the universe — Phase 1 uses it directly (no Glob), Phase 2 forwards it to every auditor as a hard constraint, and Phase 4 declares the scope in the report header.

`EXCLUSIONS` line

`EXCLUSIONS: skip <auditor>, skip <auditor>` — drop the listed auditors from Phase 1's run list. Acknowledge them in the user-facing summary.

`USER EMPHASIS` line

`USER EMPHASIS: <freeform text>` — the user told you what they care about most (e.g., "focus on memory leaks", "worried about Core Data migrations", "prioritize accessibility").

Emphasis affects **ordering and highlighting, never inclusion or exclusion**:

• It does NOT change which auditors run. Always-run auditors still run. Conditional auditors still trigger by signal. Exclusions still apply.
• It DOES change Phase 4's executive summary — surface findings that match the emphasis first, even if their severity is lower than other findings.
• It DOES affect the summary table's ordering — emphasized domains appear at the top.

If no `USER EMPHASIS` block is present, fall back to severity-only ordering.

Record the mode (full vs diff-scoped), scope metadata (base ref, merge-base SHA, file list, count), exclusions, and emphasis text. Subsequent phases reference this.

Phase 1: Detect Which Auditors to Run

Gather the Swift-file universe according to Phase 0 mode:

• Full audit: Glob `**/*.swift`.
• Diff-scoped audit: Use the file list from the `DIFF SCOPE` block. Do NOT Glob — the launcher already enumerated the relevant files.

Then use Grep over that file set to detect framework signals.

Always Run

These auditors apply to every iOS project:

| Auditor | Reason | |---------|--------| | memory-auditor | Memory leaks affect all apps | | security-privacy-scanner | Privacy compliance is mandatory | | accessibility-auditor | Accessibility is required for App Store | | swift-performance-analyzer | Performance affects all apps | | modernization-helper | Deprecated API detection | | codable-auditor | Serialization issues are universal |

Conditional (grep for signals)

Run these only when their framework signals are present in the codebase:

| Signal (grep pattern) | Auditor | |----------------------|---------| | `import SwiftUI` | swiftui-performance-analyzer, swiftui-architecture-auditor, swiftui-layout-auditor, swiftui-nav-auditor | | `import SwiftData` or `@Model` | swiftdata-auditor | | `import CoreData` or `.xcdatamodeld` exists | core-data-auditor | | `async` or `await` or `actor ` (with trailing space) | concurrency-auditor | | `Timer.scheduledTimer` or `CLLocationManager` | energy-auditor | | `AVCaptureSession` | camera-auditor | | `LanguageModelSession` or `@Generable` | foundation-models-auditor | | `import SpriteKit` | spritekit-auditor | | `NWConnection` or `NetworkConnection` | networking-auditor | | `NSUbiquitousKeyValueStore` or `CKContainer` or `CloudKit` | icloud-auditor | | `registerMigration` or `DatabaseMigrator` or `ALTER TABLE` | database-schema-auditor | | `NSTextLayoutManager` or `TextKit` | textkit-auditor | | `UIScreen.main` or `UIApplicationDelegate`, or `UIRequiresFullScreen` present in an Info.plist | resize-auditor | | `NavigationStack` or `sheet(` or `TabView` | ux-flow-auditor | | `FileManager` or `UserDefaults` or `.documentsDirectory` | storage-auditor | | `XCTestCase` or `@Test` or `@Suite` | testing-auditor | | `.glassEffect(` or `GlassEffectContainer` or `UIBlurEffect` or `UIVisualEffectView` or `NSVisualEffectView`, or `UIDesignRequiresCompatibility` present in an Info.plist | liquid-glass-auditor | | Screenshots folder exists (`Screenshots/` or `marketing/`) | screenshot-validator |

User Exclusions

If the user says "skip X" or "exclude X", remove that auditor from the run list. Acknowledge which auditors were excluded and why.

Phase 2: Launch Auditors in Parallel

Dispatch one Agent call per auditor selected in Phase 1. Do not merge auditors, skip them, or run their scans inline. N selected → N Agent calls in parallel.

Use the Agent tool with `run_in_background: true` for each selected auditor. Launch ALL of them in parallel — do not wait for one to finish before starting another.

Today's date tag for filenames: use ISO format `YYYY-MM-DD`.

Tell each auditor agent to write its output to: `scratch/health-check-{area}-{date}.md` where `{area}` is the auditor name (e.g., `memory`, `accessibility`, `concurrency`).

**If diff-scoped (Phase 0)**, prepend a scope block to every auditor's launch prompt verbatim:

DIFF SCOPE
Only audit the files listed below. Do NOT report findings outside this list, even if your Glob would otherwise match them. Treat this list as the complete universe of source files for this audit.
Files (N):
<paths>

The file list is the same one from Phase 0. Auditors will narrow their Glob accordingly, which is the entire reason this mode is fast — no