Ios Code Audit

iOS Code Audit Skill

Operating rules

• Read-only investigation, single deliverable. No code changes — the output is CODE_AUDIT.md at the repo root.
• Every finding cites `path/to/file.swift:LINE` (or a line range). "Throughout the codebase" is never acceptable for a Critical or High item.
• Severity is assigned conservatively. Critical means crash / data loss / memory corruption / security exposure. Don't inflate. See the severity guide below.
• Verify every Critical claim before propagating. Agents will sometimes overstate severity. Open the cited file and confirm the bug is real. If you can't reproduce the claim by reading the lines, demote or drop.
• Group by root cause, not by occurrence. If one missing @MainActor annotation triggers seven warnings, that's one finding listing the seven sites, not seven findings.
• `Dead/` (or any explicitly-archived directory) is excluded. Check CLAUDE.md / project README for any "do not edit" directories before launching agents.

Workflow

Step 1 — Scope the codebase

Quick measurements to brief the agents:

find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" -not -path "*/Pods/*" -not -path "*/.build/*" | xargs wc -l 2>/dev/null | tail -1
find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" 2>/dev/null | wc -l
find . -name "*.metal" 2>/dev/null | wc -l

Also identify the hot-spot files (largest LOC, central state):

find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" -exec wc -l {} \; | sort -rn | head -10

Read CLAUDE.md if present — it usually flags central state files (e.g., AppState.swift, CaptureState.swift), the rendering pipeline, and any intentionally-excluded directories.

Step 2 — Capture compiler ground truth

Run a build and extract every warning. This becomes the canonical input for the concurrency / deprecation portions of the audit — you should never have to guess whether concurrency warnings exist.

Preferred (Xcode MCP, if connected):

mcp__xcode__XcodeListNavigatorIssues(tabIdentifier, severity: "warning")

This returns a structured list with path, line, message, severity. Deduplicate (multi-target compilation produces duplicates) and bucket by root cause.

Fallback (`xcodebuild` from CLI):

xcodebuild -project <Project>.xcodeproj -scheme "<Dev scheme>" -configuration Debug build 2>&1 \
  | grep -E "warning:" | sort -u

If the build is incremental (returned in <2s), it likely skipped most files. Touch a Swift file under each target or run clean build to get a complete warning set.

Step 3 — Launch the three parallel Explore agents

One message, three tool calls. Each agent gets a focused brief from references/agent-prompts.md:

• Agent A — Concurrency & API modernity. Feed it the warnings captured in Step 2.
• Agent B — Dead code, duplication, refactor candidates. Feed it the hot-spot list and any known-stale files from CLAUDE.md.
• Agent C — Bugs, logic errors, security, performance. Feed it the hot-spot list and any specific subsystems the user has called out (camera pipeline, IAP, API client, etc.).

Each brief enforces the per-finding template (see below). Do not let agents return summaries — insist on specific file:line findings.

Step 4 — SwiftUI expert pass (if SwiftUI is in use)

If the project has SwiftUI views, invoke the swiftui-expert-skill separately after the agents return, scoped to Views/ (or wherever the SwiftUI surfaces live) plus shared UI helpers. Ask specifically for:

• @State / @Bindable / @Observable misuse
• Modifier ordering bugs
• View-body work that should be hoisted (formatters, decoders, sorts)
• Accessibility / Dynamic Type / dark-mode gaps
• Missing Equatable on hot leaf views
• Liquid Glass / iOS 26 adoption opportunities (only if requested)

You may need to read a few view files yourself to confirm patterns the skill identifies.

Step 5 — Verify the Critical findings

Before writing the report, open the cited lines for every Critical-flagged finding and confirm:

• The code matches what the agent described.
• The impact claim is real (e.g., if an agent says "memory corruption," is the buffer actually undersized? Trace the math.).
• The recommended fix is sensible.

This step has caught hallucinated severity in prior runs. Demote or drop items that don't pan out. Never propagate a Critical you haven't personally verified.

Step 6 — Synthesize CODE_AUDIT.md

Use the skeleton in references/report-template.md.

Mandatory: the rendered report must include section numbers in every heading. This is not cosmetic — it is the report's primary interface. Users file issues like "fix §5.4" and "is §3.1 done?", and they cannot do that if headings are unnumbered. Generating an unnumbered report is a defect, not a stylistic choice. Reports without numbers will be rejected.

The numbering rules:

• Top-level sections are numbered `## 1.` through `## 12.` — exactly as listed below, in this order, even if a section has no findings (in which case write "_No findings._" under the heading rather than omitting the section).
• Every finding is a numbered subsection of the form ### N.M <short title> where N is the parent section number and M increments from 1. Example: ### 5.1 Force-unwrap on Bundle.main.url, ### 5.2 Missing .limited Photos auth handling. Never emit a finding as ### <short title> without the N.M prefix.
• Numbers are stable across edits. If a finding is removed during revision, leave the number and write _REMOVED: <reason>_ as the body — do not renumber the surviving findings, or every external reference to "§5.4" breaks.
• Executive summary items (§1) are an ordered list 1., 2., … referencing the underlying numbered finding (e.g., "[Critical] Force-unwrap on Bundle.main.url — §5.1 — path:line").
• Verification entries (§12) reference findings by their subsection number, e.g., - **§5.1** — open \path\, lines 42-47.. Do not leave <N.M> placeholders from the template — fill them in.

Top-level sections, in order:

1. Executive summary — 5-10 highest-impact findings, one line each, with severity tag and a §N.M back-reference. 2. Quick wins — ≤30-minute fixes (delete stale files, remove debug prints, fix unused-let warnings, add accessibility labels). 3. Concurrency 4. API modernity — deprecations, iOS-17+ replacements 5. Bugs / logic errors 6. Security 7. Performance 8. SwiftUI / UI 9. Dead code / duplication / refactor 10. Cross-cutting recommendations — patterns worth applying repo-wide 11. What was NOT audited — explicit out-of-scope list 12. Verification — for each Critical/High, the exact lines that prove the claim

Per-finding template (note the leading N.M):

### N.M <short title>
- **Location:** `path/to/file.swift:LINE-LINE`
- **What:** <observed problem in one sentence>
- **Why:** <impact / why it matters>
- **Action:** <recommended fix; no code, reference patterns>
- **Severity:** Critical | High | Medium | Low

Total length is comprehensive but scannable — aim for 50-100 findings. Group similar occurrences under one heading if a category has many instances (list the top 5-10 specific examples plus a count of the rest).

Severity guide

• Critical — Likely to cause crashes, data loss, memory corruption, security exposure, or shipping the wrong server URL to production. Open the cited line yourself before assigning this.
• High — Real bug a user can hit; compiler warning that will become an error in a future Swift mode; a deprecated API that's actively being removed; an architectural concurrency issue.
• Medium — Performance / quality issue; refactor candidate; missing modernization with no functional bug.
• Low — Naming, cosmetic, code style, single-occurrence cleanup.

Quality bar (final check before delivering)

• [ ] Every top-level section is numbered `## 1.` through `## 12.` and every finding is a numbered subsection ### N.M <title>. Skim the rendered report — if any heading is missing its number, fix it before delivering. Reports without numbers will be rejected as defective.
• [ ] Executive summary entries reference findings by §N.M, and Verification entries do too — no literal <N.M> placeholders survived from the template.
• [ ] Every Critical and High finding has an exact line range. No "throughout the codebase."
• [ ] Concurrency findings cross-reference the actual Step-2 warning list.
• [ ] At least 3-5 Critical findings have been spot-verified by opening the cited file.
• [ ] Findings are grouped by root cause (one annotation → many warnings = one finding).
• [ ] The "What was NOT audited" section is explicit so the user knows the gaps.
• [ ] Report is ≤ ~80 distinct findings — bigger reports lose actionability.
• [ ] No code is included in the report itself — recommendations describe patterns, not implementations.
• [ ] The user can pull any single finding into a separate task without re-explaining context.

Skill output

Always write to CODE_AUDIT.md at the repo root (the user's project working directory). Overwrite if it already exists — this skill produces a snapshot, not an append log. If the user wants history they can git mv previous versions before invoking.

What this skill does NOT cover

• Algorithmic correctness of Metal kernels / domain-specific code. Surface obvious issues only; deep algorithmic review is out of scope.
• Build settings, scheme configuration, Xcode project structure. Beyond what's visible in shared schemes.
• Third-party dependency internals. SPM / CocoaPods packages are treated as black boxes.
• Test coverage assessment. Quick scan of test targets is fine; deep test review is a separate skill.
• Localization correctness. Audit can note untranslated strings but not assess wording.
• Performance profiling. The skill identifies potential hot paths (per-frame allocations, broad state, etc.) but doesn't run Instruments traces. For that, invoke swiftui-expert-skill and its trace tooling separately.

References

• references/agent-prompts.md — The three Explore-agent briefs (copy-paste-ready, fill in the project context).
• references/report-template.md — Full skeleton for CODE_AUDIT.md.

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A single Claude Code skill (ios-code-audit) that produces a CODE_AUDIT.md report for an iOS/macOS Swift project. There is no application code, build system, or test suite here — the "deliverables" are the prompts that drive an audit run against some other Swift codebase.

When the user invokes this skill, Claude is operating in the user's iOS project directory, not this one. Edits in this repo only change future audit behavior.

File layout

• SKILL.md — the skill definition and the 6-step workflow Claude follows when invoked. This is the source of truth; everything else is referenced from it.
• references/agent-prompts.md — copy-paste briefs for the three parallel Explore agents (concurrency/API modernity, dead code/duplication, bugs/security/performance). Contains a placeholder table at the bottom showing how each {PLACEHOLDER} is discovered.
• references/report-template.md — the CODE_AUDIT.md skeleton with section numbering. Section numbers (3.1, 3.2, …) are stable across edits by design so user notes referencing "§5.4" don't shift.

The three files form a single pipeline: SKILL.md drives the workflow, the agent prompts produce raw findings, and the report template structures them.

Editing rules specific to this skill

• Severity discipline is the load-bearing invariant. SKILL.md enforces a four-level guide (Critical/High/Medium/Low) and requires spot-verification of every Critical claim before it lands in the report. Don't loosen this — it's a direct response to past runs where agents overstated severity.
• The three agents must run in parallel. agent-prompts.md repeats this: "send all three in a single message with multiple Agent tool calls." If you edit the workflow, preserve the parallel-launch requirement.
• Per-finding template is identical across all three agent briefs. If you change the format (Location/What/Why/Action/Severity), update it in all three briefs and the report template in lockstep — synthesis depends on it being mechanical.
• `Dead/` (or any explicitly-archived directory) is excluded by default. The skill expects to read the audited project's own CLAUDE.md to discover excluded paths.

What the skill explicitly does not cover

Listed in SKILL.md under "What this skill does NOT cover" — Metal kernel correctness, Xcode project structure, third-party dependencies, deep test coverage, localization wording, Instruments profiling. Keep that list in sync if scope changes.

iOS Code Audit Skill

An agent skill that produces a navigable CODE_AUDIT.md for an iOS or macOS Swift project — bugs, dead code, Swift concurrency issues, deprecated APIs, security, performance, and SwiftUI quality — with every finding cited to path/to/file.swift:LINE.

The skill is READ-ONLY: it never modifies your code. It produces one deliverable, CODE_AUDIT.md, written to the root of the audited repo.

---

Who this is for

iOS and macOS Swift developers who want a one-shot, severity-graded audit of a codebase — the kind of review you'd commission before a refactor sprint, a major release, or an acquisition. The output is a single Markdown report you can hand to a teammate, file as issues, or work through over a few PRs.

---

Install

Option A — npx skills add (recommended)

npx skills add https://github.com/jazzychad/ios-code-audit --skill ios-code-audit

Option B — manual clone

git clone https://github.com/jazzychad/ios-code-audit ~/.claude/skills/ios-code-audit

Option C - local project install

In your local project directory:

mkdir -p .claude/skills && git clone https://github.com/jazzychad/ios-code-audit .claude/skills/ios-code-audit

Restart Claude Code (or run /skills to refresh) and the skill will appear as ios-code-audit.

---

What you get

CODE_AUDIT.md is structured for triage — section numbering survives edits so you can refer to findings as "§5.4" in issues or PRs. Sections include:

• Executive summary — top 5–10 highest-impact findings, one line each
• Quick wins — ≤30-minute fixes worth knocking out first
• Concurrency — Swift 6 / strict-concurrency issues, anchored to actual compiler warnings
• API modernity — deprecations and replacements available at your deployment target
• Bugs / logic errors — force-unwraps, missing auth handling, retain cycles, race conditions
• Security — hardcoded secrets, token storage, debug-vs-prod URL gating
• Performance — per-frame allocations, CIContext lifecycle, redundant decodes, main-thread hot paths
• SwiftUI / UI — @State/@Observable misuse, view-body work, accessibility gaps
• Dead code, duplication, refactor candidates — including oversized files and unresolved TODO/FIXME
• Cross-cutting recommendations — patterns worth applying repo-wide
• What was NOT audited — explicit out-of-scope list
• Verification — exact lines proving each Critical / High claim

Operating principles enforced by the skill:

• Read-only. No code is modified.
• Every Critical / High finding cites `file.swift:LINE`. "Throughout the codebase" is rejected.
• Severity is conservative. Critical means crash, data loss, memory corruption, or security exposure — and every Critical claim is spot-verified by opening the cited file before it lands in the report.
• Findings are grouped by root cause. One missing @MainActor annotation that triggers seven warnings is one finding listing the seven sites, not seven findings.

---

Dependencies

Set these up before running the skill.

1. Xcode native MCP server (recommended)

The skill uses Xcode's built-in MCP server to extract structured compiler warnings as canonical input for the concurrency and deprecation portions of the audit. Without it, the skill falls back to parsing xcodebuild output, which works but is noisier.

Enable it by following Apple's official guide: 👉 <https://developer.apple.com/documentation/xcode/giving-external-agents-access-to-xcode>

2. swiftui-expert-skill (required if your project uses SwiftUI)

Step 4 of the workflow delegates SwiftUI review to a dedicated expert skill. If your project has any SwiftUI views, install:

👉 <https://github.com/AvdLee/SwiftUI-Agent-Skill>

npx skills add https://github.com/AvdLee/SwiftUI-Agent-Skill --skill swiftui-expert-skill

If your project is pure UIKit / AppKit, this dependency is optional — the SwiftUI pass is skipped.

---

Usage

Open Claude Code in the root of your iOS/macOS Swift project and ask naturally — the skill activates on phrases like:

• "Run a code audit"
• "Comprehensive review of this codebase"
• "Find tech debt"
• "What should I clean up?"

Or invoke it explicitly:

/ios-code-audit

When the skill finishes, the report is written to <repo-root>/CODE_AUDIT.md. The skill overwrites any existing CODE_AUDIT.md — if you want to keep prior audits, git mv them first.

If your project has a CLAUDE.md that lists "do not edit" directories (e.g., Dead/, Archive/), the skill reads and excludes them automatically.

---

How it works

A 6-step workflow:

1. Scope — count Swift files / LOC, identify hot-spot files (largest, central state). 2. Capture compiler warnings — via the Xcode MCP server (preferred) or xcodebuild (fallback). This becomes canonical input for the concurrency audit, so the skill never has to guess whether a warning exists. 3. Three parallel Explore agents —

• Agent A: Concurrency & API modernity (fed the Step 2 warnings)
• Agent B: Dead code, duplication, refactor candidates
• Agent C: Bugs, logic errors, security, performance

4. SwiftUI expert pass — invokes swiftui-expert-skill against the SwiftUI surfaces (skipped if pure UIKit/AppKit). 5. Verify every Critical claim — open the cited lines and confirm. Demote or drop anything that doesn't reproduce. 6. Synthesize `CODE_AUDIT.md` — using a stable section-numbered template so findings can be referenced by ID.

The full workflow, including the per-agent briefs and the report skeleton, lives in `SKILL.md` and the `references/` directory.

---

What this skill does NOT cover

• Algorithmic correctness of domain-specific code. Obvious issues only.
• Build settings, scheme configuration, Xcode project structure beyond what's visible in shared schemes.
• Third-party dependency internals. SPM packages are treated as black boxes.
• Deep test coverage assessment. Quick scan only.
• Localization wording. The audit can flag untranslated strings but won't assess translation quality.
• Instruments / runtime profiling. The skill identifies potential hot paths but doesn't run traces. For that, use `swiftui-expert-skill` and its trace tooling separately.

---

Contributing

The three files SKILL.md, references/agent-prompts.md, and references/report-template.md form one pipeline — the per-finding template (Location / What / Why / Action / Severity) must stay identical across all three so synthesis stays mechanical. See `CLAUDE.md` for editing rules.

Issues and PRs welcome.

---

License

MIT.

Explore-Agent Briefs

The three audit agents run in parallel — send all three in a single message with multiple `Agent` tool calls so they actually parallelize. Each brief below is a template; fill in the {PROJECT_PATH}, {HOT_SPOT_FILES}, and {BUILD_WARNINGS} placeholders before sending.

All three briefs enforce the same per-finding format so synthesis is mechanical:

### <short title>
- Location: <path>:<line-range>
- What: <observed>
- Why: <impact>
- Action: <recommended>
- Severity: Critical | High | Medium | Low

Note on numbering. Agents return findings without N.M subsection numbers — the synthesis step in SKILL.md Step 6 assigns them when laying findings into the final CODE_AUDIT.md. Do not ask agents to invent numbers (you'd get collisions across the three agents), but the synthesizer MUST add the N.M prefix to every heading in the final report. See the numbering rules in report-template.md.

---

Agent A — Concurrency & API modernity

You are auditing the iOS/macOS Swift app at {PROJECT_PATH} for a comprehensive code-quality report. Your scope is **Swift concurrency** and **API modernity**.

Every finding MUST include: file path, line range, a one-sentence What, a one-sentence Why, and a one-sentence recommended Action. Do not propose code; point at problems. Be exhaustive but specific.

EXCLUDE these directories: {EXCLUDED_DIRS}

Project context:
- iOS deployment target: {IOS_TARGET} (e.g., 17+). macOS target: {MACOS_TARGET} if applicable.
- The compiler has emitted these warnings (canonical input for your concurrency audit):

{BUILD_WARNINGS}

Your tasks:

1. **Trace each compiler warning** to its surrounding code and explain root cause. Propose architectural fixes (mark a class `@MainActor`, make it an actor, introduce a Sendable snapshot type) — not code changes.

2. **Find concurrency anti-patterns the compiler may have missed**:
   - `DispatchQueue.main.async` inside async functions (should be `await MainActor.run` or `@MainActor` annotation)
   - `Task.detached` uses without cancellation handling
   - Completion-handler APIs (PhotoKit, AVFoundation, URLSession) where async equivalents exist
   - `withCheckedContinuation` wrappers that could be replaced by direct async overloads
   - `dispatchQueue.sync` / `.async` patterns that should be actors
   - `nonisolated(unsafe)` usages
   - Singletons accessed across actor boundaries

3. **Find iOS-target replacements for older APIs**:
   - PhotoKit / AVFoundation completion-handler methods with async variants
   - AVCaptureDevice.RotationCoordinator instead of orientation enums
   - `@Observable` migration completeness (any lingering `ObservableObject` / `@Published`)
   - URLSession async-await
   - `UIApplication.shared.connectedScenes` instead of `.windows`
   - Any `@available(iOS X.0, *)` guards where X is now below the deployment target

4. **Read these hot-spot files carefully** (not just grep):
{HOT_SPOT_FILES}

5. **Format response as a list of findings**, one per issue, using the template above. Aim for completeness over brevity. If a single problem manifests at multiple call sites, group them with a list of locations under one finding.

---

Agent B — Dead code, duplication, refactor candidates

You are auditing the iOS/macOS Swift app at {PROJECT_PATH} for a comprehensive code-quality report. Your scope is **dead code, duplicated code, and refactor candidates**.

Every finding MUST include: file path, line range, a one-sentence What, Why, and recommended Action. Be exhaustive but specific.

EXCLUDE these directories: {EXCLUDED_DIRS}

Project context:
- ~{LOC} LOC across {FILE_COUNT} Swift files, multi-target Xcode project. The codebase has been developed incrementally for several years.
- Known suspected stale files (verify and flag): {KNOWN_STALE_FILES}
- Known duplicated helpers (use as model for finding others): {KNOWN_DUPLICATES}

Your tasks:

1. **Find `#if false` blocks and commented-out alternates.** Use grep to locate `#if false` regions and contiguous `//`-commented Swift code blocks. For each: file:line, intent guess (obsolete vs intentional A/B), recommendation (delete vs leave with TODO).

2. **Find duplicated helpers across files.** Specifically look for:
   - Image encode/decode helpers (CIImage → JPEG/PNG, UIImage decode/orientation)
   - Thumbnail creation
   - Orientation conversion (CGImagePropertyOrientation ↔ UIImage.Orientation)
   - Palette / model serialization
   - File-path / Documents-dir construction
   - JSON encode/decode wrappers
   - Photo library album lookup / creation
   - Anything else appearing verbatim in 2+ files

3. **Find oversized files** (>500 lines). For each, propose a sensible split (e.g., "extract delegate methods into `Foo+AVCaptureDelegate.swift`").

4. **Find TODO/FIXME/HACK/XXX/`#warning` markers.** Each with file:line and a one-line summary of what's pending.

5. **Find stale files / unused code**:
   - Files with `_OLD`, `Old_`, `_v1`/`_v2`, `Legacy`, `Deprecated` in their names
   - Files where most/all content is `#if false`'d
   - Types/methods that aren't referenced anywhere (quick xref via grep)
   - Filename typos (e.g., `Extensinos.swift` instead of `Extensions.swift`)

6. **Find naming / organization inconsistencies.** Spelling mistakes in symbol names, files in the wrong folder, mixed file-organization conventions.

7. **Find `print()` calls** not behind `#if DEBUG`. Group by file with counts; flag any that wrap sensitive data.

8. **Find ad-hoc magic constants** that should be named (image dimensions, JPEG quality, retry counts, hardcoded URL strings, album names).

9. **Format response as a list of findings** using the template. If a category has many instances, list top 5-10 specific examples plus a count of the rest.

---

Agent C — Bugs, logic errors, security, performance

You are auditing the iOS/macOS Swift app at {PROJECT_PATH} for a comprehensive code-quality report. Your scope is **bugs, logic errors, security, and performance**.

Every finding MUST include: file path, line range, a one-sentence What, Why, and recommended Action. Be exhaustive but specific.

EXCLUDE these directories: {EXCLUDED_DIRS}

Project context:
- App type: {APP_TYPE} (e.g., camera app with dithering, productivity app, etc.)
- Targets: {TARGET_LIST}
- API: {API_LAYER_DESCRIPTION} (e.g., tRPC client talking to dev/prod endpoints)
- IAP: {IAP_DESCRIPTION} (e.g., StoreKit 2 / RevenueCat)
- Subsystems the user has flagged for extra scrutiny: {USER_FLAGGED_SUBSYSTEMS}

Your tasks:

1. **Bugs and logic errors.** Read these hot-spot files closely (not just grep):

{HOT_SPOT_FILES}

   Look for:
   - **Force-unwraps (`!`)** on optionals — especially in init paths, `UIImage(data:)!`, `URL(string:)!`, `Bundle.main.url(forResource:)!`
   - **Force-try (`try!`)** and **force-cast (`as!`)**, particularly in static initializers
   - **`fatalError`** in non-debug code paths
   - **Unchecked array indexing** (e.g., `arr[0]`, `palette[i]` without bounds checks)
   - **Error-eating `catch { }`** blocks
   - **Missing auth handling** — `.limited` Photos auth, `.denied`, `.notDetermined`
   - **Retain cycles** in closures (`[weak self]` missing where it should be)
   - **Race conditions** — work that should be on main but isn't (or vice versa); fetch-after-create races
   - **Async cancellation** — long-running Tasks that should be cancellable
   - **Format / UTI mismatches** in PhotoKit content editing
   - **State-init paths** — `@State` declared on passed values (silently ignores updates)

2. **Security:**
   - Hardcoded secrets, API keys, tokens — grep for `Bearer`, `apiKey`, `secret`, `Authorization`, base64 blobs
   - Auth-token storage (Keychain vs UserDefaults vs in-memory)
   - Debug vs prod URL switching mechanism — is it gated by `#if DEBUG` only? (dangerous — release builds can ship to dev)
   - User data written to disk — sane location (Documents vs Caches vs Application Support)?
   - Debug log / zip exports — verify they don't include PII, device IDs, IAP receipts
   - Entitlements files per target

3. **Performance:**
   - **Per-frame allocations** in render pipelines (Metal/CoreImage filters that allocate buffers per `outputImage` call)
   - **`CIContext` lifecycle** — fresh `CIContext()` per render is expensive
   - **Repeated JPEG/PNG re-encoding** during slider drags / live editing
   - **Full image decode for metadata only** (`UIImage(data:)` to extract orientation when `CGImageSource` is cheaper)
   - **Synchronous PhotoKit / large-collection fetches** on main thread
   - **AVCapture session reconfiguration churn** on parameter changes
   - **Heavy work in SwiftUI view body** (formatters, sorts, decodes that should be cached)

4. **Format response as a list of findings** using the template.

Severity guide:
- **Critical** = will likely cause crashes, data loss, or security exposure.
- **High** = real bug a user can hit; security issue (token leak, etc.); deprecated API blocking future builds.
- **Medium** = perf issue, refactor candidate, missing modernization.
- **Low** = code style, naming, single-occurrence cleanup.

If a single root cause manifests in many sites, group with a list of locations under one finding.

---

Placeholder discovery (how to fill the templates)

CODE_AUDIT.md Skeleton

Copy this structure into <repo-root>/CODE_AUDIT.md and fill in.

## ⚠️ Numbering is mandatory

>

Every top-level section MUST render as ## 1. Executive summary, ## 2. Quick wins, … ## 12. Verification — with the number in the heading text. Every finding MUST render as ### N.M <title> (e.g., ### 5.1 Force-unwrap on Bundle.main.url).

>

The numbers are the report's primary interface — users open issues like "fix §5.4" and the report is unusable without them. Do not emit headings as `### <title>` or `## Executive summary` without the leading number. If a section has no findings, keep its numbered heading and write _No findings._ underneath.

>

Numbers are stable: when revising, leave removed findings as ### 5.4 _REMOVED: <reason>_ rather than renumbering survivors.

# <App Name> Code Audit

Generated <YYYY-MM-DD>. Scope: ~<N> Swift files + <M> Metal/other kernels across <list of targets>. `<excluded dirs>` are excluded by request (intentional archive per `CLAUDE.md`).

Findings cite `path/to/file.swift:LINE` so you can jump straight to them in Xcode. Each item has a recommended action; no code changes were made.

---

## 1. Executive summary

Top items to address, in priority order:

1. **[Critical] <one-line title>** — `path:line`. <one-sentence consequence>.
2. **[Critical] <…>** — …
3. **[Critical/Security] <…>** — …
4. **[High] <…>** — …
5. **[High] <…>** — …
6. **[High] <…>** — …
7. **[High] <…>** — …
8. **[High] <…>** — …
9. **[High] <…>** — …
10. **[High] <…>** — …

---

## 2. Quick wins (≤30 min each)

These deliver outsized value relative to effort and have no architectural ripples.

- **<action>** — `path:line`. <one-line rationale>.
- …

---

## 3. Concurrency

### 3.1 <Title — usually the root cause, e.g. "ClassFoo should be @MainActor">
- **Location:** `path:line` (and list of affected call sites if grouped)
- **What:** <observed>
- **Why:** <impact>
- **Action:** <recommendation; no code>
- **Severity:** Critical | High | Medium | Low

### 3.2 <next finding — keep the `3.2`, `3.3`, … numbering>

---

## 4. API modernity

(Deprecations, iOS-target+ replacements available.)

### 4.1 <title>

### 4.2 <…>

---

## 5. Bugs / logic errors

### 5.1 <title>

### 5.2 <…>

---

## 6. Security

### 6.1 <title>

### 6.2 <…>

---

## 7. Performance

### 7.1 <title>

### 7.2 <…>

---

## 8. SwiftUI / UI

(If the project uses SwiftUI; otherwise omit or replace with "UIKit / AppKit" — but keep the `## 8.` number.)

### 8.1 <title>

### 8.2 <…>

---

## 9. Dead code / duplication / refactor

### 9.1 Files to delete outright
- `path/to/file.swift` — <reason>.
- …
- **Severity:** High (clean up; ~<N> LOC removed)

### 9.2 <duplicated helper name>
- **Locations:** `path1:line`, `path2:line`
- **Action:** Extract to <shared location>.
- **Severity:** High | Medium

### 9.3 <…>

### 9.N Oversized files (>500 LOC)
- **`path:LOC`** — <split proposal>. Severity: High | Medium.
- …

### 9.N+1 Unresolved TODOs / FIXMEs
- `path:line` — <quoted comment>.
- …
- **Severity:** Medium

### 9.N+2 Magic constants
- <constant> at `path:line`, `path:line` — name it once.
- …
- **Severity:** Low

---

## 10. Cross-cutting recommendations

Patterns worth applying repo-wide rather than one finding at a time:

1. **<pattern>**. <one-paragraph rationale tying together multiple findings>.
2. **<pattern>**. …
3. …

---

## 11. What was NOT audited

- `<excluded dirs>` (intentional archive).
- Algorithmic correctness of <domain-specific code, e.g. Metal kernels, ML models>.
- Build settings / Xcode project structure beyond shared schemes.
- Third-party SPM/CocoaPods dependency internals (<list>).
- Tests under `<test target paths>` — quick scan only; no deep coverage review.
- The `<extension target>/` targets got light coverage. Their entitlements files were not opened; verify they match the App Group identifier used elsewhere.
- StoreKit 2 product configuration in `<.storekit file>` — file structure only, not whether each product matches App Store Connect.
- Localization and string catalogs — not assessed.
- <Anything else specifically out of scope>.

---

## 12. Verification

Spot-check pattern: open Xcode, command-click the `path:line` reference in this report — it should land on the cited line. Each Critical / High finding has an exact line range, not "scattered throughout."

For the Critical items, here are the lines that prove the claim. **Replace each `§N.M` below with the actual subsection number of the finding you're verifying — do not leave the placeholder in the rendered report.**

- **§5.1** — open `path`, lines `42-47`. <one-sentence verification — what to look at>.
- **§3.2** — open `path`, line `118`. <…>.
- **§6.1** — …

If any finding doesn't reproduce when you visit the line, ping me with the specific reference and I'll re-investigate.

Notes on filling the template

• Numbering is non-negotiable. Every ## N. <Title> heading keeps its number in the rendered report, and every finding is ### N.M <title>. The numbers are the user's primary reference scheme — a report without them is broken. Do a final pass before delivery: skim the rendered Markdown and confirm no heading is missing its prefix.
• Numbered subsections (3.1, 3.2, …) survive edits. When you delete a finding, leave the number — note "_REMOVED: <reason>_" — so the user's notes/issues that reference "§5.4" don't shift.
• Executive summary is curated, not algorithmic. Pick the 10 highest-impact items across all categories; some Critical items may not appear here if they're already obvious from another finding. Each entry should reference the underlying finding by §N.M.
• Cross-cutting recommendations is where you connect dots. If three separate findings all point at "CaptureState should be @MainActor," call that out as one repo-wide change.
• The "What was NOT audited" section is mandatory. It sets the user's expectations and prevents "you missed X" follow-ups.
• Verification section is the trust contract. For each Critical, name the literal lines the reader can open to confirm the claim. If you can't, the finding probably isn't Critical.