[Proposal] Reasoning Quality Gate Pipeline: Pre-task Calibration → Adversarial Review → Delivery Verification

# [Proposal] Reasoning Quality Gate Pipeline: Pre-task Calibration → Adversarial Review → Delivery Verification

## Summary

A three-gate pipeline covering AI output quality across the full session lifecycle. Each gate targets a failure mode the others can't catch. Two of the three gates have been independently adopted, production-hardened, and merged in leading Claude Code ecosystem repositories, with formal attribution for the original design.

## Problem

Existing quality tools (lint, typecheck, test, security scan) verify **code artifacts**. They don't verify **reasoning quality** — whether the agent's thinking process itself was sound. In Claude Code sessions, three failure modes routinely slip through:

| Failure | When | Why existing tools miss it |
|---------|------|---------------------------|
| Agent edits files before confirming the approach is correct — writes 200 lines, then user realizes the direction was wrong | Before first keystroke | No pre-edit checkpoint exists |
| Single-pass code review misses blind spots — the same model reviewing its own output inherits the same blind spots | During implementation | Reviewer and author share reasoning gaps |
| Agent declares "done" via Stop but one or more claimed outputs were never written to disk, or requirements were silently dropped | After delivery | Stop hook has no output verification layer |

These aren't hypothetical — they're patterns extracted from real Claude Code sessions. Each gate was added when a failure mode was observed that existing checks couldn't catch.

## Three Gates

```
Session Start → ① Pre-task Calibration (PreToolUse hook, exit 2)
↓ pass
Task execution
↓
② Adversarial Review (on-demand, multi-round)
↓ pass
③ Delivery Verification (Stop hook, exit 2)
↓ pass
Delivery
```

### ① Pre-task Calibration

Before any Edit/Write/high-risk Bash: three mandatory questions. Any fail → PreToolUse hook exit 2, tool call blocked.

- Q1: Concept review passed? (did I validate the approach with an adversarial check before acting?)
- Q2: Inputs consistent? (do file paths, constants, and assumptions match actual code, not documentation memory?)
- Q3: Post-completion verification planned? (will I verify output, not just claim completion?)

**Mechanism**: Establishes a mandatory pre-action checkpoint via structured prompting, forcing the agent to verify feasibility and plan verification before executing any high-risk tool call. It reduces impulsive, unplanned edits by adding a consistent decision checkpoint at the only moment when prevention is cheaper than correction — before the first keystroke.

### ② Adversarial Review

**Fixed pool**: 9 sourced personas with verifiable philosophies (e.g., Rich Hickey on simplicity vs. complexity, John Carmack on edge-case testing, Don Norman on cognitive load). Each persona is grounded in documented principles with explicit confidence ratings — no fabricated quotes, no invented authorities.

**Random pool**: web-search to supplement unknown perspectives from domains outside the fixed pool's coverage, preventing echo-chamber effects.

**Mechanism**: Manager persona classifies task → selects panel → multi-round cross-review → ≥2 reviewers independently flagging same issue → auto-escalate to CRITICAL → anti-fabrication discipline (every attribution carries a confidence level; unverifiable claims are rejected rather than embellished).

### ③ Delivery Verification

**Step 0 (mechanical)**: File read-back verification — use file-read tool to confirm every claimed output file actually exists on disk with non-trivial content. This is the one verification an agent cannot fabricate: tool return values can report success without writing content, but a read-back confirms or refutes the claim deterministically.

**Steps 1-4 (reasoning, damage-severity order)**:
1. **Honesty** — is the agent being honest about what wasn't done? If failing, the remaining three dimensions audit fiction.
2. **Completeness** — did every request get addressed, or were requirements silently dropped?
3. **Consistency** — did the output contradict itself or the governing rules?
4. **Groundedness** — are claims supported by evidence, or just asserted?

Fail → Stop hook exit 2, delivery blocked. Lexicographic rule: never fix Groundedness while Honesty is failing — auditing fiction wastes effort and masks the root problem.

## Cross-gate Design Principles

1. **Mechanical where possible.** Gates ① and ③ use hook exit codes (PreToolUse + Stop). Gate ② uses a tier-classification script for review depth signals. Deterministic checks beat aspirational prompts — file timestamps, exit codes, and read-back verification don't drift.
2. **Damage-severity ordering.** Honesty before Completeness before Consistency before Groundedness. The order is not arbitrary — it reflects the cost of missing each dimension.
3. **Independent, composable.** Each gate works standalone. Combined they form defense in depth — a failure that slips past one gate is caught by another operating at a different lifecycle point with different detection mechanisms.

## Independent Validation

Two of the three gates have been independently adopted, production-hardened, and merged in leading Claude Code ecosystem repositories, with formal attribution for the original design.

### Gate ② Adversarial Review — merged with Co-authored-by attribution

- Original design proposal: `alirezarezvani/claude-skills#866`
- Maintainer-refined implementation merged to dev branch: `alirezarezvani/claude-skills#867` (2026-07-01)
- Maintainer explicit confirmation: *"core idea is genuinely valuable and filled a real gap next to adversarial-reviewer and code-reviewer"*
- **Co-authored-by attribution** added to the final merge commit per community contribution convention

### Gate ③ Delivery Verification — merged after full maintainer approval

- Original approved draft: `affaan-m/ECC#2365` (full maintainer approval from daltino)
- Final merged version: `affaan-m/ECC#2378` (2026-06-30, merged by affaan-m)
- Maintainer review: *"useful delivery-gate skill that complements the existing verification-loop by focusing on thinking quality"*

### Gate ① Pre-task Calibration — validated in production workflow

- 50+ real-world coding sessions in personal Claude Code workflow
- Not yet submitted to any public repository; included here as the upstream component completing the full pipeline

### Industry pattern alignment

The four verification dimensions (honesty, completeness, consistency, groundedness) emerged independently from real session failures — each dimension was added when a specific failure mode was observed that existing checks could not catch.

## What's Different From Existing Skills

Existing skills verify code artifacts (build, lint, typecheck, security). This pipeline verifies the **reasoning process** that produced those artifacts — before, during, and after execution. The three-gate structure was not designed upfront: each gate was added when a specific Claude Code failure mode was observed that existing gates could not catch. The result is a pipeline where blind spots are cross-covered by independent detection mechanisms at different lifecycle points.

## Request

This is a **design proposal**, not a code submission. I'm sharing the full architecture because:

- Two components have been independently production-hardened and merged with formal attribution
- The complete three-gate pipeline has been refined across 50+ real-world sessions
- The design patterns (mechanical read-back, damage-priority ordering, adversarial persona pools) are generalizable beyond any single implementation

My core contribution is the pipeline architecture and design patterns. I'm happy to help draft initial skill implementations, but I fully defer to repo maintainers on code structure, naming conventions, and integration standards to ensure consistency with the codebase.

If the team chooses to implement any part of this design internally, I ask that standard open source contribution conventions be followed for original design attribution, consistent with how prior community adoptions of these components have been handled.

## References

- Gate ② (merged, Co-authored-by): `alirezarezvani/claude-skills#866` → `#867`
- Gate ③ (merged, approved): `affaan-m/ECC#2365` → `#2378`
- Gate ③ enhanced discussion: `anthropics/skills#1367` (self-audit skill, OPEN)