Review Implementation

Validate implementation work at checkpoints during plan execution.

Purpose

Provide quality gates during plan execution by:

•Verifying tasks completed as specified
•Checking code quality and patterns
•Validating tests are adequate
•Identifying issues before they compound

When to Use

•After completing a phase during plan-execute
•At the end of plan execution (mandatory)
•When manually checking implementation progress
•Before merging implementation work

CRITICAL: Third-Party Review Required

This skill MUST delegate to Codex CLI. The review cannot be performed by the agent that implemented the code - an independent third-party model must validate the work.

Why third-party review matters:

•Catches blind spots the implementer missed
•Validates implementation against plan specifications
•Provides independent verification of code quality
•Reduces confirmation bias in self-review

If Codex CLI is not available, inform the user and do not proceed with a self-review.

Codex CLI Invocation

Use the dedicated codex review command for non-interactive code review:

bash

# Review uncommitted changes
codex review --uncommitted --title "Review Title"

# Review changes against a base branch
codex review --base main --title "PR Review"

# Review a specific commit
codex review --commit abc123 --title "Commit Review"

# Review with custom instructions (no scope flags)
codex review "Check for security issues in the authentication code"

# Read custom instructions from stdin (no scope flags)
cat <<'PROMPT' | codex review -
<review instructions here>
PROMPT

Key options:

•--uncommitted - Review staged, unstaged, and untracked changes
•--base <BRANCH> - Review changes against a base branch
•--commit <SHA> - Review changes introduced by a specific commit
•--title <TITLE> - Optional title for the review summary

IMPORTANT: The --base, --commit, and --uncommitted flags cannot be combined with a [PROMPT] argument. Use either:

•Scope flags (--commit, --base, --uncommitted) with optional --title
•OR a custom [PROMPT] without scope flags

Review Scopes

Phase Review

Invoked after each phase completes:

code

/review-implementation --scope phase --phase {N}

Reviews:

•Tasks in the specified phase
•Files changed during this phase
•Verification commands ran successfully
•No regressions introduced

Plan Review

Invoked at plan completion (mandatory):

code

/review-implementation --scope plan

Reviews:

•All phases completed
•Full test coverage
•Documentation updated
•Overall code quality

Diff Review

Review specific changes:

code

/review-implementation --scope diff

Reviews:

•Current uncommitted changes
•Or changes since a specific commit

Review Workflow

Step 1: Gather Context

Collect information about what to review:

•Identify the plan being executed
•Determine scope (phase, plan, or diff)
•
Get the changes:
- •For phase: commits since phase start
- •For plan: all commits in execution
- •For diff: current uncommitted changes

bash

# Get changes for review
git diff --stat HEAD~{N}
git log --oneline HEAD~{N}..HEAD

Step 2: Load Plan Expectations

Read the plan to understand:

•What tasks should have been completed
•Expected file changes (CREATE/MODIFY/DELETE)
•Verification commands specified
•Testing strategy requirements

Step 3: Verify Codex Available

MANDATORY: You must invoke Codex CLI. Do not perform the review yourself.

bash

which codex || echo "Codex CLI not installed"

If not available, stop and inform the user they need to install Codex CLI.

Step 4: Invoke Codex Review

Use codex review with the appropriate scope:

For Phase Review (uncommitted changes):

bash

codex review --uncommitted --title "Phase {N}: {phase-name}"

For Phase Review (committed changes):

bash

codex review --commit {phase-commit-sha} --title "Phase {N}: {phase-name}"

For Plan Review (against base branch):

bash

codex review --base main --title "Plan Review: {plan-name}"

Note: Scope flags (--commit, --base, --uncommitted) cannot be combined with custom prompts. Codex will automatically analyze the changes and provide a structured review.

Codex will:

•Read the changed files and understand the context
•Examine the actual code changes
•Check for bugs, security issues, and code quality
•Provide a structured review with findings

Step 5: Run Verification

Execute verification commands from the plan:

bash

bun test
bun run typecheck
bun run lint

Step 6: Compile Review Report

Output a structured review report:

markdown

## Implementation Review: {scope}

**Plan:** {plan-name}
**Scope:** Phase {N} | Full Plan | Diff
**Reviewed by:** Codex (gpt-5.1-codex-max)
**Verdict:** PASS | NEEDS_REVISION | FAIL

### Summary

{2-3 sentence summary of findings}

### Tasks Verified

| Task | Expected | Actual | Status |
|------|----------|--------|--------|
| 1.1 Create auth module | `src/auth.ts` created | ✅ Created | PASS |
| 1.2 Add tests | 3+ tests | 4 tests | PASS |

### Code Quality

| Aspect | Finding | Severity |
|--------|---------|----------|
| Correctness | Logic matches spec | - |
| Patterns | Follows existing patterns | - |
| Edge cases | Missing null check in parser | MEDIUM |

### Issues Found

| Severity | Issue | Location | Recommendation |
|----------|-------|----------|----------------|
| HIGH | Missing error handler | `src/auth.ts:42` | Add try-catch |
| MEDIUM | Unused import | `src/index.ts:3` | Remove import |
| LOW | Variable could be const | `src/utils.ts:15` | Use const |

