Code Quality Gate

Code Quality Gate

Use this skill after implementation and before final acceptance verification. This ordering does not prohibit safe, disposable previews or risk probes during implementation; those are diagnosis, not acceptance or permission for unsafe live installation or mutation.

Run it as a fresh subagent review gate, separate from the implementer. A same-agent skill invocation is not independence. Fresh context reduces self-confirmation bias; it does not guarantee unbiased review. Small changes still receive fresh review, focused on the diff, intent, and concrete risks; expand depth for uncertainty, coupling, security, or consequential failure. It returns a decision and never edits files.

Mode Dispatch

• The default, when mode is omitted, is the existing issue mode below. Any mode other than the explicit mode: isa request uses the existing issue-mode contract; do not auto-detect ISA inputs.
• When the caller explicitly supplies mode: isa, use the alternate contract in references/isa-mode.md. Do not require, read, create, or infer {ISSUE_DIR}/plan.md for that invocation.
• The two modes have separate inputs and output contracts. Do not mix issue artifacts into ISA review or ISA inputs into issue review.

Inputs

Read the minimum available context:

• Required: {ISSUE_DIR}/plan.md for pipeline calls; for a standalone call, an explicit approved scope, acceptance criteria, boundaries, and any named Mechanical commands may be supplied directly instead. Below, plan.md means that approved contract for standalone review; do not create pipeline artifacts just to review a diff.
• Required: changed files and/or git diff
• Optional but useful: {ISSUE_DIR}/issue.md
• Optional but useful: implementation summary from the implementation agent
• Required when plan.md names Mechanical command(s): raw output for those commands. Missing that output is REVISE_CODE. This gate does not run the commands or edit tests.
• Optional but useful: _ai/prompts/quality/code-review.md as the review standard
• Optional but useful: _ai/prompts/quality/code-guidelines.md as the quality standard

If the approved contract or changed code/diff is missing, return ASK_USER naming the missing input and its owner. The caller repairs pipeline-owned gaps from approved context before redispatch; only unresolved intent or permission needs a human decision. A missing pipeline plan is not permission to silently switch to standalone inputs.

Artifact Contract

• ISSUE_DIR is the artifact directory created by gather-context for the current pipeline run.
• Required: the approved contract above, plus changed files and/or git diff and exact candidate identity (commit or base plus uncommitted diff).
• Optional but useful: issue.md, implementation summary, and quality docs.
• If plan.md names Mechanical command(s) and their raw output is missing, return REVISE_CODE identifying an evidence gap, not a code defect. Request the receipt from the implementation owner without source changes. Do not run the commands.
• If command output is missing because the plan has no Mechanical field (legacy plan), do not invent a requirement here.

Review Process

1. Reconstruct the intended scope from plan.md; use issue.md only to resolve ambiguity.
2. Review the diff and directly affected code first.
3. Trigger wider dependency review only when the change touches shared modules, public interfaces, global state, async side effects, security-sensitive paths, or common components.
4. Compare implementation against the referenced quality docs without copying them into the report.
5. Heavily weight simplicity: prefer the smallest code that satisfies plan.md; penalize speculative abstractions, extra surfaces, duplicate state, and unplanned features.
6. Check provided Mechanical / test / build / lint / typecheck output. Distinguish demonstrated code failures from commands blocked by environment prerequisites; identify prerequisite repair in the findings, not speculative source changes. Do not invent results that were not provided. Do not run commands or edit tests.
7. Return a concise structured decision to the orchestrator.

Weighted Rubric

Score out of 100:

Scoring anchors:

• Full credit: clear artifact or code evidence supports the item.
• Half credit: partially satisfied, thinly evidenced, or has non-blocking gaps.
• Zero credit: missing, contradicted, unverifiable, or unsafe.

Hard Fails

Return REVISE_CODE regardless of score if any are true:

• Relevant test, build, lint, or typecheck output fails.
• Plan-named Mechanical command output is missing or failing.
• New or changed Mechanical test that asserts no relevant condition of the Objective (compile/lint/typecheck-only oracle). Mechanical and Observable may cover different parts of the outcome; do not demand a new end-to-end harness when focused assertions plus actual-surface proof suffice.
• High severity bug with direct code evidence.
• Security or privacy issue.
• Implementation contradicts plan.md.
• Unplanned scope drift.
• Overengineered solution where a simpler approach satisfies plan.md.

Return ASK_USER instead when the blocker is missing context, ambiguous product intent, unclear plan scope, or conflicting artifacts. Missing Mechanical output is REVISE_CODE, not ASK_USER.

Decision Rules

• APPROVE_CODE: no hard fail, score is 85 or higher, and remaining issues are low-risk or clearly optional.
• REVISE_CODE: hard fail applies, or score is below 85 with actionable implementation changes.
• ASK_USER: required inputs are missing, product behavior is ambiguous, or deciding would require guessing beyond the artifacts.

If REVISE_CODE, the caller routes the actual gap to its owner: missing receipts to implementation, failed prerequisites to setup, and demonstrated defects to implementation. Then obtain fresh review of the resulting candidate. Identify which prior findings and evidence remain valid and which need rechecking; a narrow correction need not repeat unrelated review, while coupled, uncertain, or consequential changes may warrant full fresh assurance. Compare repeated findings before proposing another edit; an unchanged failure calls for reconsideration. After 2 REVISE_CODE verdicts the caller stops with EXHAUSTED, including evidence-only rejections; carry prior verdicts across dispatches. If fresh delegation is unavailable, report the limitation, not APPROVE_CODE from self-review.

Output Format

Return exactly this structure:

## Code Quality Gate Result

- Decision: `APPROVE_CODE|REVISE_CODE|ASK_USER`
- Score: [0-100 or `N/A`]
- Reviewed: [plan.md, issue.md, diff/changed files, implementation summary, command outputs, quality docs]

### Findings

- [severity] [file:line or artifact] [specific issue or approval reason]
- [severity] [file:line or artifact] [specific issue or approval reason]

### Required Changes

- [Only for REVISE_CODE or ASK_USER; otherwise `None`]

### Next Action

- [run verification-gate / revise implementation / ask user]

Constraints

• Do not edit files.
• Do not implement fixes.
• Do not create review artifacts or helper files.
• Do not run Mechanical commands, tests, or broad QA. Require attached output; use verification-gate after approval.
• Do not duplicate the full quality docs; reference _ai/prompts/quality/code-review.md and _ai/prompts/quality/code-guidelines.md.
• Do not commit changes.
• Keep findings concise and evidence-based. Speculative risks must be marked low confidence or omitted.