Phx Audit

Project Health Audit

Comprehensive project-wide health assessment across five independent concern tracks.

Usage

phx-audit              # Full audit (default)
phx-audit --quick      # 2-3 minute pulse check
phx-audit --focus=security   # Deep dive single area
phx-audit --focus=performance
phx-audit --since abc123   # Incremental audit since commit
phx-audit --since HEAD~10  # Audit last 10 commits

When to Use

• Quarterly health checks
• Before major releases
• After large refactors
• New team member onboarding (understand codebase health)

Iron Laws

• Complete every selected track before synthesizing — partial results make

cross-category scores misleading

• Scope each track to concrete directories and checks — vague project-wide

analysis produces generic findings

• Never compare scores across projects — track trends only within the same

codebase

• Run quick mode before full mode — catch basic failures before expensive

analysis

Portable Audit Workflow

• Create .claude/audit/reports/ and .claude/audit/summaries/.
• Run the quick checks below. Stop and report a blocker when the project cannot

compile or its test command cannot start.

• Complete five tracks: architecture, performance, security, tests, and

dependencies. Native generic workers may run independent tracks in parallel

when the runtime provides them; otherwise run every track sequentially in

this session. Never require named custom agents.

• Write one evidence-focused report per track under .claude/audit/reports/.

Report issues only, cite paths and lines, and use one summary line for a

clean area.

• After all selected reports exist, deduplicate findings, identify

cross-category correlations, calculate scores using

references/scoring-methodology.md, and write

.claude/audit/summaries/project-health-{date}.md.

If two or more optional workers fail or hit limits, finish the missing tracks

sequentially. Never present an incomplete track as audited.

Output Format

Report an executive health score, per-category scores for Architecture,

Performance, Security, Tests, and Dependencies, critical issues, top

recommendations, and an Immediate/Short-term/Long-term action plan.

Quick Mode (--quick)

Only run essential checks (~2-3 minutes):

Run mix compile --warnings-as-errors, then mix hex.audit && mix deps.audit,

then mix xref graph --format stats, then mix test --trace 2>&1 | tail -20.

Skip: Full security scan, N+1 analysis, test quality metrics, architecture deep dive.

Focus Mode (--focus=area)

Run only the selected concern track with its deeper checks:

| Focus | Extra checks |

|-------|--------------|

| security | Full OWASP review, Sobelow, manual authorization patterns |

| performance | Query plans, N+1 inventory, profiling evidence |

| architecture | Full xref graph, coupling matrix, cohesion |

| tests | Coverage by context, isolation, flaky-test indicators |

| deps | Vulnerabilities, licenses, maintenance status |

Incremental Mode (--since <commit>)

Analyze only changes since a specific commit. Useful for pre-merge checks:

Run git diff --name-only <commit>...HEAD to identify changed files, then run targeted audits on changed files only (skips full project scan).

Combines with other flags: phx-audit --since HEAD~5 --focus=security

Relationship to Other Commands

| Command | Scope | Frequency |

|---------|-------|-----------|

| phx-review | Changed files (diff) | Every PR |

| phx-audit | Entire project | Quarterly |

| phx-boundaries | Context structure | On-demand |

| phx-verify | Compile/test pass | Anytime |

References

• references/scoring-methodology.md - How scores are calculated
• references/architecture-checks.md - Detailed architecture criteria