### Test Coverage

- New tests: {N}
- All tests passing: ✅ | ❌
- Coverage adequate: ✅ | ❌

### Recommendations

1. {Actionable recommendation}
2. {Actionable recommendation}

### Verdict Explanation

{Why this verdict was given}

**Next Steps:**
- PASS: Continue to next phase / Merge
- NEEDS_REVISION: Apply fixes listed above
- FAIL: Stop and consult user

Verdicts

PASS

Implementation meets all requirements:

•All expected tasks completed
•Tests passing and adequate
•No HIGH severity issues
•Code quality acceptable

Action: Proceed to next phase or merge.

NEEDS_REVISION

Implementation mostly correct but has issues:

•Some tasks incomplete or incorrect
•MEDIUM severity issues found
•Tests incomplete

Action: Fix issues and re-run review.

FAIL

Significant problems found:

•Major tasks missing or wrong
•HIGH severity issues
•Breaking changes
•Security concerns

Action: Stop execution, consult user.

Critical Analysis

When analyzing findings, apply critical thinking:

Do Apply Feedback When:

•Issue is clearly a bug or error
•Fix is straightforward and safe
•Pattern violation is obvious
•Security concern is valid

Question Feedback When:

•Suggestion is stylistic preference
•Fix would require scope expansion
•Recommendation conflicts with plan
•Issue is a known trade-off

Document Decisions

When choosing not to apply feedback:

markdown

**Declined Recommendation:**
> "Add retry logic to API calls"

**Reason:** Out of scope for current phase. Will be addressed in Phase 4 as per plan.

Integration with plan-execute

This skill is invoked automatically by plan-execute:

•After each phase completes
•Before proceeding to next phase
•At plan completion (mandatory)

The plan-execute skill will:

•Pass the current scope and phase
•Wait for the verdict
•Act based on the verdict (continue, fix, or stop)

Examples

Example: Phase review passes

code

/review-implementation --scope phase --phase 1

Claude: I'll review Phase 1 using Codex CLI for independent validation.

[Runs: which codex]
/opt/homebrew/bin/codex

[Runs: codex review --commit abc123 --title "Phase 1: Database Schema"]

Codex returned:

## Implementation Review: Phase 1

**Plan:** 0042_user-auth
**Scope:** Phase 1
**Reviewed by:** Codex (gpt-5.1-codex-max)
**Verdict:** PASS

### Summary
All 3 tasks in Phase 1 completed successfully. Database schema
created, migrations added, and tests passing.

### Tasks Verified
| Task | Expected | Status |
|------|----------|--------|
| 1.1 Create schema | `src/db/schema.ts` | PASS |
| 1.2 Add migration | `migrations/001_users.ts` | PASS |
| 1.3 Write tests | 5+ tests | PASS (6 tests) |

### Verdict Explanation
All tasks complete, tests passing, no issues found.

**Next Steps:** Proceed to Phase 2

Example: Review finds issues

code

/review-implementation --scope phase --phase 2

Claude: I'll review Phase 2 using Codex CLI.

[Runs: codex review --commit def456 --title "Phase 2: API Endpoints"]

Codex returned:

## Implementation Review: Phase 2

**Reviewed by:** Codex (gpt-5.1-codex-max)
**Verdict:** NEEDS_REVISION

### Issues Found
| Severity | Issue | Location | Recommendation |
|----------|-------|----------|----------------|
| HIGH | Missing validation | `src/api/users.ts:28` | Add input validation |
| MEDIUM | No error handling | `src/api/users.ts:35` | Add try-catch |

### Recommendations
1. Add Zod schema validation before processing request
2. Wrap database call in try-catch

**Next Steps:** Apply fixes and re-run review

Example: Final plan review

code

/review-implementation --scope plan

Claude: I'll perform the final plan review using Codex CLI.

[Runs: codex review --base main --title "Plan Review: 0042_user-auth"]

Codex returned:

## Implementation Review: Full Plan

**Plan:** 0042_user-auth
**Reviewed by:** Codex (gpt-5.1-codex-max)
**Verdict:** PASS

### Summary
All 4 phases complete. 12 tasks implemented, 24 tests added,
all verification passing.

### Phases Verified
- [x] Phase 1: Database Schema (3/3 tasks)
- [x] Phase 2: API Endpoints (4/4 tasks)
- [x] Phase 3: Frontend Forms (3/3 tasks)
- [x] Phase 4: Integration Tests (2/2 tasks)

### Test Coverage
- Unit tests: 18
- Integration tests: 6
- All passing: ✅

### Final Checks
- [x] All tests pass
- [x] Type check clean
- [x] Lint clean
- [x] Documentation updated

**Ready to merge.**

Example: Codex not available

code

/review-implementation --scope plan

Claude: I need to invoke Codex CLI for third-party review.

[Runs: which codex]
codex not found

I cannot proceed with the review. This skill requires Codex CLI
for independent third-party validation. Please install it:

  npm install -g @openai/codex

Then run /review-implementation again.

Related Skills

•plan-execute - Invokes this skill at checkpoints
•review-plan - Reviews plans before execution
•review-code - General code review (not plan-specific)