claude-archeflow-plugin/skills/check-phase/SKILL.md

---
name: check-phase
description: Use when you are acting as Guardian, Skeptic, Sage, or Trickster archetype in the Check phase. Defines shared review rules and output format.
---

# Check Phase

Multiple reviewers examine the Maker's implementation in parallel. Each agent definition has its specific protocol — this skill defines the shared rules.

## Shared Rules

1. **Read the proposal first.** Review against the intended design, not invented requirements.
2. **Read the actual code.** Use `git diff` on the Maker's branch. Don't review descriptions alone.
3. **Structured findings.** Use the standardized finding format below for every issue.
4. **Clear verdict:** `APPROVED` or `REJECTED` with rationale.
5. **Status tokens are separate from verdicts.** The `STATUS: DONE` line signals the agent finished successfully. The `APPROVED`/`REJECTED` verdict is domain output. A reviewer can be `STATUS: DONE` with verdict `REJECTED` — that is normal. Parse both independently.

## Finding Format

Every finding must use this format for cross-cycle tracking:

```
| Location | Severity | Category | Description | Fix |
|----------|----------|----------|-------------|-----|
| src/auth/handler.ts:48 | CRITICAL | security | Empty string bypasses validation | Add length check before processing |
```

**Severity:**
- **CRITICAL** — Must fix. Blocks approval.
- **WARNING** — Should fix. Doesn't block alone.
- **INFO** — Nice to have. Never blocks.

**Categories** (use consistently for cross-cycle tracking):
- `security` — Injection, auth bypass, data exposure, secrets
- `reliability` — Error handling, edge cases, race conditions, crashes
- `design` — Architecture, assumptions, scalability, coupling
- `breaking-change` — API compatibility, schema migrations, removals
- `dependency` — New deps, version conflicts, license issues
- `quality` — Readability, maintainability, naming, duplication
- `testing` — Missing tests, weak assertions, untested paths
- `consistency` — Deviates from codebase patterns

## Consolidated Output

After all reviewers finish, compile:

```markdown
## Check Phase Results — Cycle N

### Guardian: APPROVED
| Location | Severity | Category | Description | Fix |
|----------|----------|----------|-------------|-----|
| src/auth/handler.ts:52 | WARNING | security | Missing rate limit | Add rate limiter middleware |

### Skeptic: APPROVED
| Location | Severity | Category | Description | Fix |
|----------|----------|----------|-------------|-----|
| src/auth/handler.ts:30 | INFO | design | Consider caching validated tokens | Add TTL cache for token validation |

### Sage: APPROVED
| Location | Severity | Category | Description | Fix |
|----------|----------|----------|-------------|-----|
| tests/auth.test.ts:15 | WARNING | testing | Test names don't describe behavior | Rename to "should reject expired tokens" |

### Trickster: REJECTED
| Location | Severity | Category | Description | Fix |
|----------|----------|----------|-------------|-----|
| src/auth/handler.ts:48 | CRITICAL | reliability | Empty string bypasses validation | Add `if (!token || token.trim() === '')` guard |

### Deduplication
If two reviewers raise the same issue (same file + same category), merge:
| Guardian + Skeptic | CRITICAL | security | Input not sanitized (src/api.ts:30) | Add validation |

Use the higher severity. Don't double-count in the verdict.

### Verdict: REJECTED — 1 critical finding
→ Build cycle feedback (see orchestration skill) and feed to Plan phase
```

## Reviewer Spawning Protocol

This section defines the exact sequence for spawning reviewers in the Check phase.

### Step 1: Guardian First (mandatory)

Guardian always runs first, before any other reviewer. It receives the Maker's git diff and the proposal's risk section only.

**Context for Guardian:**
- `git diff main...<maker-branch>` (the actual code changes)
- Risk section from `plan-creator.md` (if present)
- Do NOT include: Explorer research, full proposal, other reviewer outputs

