| name | phx-review |
| description | Review changed Elixir/Phoenix code read-only. Check requirements, cite evidence, deduplicate findings, and return a severity-based verdict. |
Review Elixir/Phoenix Code
Perform an evidence-based, read-only review of changed code. Find and explain
issues; do not edit files, create tasks, or fix findings.
Usage
/phx-review
/phx-review test
/phx-review security
/phx-review .claude/plans/auth/plan.md
/phx-review --no-requirements
Treat the text after the skill name as a focus area, issue identifier, or path to
a plan/specification.
Iron Laws
- Review is read-only — inspect and report; never modify the worktree.
- Scope to changed code — distinguish new defects from pre-existing issues.
- Every finding needs evidence — cite a path and line, explain impact, and
describe the concrete failure mode.
- Check requirements when available — unmet requirements affect the verdict.
- Deduplicate and prioritize — one root cause is one finding, with the
highest justified severity.
- Do not require custom agents, hooks, MCP, or unavailable task APIs — use
optional runtime capabilities only when present.
Workflow
1. Establish Scope
Determine the merge base or user-specified base, then inspect:
git status --short
git diff --name-only <base>...HEAD
git diff --stat <base>...HEAD
git diff <base>...HEAD -- <changed-files>
Do not assume HEAD~5 is the correct base. Include uncommitted changes when the
user asks to review the current worktree. Record the chosen scope in the result.
2. Load Requirements
Unless --no-requirements is set, look for an explicit plan/spec path, current
conversation requirements, a branch or commit issue identifier, or the latest
relevant plan. Use available integrations or gh issue view when configured;
otherwise mark requirements NOT AVAILABLE and continue.
Read references/requirements-detection.md for detection order. Never let a
missing Linear, GitHub, hook, or MCP integration block code review.
3. Review by Concern
Select only concerns relevant to the diff:
- Elixir/Phoenix correctness and idioms;
- Ecto queries, changesets, transactions, migrations, and N+1 risks;
- LiveView lifecycle, reconnect, forms, streams, and assigns;
- authentication, authorization, secrets, and input handling;
- Oban idempotency, retries, uniqueness, and transaction boundaries;
- tests, regressions, and verification gaps;
- deployment/runtime configuration when those files changed.
Native OpenCode subagents may run independent read-only concern tracks in parallel.
Use generic subagents with the complete diff scope and return findings to this
session; do not depend on separately installed named agents. If subagents are
unavailable or unnecessary, run every selected concern sequentially here. A
sequential review is fully valid.
4. Verify Findings
For each candidate:
- Confirm it is in changed code or label it
PRE-EXISTING.
- Trace the actual runtime or data-flow consequence.
- Check nearby tests and requirements.
- Remove style-only noise and speculative concerns.
- Merge duplicates under the clearest root cause.
Run targeted read-only verification when it materially changes confidence. Do
not alter files or suppress failures. If a check cannot run, report that clearly.
5. Report a Verdict
Return one verdict:
PASSPASS WITH WARNINGSREQUIRES CHANGESBLOCKED
List findings in descending severity as BLOCKER, WARNING, or SUGGESTION.
Each finding must include path:line, evidence, impact, and the smallest
appropriate correction. Add requirements coverage before findings; any UNMET
requirement requires REQUIRES CHANGES.
If there are no findings, say so explicitly and list residual risks or checks not
run. Stop after presenting the review. Suggest /phx-triage, /phx-plan, or
/phx-compound as optional next steps without invoking them automatically.
References
references/requirements-detection.md — requirements source and coverage rulesreferences/agent-spawning.md — OpenCode concern selection and optional parallelism
