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

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

---

Evidence Requirements

Every CRITICAL or WARNING finding must include concrete evidence. Findings without evidence are downgraded to INFO.

Evidence Types

Type	Example	When Required
Command output	npm test output showing failure	Test-related findings
Exit code	exit code 1 from eslint	Tool-based validation
Code citation	src/auth.ts:48 — \if (token) { ... }``	Logic or security findings
Git diff	+ db.query(userInput) (unsanitized)	Implementation review
Reproduction steps	"1. Send POST with empty body, 2. Observe 500"	Runtime behavior findings

Banned Phrases

The following phrases are not permitted in CRITICAL or WARNING findings. They indicate speculation, not evidence:

• "might be"
• "could potentially"
• "appears to"
• "seems like"
• "may not"

A finding using these phrases must either be rewritten with evidence or downgraded to INFO.

Verification Protocol

For each CRITICAL or WARNING finding, state:

1. What was tested — the specific code path, input, or scenario examined
2. What was observed — the actual behavior or code construct found
3. What correct behavior should be — the expected alternative

Downgrade Rule

If a reviewer produces a CRITICAL or WARNING finding without any of the evidence types above, the orchestrator downgrades it to INFO and emits a decision event:

./lib/archeflow-event.sh "$RUN_ID" decision check "" \
  '{"what":"evidence_downgrade","from":"CRITICAL","to":"INFO","finding":"<description>","reviewer":"<archetype>","reason":"no evidence provided"}'

---

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.