# Parallel Multi-Layer Audit Pattern

## When to Use

When the user asks for a comprehensive audit of a large codebase spanning multiple layers (backend, data, player, UI, security, performance). This is a READ-ONLY inspection pattern — sub-agents only read files, never write.

## The Pattern

1. **Identify layers** — partition the codebase into 3-4 independent inspection layers (e.g. data layer, player layer, UI/focus layer, backend services)
2. **Dispatch parallel sub-agents** — one per layer, each with:
   - `toolsets: ['file', 'terminal']` — file reading + basic terminal for computation
   - `context` with exact file paths to inspect and specific audit criteria (race conditions, leaks, focus traps, etc.)
   - Clear instruction to report concrete findings with `file:line` references
3. **Synthesize in parent** — read all results, cross-reference findings, prioritize by severity (Critical > High > Medium > Low)
4. **Research before fixing** — for each non-trivial fix, verify against official docs (Kotlin coroutines guide, Android dev docs, Stremio addon SDK spec) before applying
5. **Fix in priority order** — Critical first, then High, then Medium. Build after each batch.

## Sub-Agent Task Shape

Use `delegate_task` with `tasks` array for parallel dispatch:

```
Goal: "Audit the Android app data layer for issues. Report concrete findings with file:line references."
Context: "Project: [name] at [path]. Uses [key technologies].
Focus on: race conditions, missing error handling, caching issues, thread safety, token leaks, N+1 queries, coroutine cancellation.
Files to inspect:
  1) /path/to/AddonRepository.kt
  2) /path/to/DebridService.kt
  3) /path/to/PreferencesManager.kt
  4) /path/to/StremioAddonClientImpl.kt"
Toolsets: ["file", "terminal"]
```

Repeat for 2-3 more parallel tasks targeting different layers (player, UI, backend).

## Key Rules

- **Sub-agents are inspectors, not authors.** They should never write code — only read and report.
- **Cross-reference findings.** Two sub-agents may find different aspects of the same root cause.
- **Every recommendation must cite a source.** "Remove dead param" → grep confirms zero callers. "Use withTimeoutOrNull" → link to Kotlin docs. Never recommend without evidence.
- **Fix ALL findings in the same session.** The user expects actionable repairs, not a deferred backlog. Only skip architectural rewrites that need planning.
- **Build after each batch to catch API drift early.** Don't accumulate unfixed compile errors across files.

## Pitfalls

- **Sub-agents may misidentify issues.** Always verify critical findings yourself before fixing (read the file, confirm the claim). Sub-agents can hallucinate line numbers or misinterpret code.
- **Overlapping file access.** If sub-agents are asked to read the same files, context cost multiplies. Partition cleanly by layer to minimize overlap.
- **Parallel dispatch timeout.** If a sub-agent has too many files to read (>8 large files), it may timeout. Cap at 4-6 files per sub-agent.