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 .xcodeproj -scheme "" -configuration Debug build 2>&1 \
  | grep -E "warning:" | sort -u

If the build is incremental (returned in 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 ### without the N.M` prefix.

• Numbers are stable across edits. If a finding is removed during revision, leave the number and write _REMOVED: _ 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 `` 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 
- **Location:** `path/to/file.swift:LINE-LINE`
- **What:** 
- **Why:** 
- **Action:** 
- **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 . 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 `` 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jazzychad
• Source: jazzychad/ios-code-audit
• License: MIT

Install and usage instructions live in the source repository linked above.