Quality & RCF Gates
Relevant source files
The following files were used as context for generating this wiki page:
Quality & RCF (Root-Cause-First) Gates ensure that repository changes adhere to strict implementation standards and behavioral integrity. These gates act as automated and procedural checkpoints that prevent speculative code, duplication, and unverified bug fixes from entering the production environment. They are deeply integrated into the repo-production-workflow and enforce non-negotiable hard invariants defined in the project's core documentation.
Sources: skills/production-code/SKILL.md:1-15, CLAUDE.md:25-45
Root-Cause-First (RCF) Gate
The RCF Gate prevents production fixes for bugs, regressions, or performance issues until the system reaches a specific state of diagnosis. It requires three distinct pieces of evidence before any code modification: a reproduced symptom, a traced root cause, and a testable hypothesis. This gate ensures developers fix the source of an issue rather than merely guarding against its visible symptoms.
Sources: skills/production-preflight/SKILL.md:37-47, CLAUDE.md:42-45
RCF Requirements
| Requirement | Description | Verification Method |
|---|---|---|
| Reproduced Symptom | The exact failure observed at a production seam. | Automated feedback loop (test, script, or trace). |
| Traced Root Cause | The source trigger, not just the visible error. | Backwards trace from symptom to original trigger. |
| Testable Hypothesis | Statement of why the proposed edit fixes the source. | Falsifiable prediction: "If X is changed, Y occurs." |
| Source-level Fix | Implementation that addresses the trigger directly. | Smallest correct change at the identified source. |
Sources: skills/production-preflight/SKILL.md:40-47, skills/diagnose/SKILL.md:17-25
Diagnostic Feedback Loops
The diagnose skill provides the mechanical procedure for passing the RCF Gate. It prioritizes the construction of a deterministic, agent-runnable pass/fail signal.
The diagram above illustrates the sequential progression required to satisfy the Root-Cause-First invariant before code modification begins.
Sources: skills/diagnose/SKILL.md:30-100, skills/diagnose/SKILL.md:110-140
Code Quality Gate
The Code Quality Gate enforces seven core principles to judge repository changes. It operates as a non-mutating script (code_quality_gate.py) that measures the worktree against a base reference. The gate reports findings based on severity, location, and contract violation.
Sources: skills/code-quality/SKILL.md:12-60, skills/production-code/SKILL.md:21-35
The Seven Principles
- Minimal code: Ensure the smallest correct change and removal of obsolete code.
- No duplicated behavior: Reuse existing implementations and avoid similar-but-different logic.
- Direct data and control flow: Keep state transitions and I/O explicit; avoid avoidable orchestration hops.
- No fake-green escape: Ban mocks at production seams and ensure real failures are corrected, not muted.
- Cleanup discipline: Remove temporary artifacts, obsolete branches, and change-created dead code.
- Consequence coverage: Trace coupled updates and ensure proof crosses the combined behavior surface.
- Simple implementation: Prioritize readable, direct code over ceremonial or verbose patterns.
Sources: skills/code-quality/SKILL.md:14-55
Gate Execution
The quality gate is invoked via the CLI to check the current repository state:
PYTHONDONTWRITEBYTECODE=1 python3 "$HOME/.claude/skills/production-code/scripts/code_quality_gate.py" check --repo "$PWD" --base-ref <ref>
Sources: skills/production-code/SKILL.md:26-28
Hard Invariants & Mock Ban
The project enforces hard invariants that these gates must uphold. These are absolute rules that skills cannot weaken or duplicate.
- Mock Ban: Verification must cross the real production Seam. Mocks, stubs, and test-only adapters are forbidden as production proof.
- Imaginary-Risk Ban: Theoretical failures do not justify code. A change requires a verified mechanism and demonstrated occurrence.
- Contradictory-Contract Gate: Interfaces cannot promise arbitrary caller behavior while also carrying "do not call" caveats.
Sources: CLAUDE.md:27-41
Data Boundary Validation
The gates enforce strict data handling at the system boundaries. PAYLOADS from external sources (HTTP, Firestore, Cloud Tasks) must be treated as unknown until validated.
This diagram shows the "validate once at the boundary" rule enforced by the quality gates.
Sources: skills/production-code/SKILL.md:100-110
Production Preflight Gate
The Production Preflight Gate must be cleared before the first tracked edit in a governed pass. It requires a structured JSON record containing the architectural decisions and a Behavior Map of falsifiable attacks.
Sources: skills/production-preflight/SKILL.md:20-25, skills/production-preflight/SKILL.md:195-205
Behavior Map (BM) Requirements
Every preflight must include a behaviorMap array where each item represents a concrete adversarial attack on a public promise.
| Field | Type | Description |
|---|---|---|
id | string | Stable uppercase identifier (e.g., BM_ATOMICITY). |
kind | string | contract (requested) or preservation (existing). |
behavior | string | The specific observable behavior being tested. |
redFailure | string | The exact product exception or diagnostic expected. |
status | string | pending, already-satisfied, or omitted. |
Sources: skills/production-preflight/SKILL.md:209-245
Summary
Quality & RCF Gates form the backbone of the repository's governance. By enforcing the Mock Ban, Imaginary-Risk Ban, and Root-Cause-First diagnosis, the system ensures that every line of code is necessary, verified at a real production seam, and directly addresses a demonstrated requirement or defect. These gates transition implementation from a speculative process to a verifiable engineering discipline.
Sources: CLAUDE.md:25-50, skills/production-code/SKILL.md:230-245