```
Agent(
  description: "Guardian: security and risk review for <task>",
  prompt: "You are the GUARDIAN archetype.
    Review the diff: <maker's diff>
    Proposal risks: <risk section from plan-creator.md>
    Assess: security vulnerabilities, reliability risks, breaking changes, dependency risks.
    Output: APPROVED or REJECTED with findings in the standardized format.
    Each finding: | Location | Severity | Category | Description | Fix |",
  model: <resolve_model guardian $WORKFLOW>
)
```

Save output to `.archeflow/artifacts/${RUN_ID}/check-guardian.md`.

### Step 2: A2 Fast-Path Evaluation

After Guardian completes, parse its output before spawning other reviewers:

```bash
CRITICAL_COUNT=$(grep -c "| CRITICAL |" ".archeflow/artifacts/${RUN_ID}/check-guardian.md" || echo 0)
WARNING_COUNT=$(grep -c "| WARNING |" ".archeflow/artifacts/${RUN_ID}/check-guardian.md" || echo 0)

# A2 fast-path: skip remaining reviewers if Guardian is clean
# Exception: first cycle of thorough workflows always spawns all reviewers
if [[ "$CRITICAL_COUNT" -eq 0 && "$WARNING_COUNT" -eq 0 \
      && "$ESCALATED" != "true" \
      && ! ("$WORKFLOW" == "thorough" && "$CYCLE" -eq 1) ]]; then
  echo "Guardian fast-path: 0 CRITICAL, 0 WARNING — skipping remaining reviewers."
  # Proceed directly to Act phase
fi
```

### Step 3: Parallel Reviewer Spawning

If A2 does not trigger, spawn remaining reviewers in parallel based on workflow:

| Workflow | Reviewers (after Guardian) |
|----------|--------------------------|
| `fast` | None (Guardian only) |
| `fast` (escalated via A1) | Skeptic + Sage |
| `standard` | Skeptic + Sage |
| `thorough` | Skeptic + Sage + Trickster |

Spawn all applicable reviewers in a single message with multiple Agent calls:

```
# Standard workflow example — spawn Skeptic and Sage in parallel:
Agent(
  description: "Skeptic: challenge assumptions for <task>",
  prompt: "<Skeptic prompt with Creator's proposal>",
  model: <resolve_model skeptic $WORKFLOW>
)

Agent(
  description: "Sage: holistic quality review for <task>",
  prompt: "<Sage prompt with proposal + diff + implementation summary>",
  model: <resolve_model sage $WORKFLOW>
)
```

Each reviewer gets context per the attention filters defined in `archeflow:orchestration`:
- **Skeptic:** Creator's proposal (assumptions section focus)
- **Sage:** Creator's proposal + Maker's diff + implementation summary
- **Trickster:** Maker's diff only

### Step 4: Collect Results

Wait for all spawned reviewers to return. For each:
1. Save output to `.archeflow/artifacts/${RUN_ID}/check-<archetype>.md`
2. Emit `review.verdict` event with findings
3. Record sequence number for DAG parent tracking

### Timeout Handling

Each reviewer has a **5-minute timeout**. If a reviewer does not return within 5 minutes:
1. Emit `agent.complete` with `"error": true, "reason": "timeout"`
2. Log a WARNING — do not block the run
3. Treat the timed-out reviewer as having delivered no findings (neither approved nor rejected)
4. Proceed with available verdicts

If Guardian times out, this is a blocking failure — abort the Check phase and report to the user.

### Re-Check Protocol (Act Phase Fixes)

When the Act phase routes findings back to the Maker and the Maker applies fixes in a subsequent cycle, the Check phase re-runs with the updated diff. Reviewers who previously rejected should focus on whether their specific findings were addressed. The structured feedback from `act-feedback.md` provides the mapping of which findings were routed where.

---

## Why Structured Findings Matter

The standardized format enables:
- **Cross-cycle tracking:** Same category + location = same issue. Can detect resolution or regression.
- **Feedback routing:** Security/design findings → Creator. Quality/testing findings → Maker.
- **Shadow detection:** CRITICAL:WARNING ratios, finding counts, and category distributions are measurable.
- **Metrics:** Severity counts feed into the orchestration summary.