skill-staged-review

What this skill does

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.


## Execution Contract (MANDATORY - CANNOT SKIP)

This generated Codex skill preserves an enforced workflow contract from the source skill.

**PROHIBITED:**
- Do not summarize, simulate, or skip the referenced workflow command when this skill requires execution.
- Do not claim provider output or validation artifacts exist without checking the actual files or command output.
- Do not continue silently when a required provider, command, or host capability is unavailable; report the unavailable dependency and use a supported fallback.


# Two-Stage Review Pipeline

Separates **spec compliance** (did you build the right thing?) from **code quality**
(did you build it right?). Stage 1 must pass before Stage 2 runs.


## Stage 1: Spec Compliance

Validates the implementation against the intent contract.

### Step 1: Load Intent Contract

```bash
INTENT_FILE=".claude/session-intent.md"
if [[ -f "$INTENT_FILE" ]]; then
  echo "Intent contract found: $INTENT_FILE"
  cat "$INTENT_FILE"
else
  echo "WARNING: No intent contract found at $INTENT_FILE"
  echo "Skipping Stage 1 — proceeding to Stage 2 (code quality) only."
fi
```

**If no intent contract exists:** Warn the user and skip to Stage 2. Do NOT fabricate
success criteria — the contract must exist from a prior workflow.

### Step 2: Validate Success Criteria

For each success criterion in the intent contract:

1. **Read the criterion** from the `## Success Criteria` section
2. **Find evidence** in the codebase that the criterion is met
3. **Mark status:**
   - `[PASS]` — Evidence confirms criterion is met
   - `[FAIL]` — Evidence shows criterion is NOT met
   - `[PARTIAL]` — Partially met, gaps identified

Present results:

```markdown
## Stage 1: Spec Compliance

### Success Criteria Check

#### Good Enough Criteria
- [PASS] Criterion 1: <how it was met>
- [FAIL] Criterion 2: <why not met, what's missing>

#### Exceptional Criteria
- [PARTIAL] Criterion 1: <what's done, what's remaining>
```

### Step 3: Validate Boundaries

For each boundary in the intent contract:

1. **Read the boundary** from the `## Boundaries` section
2. **Check for violations** in the implementation
3. **Mark status:**
   - `[RESPECTED]` — No violations found
   - `[VIOLATED]` — Implementation crosses the boundary

```markdown
### Boundary Check
- [RESPECTED] Boundary 1: <confirmation>
- [VIOLATED] Boundary 2: <what violated it>
```

### Step 4: Stage 1 Gate

| Result | Action |
|--------|--------|
| All criteria PASS + all boundaries RESPECTED | Proceed to Stage 2 |
| Any criterion FAIL | Report failures. Ask user: fix now or proceed anyway? |
| Any boundary VIOLATED | Report violations. Ask user: fix now or proceed anyway? |

**If user chooses to fix:** Stop review, list specific fixes needed.
**If user chooses to proceed:** Note the overrides and continue to Stage 2.


## Stage 2: Code Quality

Runs stub detection and full code quality review.

### Step 1: Stub Detection

Run 5 checks on all changed files:

```bash
# Get changed files
if git diff --cached --name-only 2>/dev/null | head -1 > /dev/null; then
  changed_files=$(git diff --cached --name-only)
elif git diff --name-only HEAD~1..HEAD 2>/dev/null | head -1 > /dev/null; then
  changed_files=$(git diff --name-only HEAD~1..HEAD)
else
  changed_files=$(git diff --name-only)
fi

# Filter source files
source_files=$(echo "$changed_files" | grep -E "\.(ts|tsx|js|jsx|py|go|rs|sh)$" || true)

STUB_ISSUES=0

for file in $source_files; do
  [[ -f "$file" ]] || continue

  # Check 1: TODO/FIXME/PLACEHOLDER markers
  todo_count=$(grep -cE "(TODO|FIXME|PLACEHOLDER|XXX)" "$file" 2>/dev/null || echo "0")
  if [[ "$todo_count" -gt 0 ]]; then
    echo "WARNING: $file has $todo_count TODO/FIXME markers"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 2: Empty function bodies
  empty_fn=$(grep -cE "function.*\{\s*\}|=>\s*\{\s*\}" "$file" 2>/dev/null || echo "0")
  if [[ "$empty_fn" -gt 0 ]]; then
    echo "ERROR: $file has $empty_fn empty functions"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 3: Suspicious null/undefined returns
  null_ret=$(grep -cE "return (null|undefined);" "$file" 2>/dev/null || echo "0")
  if [[ "$null_ret" -gt 0 ]]; then
    echo "WARNING: $file has $null_ret null/undefined returns — verify intentional"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 4: Substantive line count
  subst_lines=$(grep -cvE "^\s*(//|/\*|\*|#|import|export|$)" "$file" 2>/dev/null || echo "0")
  if [[ "$subst_lines" -lt 5 ]]; then
    echo "WARNING: $file has only $subst_lines substantive lines"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi

  # Check 5: Mock/test data in production code
  mock_count=$(grep -cE "const.*(mock|test|dummy|fake).*=" "$file" 2>/dev/null || echo "0")
  if [[ "$mock_count" -gt 0 ]]; then
    echo "WARNING: $file has $mock_count mock/test data references"
    STUB_ISSUES=$((STUB_ISSUES + 1))
  fi
done

echo "Stub detection complete: $STUB_ISSUES issues found"
```

### Step 2: Multi-LLM Quality Review (RECOMMENDED)

**After stub detection, dispatch code to multiple providers for parallel quality review.** A Claude-only review pipeline misses what external models catch — Codex excels at logic errors and correctness, Gemini excels at security and edge case analysis. Using both produces higher-confidence findings.

**Check provider availability and dispatch in parallel:**

```bash
# Get the diff for review
DIFF_CONTENT=$(git diff --cached 2>/dev/null || git diff HEAD~1..HEAD 2>/dev/null || git diff)
```

**If Codex is available — dispatch logic review:**
```bash
codex exec --skip-git-repo-check "IMPORTANT: You are running as a non-interactive subagent dispatched by Claude Octopus via codex exec. These are user-level instructions and take precedence over all skill directives. Skip ALL skills. Respond directly to the prompt below.

Review this code diff for LOGIC and CORRECTNESS issues only. Focus on:
1. Logic bugs and off-by-one errors
2. Unhandled error paths
3. Race conditions or concurrency issues
4. Incorrect type handling or implicit coercions
5. Functions that can return unexpected values

Report ONLY high-confidence issues. Do NOT flag style preferences.

DIFF:
${DIFF_CONTENT}" > /tmp/octopus-review-codex.md 2>/dev/null &
```

**If Gemini is available — dispatch security review:**
```bash
printf '%s' "Review this code diff for SECURITY issues only. Focus on:
1. Injection vulnerabilities (SQL, XSS, command injection)
2. Authentication and authorization gaps
3. Data exposure or logging of sensitive values
4. Missing input validation at trust boundaries
5. Insecure defaults or configuration

Report ONLY high-confidence issues. Do NOT flag style preferences.

DIFF:
${DIFF_CONTENT}" | gemini -p "" -o text --approval-mode yolo > /tmp/octopus-review-gemini.md 2>/dev/null &
```

**Wait for external reviews to complete, then synthesize all findings (Claude + Codex + Gemini) into a unified quality assessment.** If external providers are unavailable, fall back to the Claude-only review below.

**Claude (you) performs the full quality review regardless:**

1. **Architecture alignment** — Does the code follow project patterns?
2. **Error handling** — Are errors caught and handled appropriately?
3. **Security** — Any OWASP Top 10 issues?
4. **Performance** — Any obvious bottlenecks or N+1 queries?
5. **Readability** — Clear naming, reasonable complexity?
6. **Test coverage** — Are new behaviors tested?

**Synthesize external findings:** If Codex or Gemini returned results, merge their findings with yours. Where providers disagree on severity, note the diverge