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

name, description

name	description
check-phase	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.

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:

## 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:

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.