CocoreviewSAFE

CocoPlus is an Agentic Operating System for Snowflake Coco. It brings structured, multi-agent workflows to data engineering projects — covering everything from project initialization through spec, plan, build, test, review, and ship phases.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: cocoreview
description: CocoReview — structured code review with six-severity findings vocabulary, progressive disclosure architecture, and universal anti-pattern baseline. Invoked via $review [file] [--complexity] [--security] [--architecture] [--language <lang>].
version: "1.4.0"
author: CocoPlus
tags:
  - cocoreview
  - code-review
  - delivery-discipline
user-invocable: true
blocking: true
---

## Objective

You are executing CocoReview — a structured, evidence-grounded code review. Your task is to produce an actionable prioritized finding report using the six-severity vocabulary and the four-phase review process.

Before proceeding, verify that `.cocoplus/` exists. If not, output: "CocoPlus is not initialized. Run `$pod init` first." Then stop.

## Routing Table

| Invocation | Loads |
|------------|-------|
| `$review <file>` | `universal-quality.md` + language guide inferred from file extension |
| `$review --security` | `universal-quality.md` + language guide + `security-review.md` |
| `$review --architecture` | `universal-quality.md` + `architecture-review.md` |
| `$review --complexity` | Run `cocoreview/pr-complexity` only — no LLM review |
| `$review --language <lang>` | `universal-quality.md` + explicit language guide |
| `$review export markdown|html|pdf [report]` | Route to `.cortex/skills/cocoreview/review-export/SKILL.md` |

## Step 1 — Parse Invocation and Run Complexity Analyzer

Parse the `$review` command for file path and flags. If no file path provided for non-complexity commands, ask: "Which file or directory should I review?"

**Always run `cocoreview/pr-complexity` first** (before any LLM work):

```
invoke cocoreview/pr-complexity --file <path>
```

Read the output JSON. If `size_bucket` is `XL` (≥800 lines of change), surface a split recommendation:

```
⚠ CocoReview: This artifact is in the XL complexity bucket (<N> lines changed, complexity score <score>).
XL changes are significantly harder to review effectively. Consider splitting into:
- Schema/model changes (separate PR)
- Logic/transformation changes (separate PR)
- Test additions (can merge with logic changes)

Proceed with full review anyway? [YES/SPLIT]
```

If `--complexity` flag: display complexity output and stop (no LLM review).

## Step 2 — Load Reference Guides

Based on routing table above, load the appropriate guides from `.cortex/skills/cocoreview/`. Always load `universal-quality.md`. Load others based on flags and risk_flags from complexity analyzer output (e.g., if `security-sensitive` in risk_flags, load `security-review.md`).

## Step 3 — Context Gathering (Phase 1: ~2–3 minutes)

Before reviewing implementation, understand WHY the change exists:
- Read PR description if available (`.cocoplus/review/pr-description.md` or ask developer for context)
- Read linked issue or spec if referenced
- Check if this is part of an active CocoBrew lifecycle phase (read `lifecycle/meta.json`)

## Step 4 — High-Level Review (Phase 2: ~5–10 minutes)

Architecture and strategy BEFORE line-level inspection:
- Does the solution fit the problem? Is the approach right?
- Is the file organization coherent? Does it follow the project's structure (read `cocoplus-context.md` if present)?
- Is the test strategy adequate for the change scope?

**If architectural problems found: surface them now before line-by-line work begins.** There is no value in perfecting the implementation of a structurally wrong design.

## Step 5 — Line-by-Line Review (Phase 3: ~10–20 minutes)

Apply the loaded reference guides. For each finding, assign a severity from the six-severity vocabulary:

| Label | Meaning | Effect on Verdict |
|-------|---------|-------------------|
| `blocking` | Must resolve before merge | → REQUEST_CHANGES |
| `important` | Should resolve | → COMMENT or REQUEST_CHANGES |
| `nit` | Minor style concern | Non-blocking |
| `suggestion` | Optional improvement | Non-blocking |
| `learning` | Educational context note | Non-blocking |
| `praise` | Well-constructed pattern | Mandatory if good patterns exist |

**Reuse check is first-class:** Before accepting new code, verify no existing utility already covers the case. For Snowflake: before a new UDF, check if an existing function can be parameterized; before a new pipeline, check if an existing one can be extended.

**TOCTOU detection:** Specifically flag Snowflake `IF EXISTS THEN INSERT` patterns and recommend `MERGE` instead.

**Mandatory praise:** If ANY well-constructed pattern exists in the artifact, emit at least one `praise` finding. If no well-constructed pattern is found, emit: `praise: Evaluation scope was limited — no exemplary patterns identified in this review.`

**METR taxonomy classification:** Classify every Phase 1 (universal anti-pattern) finding under one of five METR categories — sourced from METR's real-world evaluation findings on the empirical gap between benchmark pass rates and actual merge outcomes:

| Category | Covers |
|----------|--------|
| `code-quality` | Correctness defects, logic errors, missing null/error handling |
| `style` | Naming, formatting, convention deviation |
| `scope` | Change touches more than the stated task requires |
| `collateral-effects` | Change has side effects on unrelated behavior or callers |
| `defensive-code` | Missing or excessive defensive checks relative to actual trust boundary |

**Evidence citation requirement:** Every `blocking` and `important` finding must cite the evidence tier that grounds it: `e2e` (observed failure against a real execution), `reference` (contradicts an externally sourced standard), or `project-historical` (contradicts a documented prior decision in `cocoplus-context.md` or `plan.md`). A finding citing only `unit` evidence (a self-constructed test case) or `self-assessment` (the reviewing agent's own judgment with no external grounding) **may not exceed `nit` severity** — regardless of how confident the finding reads.

Finding format with taxonomy and evidence:
```yaml
-

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.