pre-pr-audit

Pre-PR Audit

Pre-deploy ultimate verification. Aggregates test quality, coverage, risk, and AC traceability into a single confidence index (0-100).

When NOT to Use

| Need | Use Instead | |------|-------------| | Code review | /codex-review-fast | | Post-deploy runtime verification | /feature-verify | | Periodic project health | /project-audit | | Just run tests | /verify | | Just check risk | /risk-assess |

Positioning

auto-loop done → [user invokes] /pre-pr-audit → /smart-commit → /push-ci → /create-pr
                                     ↑
                        Pre-deploy ultimate verification

Prohibited

❌ git add | git commit | git push — per @rules/git-workflow.md

This skill audits and reports. It does not modify code or commit.

Arguments

| Arg | Description | Default | |-----|-------------|---------| | --mode fast\|deep | Execution depth | fast | | --strict | Non-zero exit on ⛔ PR-Blocked | off | | --json | Machine-readable JSON output | off | | --base <ref> | Compare against ref | HEAD |

Workflow

sequenceDiagram
    participant U as User
    participant PA as /pre-pr-audit
    participant RA as /risk-assess
    participant TR as /codex-test-review
    participant CC as /check-coverage
    participant ST as State / Artifacts

    U->>PA: /pre-pr-audit [--mode fast|deep]

    par Phase A: Collect
        PA->>ST: [Background Agent] Read precommit/verify state (freshness)
        PA->>RA: [Foreground — blocking] /risk-assess --mode fast
        PA->>PA: [Background Agent] Detect changed files + map to tests
    end

    Note over PA,RA: A2 (/risk-assess) must complete before Phase B — Module Selection depends on top_affected

    par Phase B: Targeted
        PA->>TR: [Foreground] /codex-test-review (top-N risky modules)
        PA->>CC: [Background Agent: coverage-analyst] /check-coverage (deep mode only)
        PA->>PA: [Background Agent] AC trace (if request doc exists)
    end

    PA->>PA: Phase C: Aggregate + hard-fail + gate
    PA->>U: Phase D: Report + confidence index

Phase A: Collect (parallel with dispatch annotations)

| Step | Dispatch | Action | Source | |------|----------|--------|--------| | A1 | Background Agent | Read precommit/verify state file | .claude_review_state.json — check precommit.passed + freshness (HEAD match) | | A2 | Foreground (blocking) | Invoke /risk-assess --mode fast | Skill tool — get risk_level, top_affected, overall_score | | A3 | Background Agent | Detect changed files + map to test files | git diff --name-only HEAD → match against test/ patterns |

A2 MUST stay foreground: Phase B Module Selection depends on top_affected from /risk-assess output. A1 and A3 dispatch as background Agents and run in parallel with A2.

Phase B: Targeted (parallel, mode-dependent, with dispatch annotations)

| Step | Dispatch | fast | deep | Action | |------|----------|------|------|--------| | B1 | Foreground | top-3 | top-10 + supplement | /codex-test-review on selected modules (see Module Selection) | | B2 | Background Agent (coverage-analyst) | skip | ✅ | /check-coverage for pyramid balance | | B3 | Background Agent | skip | ✅ (if request doc) | AC trace: parse ## Acceptance Criteria → map to test evidence |

B2 uses coverage-analyst agent (agents/coverage-analyst.md) for background execution. B3 dispatches as a background Agent for AC parsing. B1 stays foreground as the primary assessment.

Module Selection (deterministic)

1. Source: /risk-assess JSON top_affected array (each: file + dependent_count)
2. Sort: dependent_count descending, tie-break file ascending (stable sort)
3. Select: N=3 (fast) or N=10 (deep)
4. Deep supplement: git diff --name-only for files beyond top_affected cap
5. Fallback: if /risk-assess unavailable, git diff --stat sorted by lines-changed descending

Phase C: Aggregate

1. Score each dimension per references/scoring-model.md
2. Apply evidence confidence cap
3. Check hard-fail overrides
4. Compute final index

Phase D: Output

Output report per references/output-template.md. Include:

• Confidence index (0-100) + gate sentinel
• Per-dimension score table
• Hard-fail check results
• Findings (prioritized)
• Next actions

5 Dimensions

| # | Dimension | Weight | Checks | |---|-----------|--------|--------| | 1 | Execution Integrity | 25% | All tests pass, precommit passed, HEAD freshness, no flaky indicators | | 2 | Coverage Adequacy | 25% | Unit/Integration/E2E pyramid balance, per-module gap analysis | | 3 | Test Quality | 20% | AAA compliance, naming, assertion depth, edge cases (per @rules/testing.md) | | 4 | Risk-to-Test Alignment | 20% | High-risk files have tests, risk level ↔ test depth proportional | | 5 | Evidence Governance | 10% | AC traceability, exception policy compliance, expiry check |

Gate

User-Facing (3-tier)

| Gate | Score | Sentinel | |------|-------|----------| | ✅ Ready | >=85 | ✅ PR-Ready | | ⚠️ Needs attention | 60-84 | ⚠️ PR-Caution | | ⛔ Not ready | <60 | ⛔ PR-Blocked |

Hard-Fail Overrides (force ⛔ regardless of score)

| Override | Condition | Source | |----------|-----------|--------| | Precommit stale | Not passed after latest edit | Auto-loop state | | Prohibited domain exception | Security/data-integrity/regression AC uses manual exception | @rules/testing.md | | Exception cap exceeded | Exception count > AC-count-based cap | @rules/testing.md | | Expired exception | Past ISO 8601 expiry date | @rules/testing.md | | Invalid reason class | Non-enum reason in exception | @rules/testing.md | | Unverified exception | No Codex VALID_EXCEPTION verdict | @rules/testing.md | | Evidence stale | Artifacts HEAD SHA ≠ current HEAD | Freshness check | | Critical untested | /risk-assess HIGH+ on zero-coverage files | Risk alignment |

Scoring

See references/scoring-model.md for formulas. Summary:

• Check score: pass=1, partial=0.5, fail=0, N/A=excluded
• Dimension score: applicable_sum / applicable_count × 100
• Raw: weighted average (N/A dimensions excluded, weights renormalized)
• Cap: evidence confidence (1.0 / 0.9 / 0.75 / 0.6)
• Final: round(raw × cap)

Verification

• [ ] All 5 dimensions scored (or N/A with reason)
• [ ] Hard-fail checks evaluated
• [ ] Gate sentinel output matches score
• [ ] No git add/commit/push executed
• [ ] Findings include file:line references

References

• references/scoring-model.md — Scoring formulas, weights, confidence caps
• references/output-template.md — Report format, JSON schema, sentinel strings
• @rules/testing.md — Evidence model + exception policy (hard-fail source)
• @rules/testing-project.md — Project-specific overrides

Examples

Input: /pre-pr-audit
Action: fast mode → collect state + risk → test-review top-3 → aggregate → 85/100 ✅ PR-Ready

Input: /pre-pr-audit --mode deep
Action: deep mode → collect + risk → test-review top-10 + coverage + AC trace → aggregate → 72/100 ⚠️ PR-Caution

Input: /pre-pr-audit --strict
Action: fast mode → score 55 → ⛔ PR-Blocked → exit code 1