142 lines
4.2 KiB
Markdown
142 lines
4.2 KiB
Markdown
---
|
|
name: review
|
|
description: |
|
|
Review-only mode. Run Guardian + optional reviewers on an existing diff or branch,
|
|
without any Plan/Do orchestration. The highest-ROI mode for catching design-level bugs.
|
|
<example>User: "af-review"</example>
|
|
<example>User: "Review the last commit"</example>
|
|
<example>User: "af-review --reviewers guardian,skeptic"</example>
|
|
---
|
|
|
|
# ArcheFlow Review Mode
|
|
|
|
Run reviewers on existing code changes without orchestrating implementation.
|
|
This is the most cost-effective mode — it delivers Guardian's error-path analysis
|
|
without the Maker overhead.
|
|
|
|
## When to Use
|
|
|
|
- After you've implemented something and want a quality check
|
|
- On a PR or branch before merging
|
|
- When the sprint runner flags a task as DONE_WITH_CONCERNS
|
|
- As a pre-commit quality gate for complex changes
|
|
|
|
## Invocation
|
|
|
|
```
|
|
af-review # Review uncommitted changes
|
|
af-review --branch feat/batch-api # Review branch diff against main
|
|
af-review --commit HEAD~3..HEAD # Review last 3 commits
|
|
af-review --reviewers guardian,skeptic,sage # Choose reviewers (default: guardian)
|
|
af-review --evidence # Enable evidence-gating (stricter)
|
|
```
|
|
|
|
---
|
|
|
|
## Execution
|
|
|
|
### Step 1: Get the Diff
|
|
|
|
```bash
|
|
# Uncommitted changes
|
|
DIFF=$(git diff HEAD)
|
|
|
|
# Branch diff
|
|
DIFF=$(git diff main...HEAD)
|
|
|
|
# Commit range
|
|
DIFF=$(git diff HEAD~3..HEAD)
|
|
|
|
# If diff is too large (>500 lines), split by file
|
|
if [[ $(echo "$DIFF" | wc -l) -gt 500 ]]; then
|
|
# Review per-file to keep context focused
|
|
FILES=$(git diff --name-only HEAD)
|
|
fi
|
|
```
|
|
|
|
### Step 2: Spawn Reviewers
|
|
|
|
Default: Guardian only (fastest, highest ROI).
|
|
With `--reviewers`: spawn requested reviewers in parallel.
|
|
|
|
**Guardian** (always first):
|
|
```
|
|
Agent(
|
|
description: "Guardian: review changes for <project>",
|
|
prompt: "You are the GUARDIAN archetype — security and risk reviewer.
|
|
|
|
Review this diff for: security vulnerabilities, error handling gaps,
|
|
data loss scenarios, race conditions, and breaking changes.
|
|
|
|
For each finding: cite specific code (file:line), state what you tested
|
|
or observed, state what the correct behavior should be.
|
|
|
|
Diff:
|
|
<DIFF>
|
|
|
|
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED",
|
|
subagent_type: "code-reviewer"
|
|
)
|
|
```
|
|
|
|
**Skeptic** (if requested):
|
|
- Focus: hidden assumptions, edge cases, scalability
|
|
- Context: diff + any design docs
|
|
|
|
**Sage** (if requested):
|
|
- Focus: code quality, test coverage, maintainability
|
|
- Context: diff + surrounding code
|
|
|
|
**Trickster** (if requested):
|
|
- Focus: adversarial inputs, failure injection, chaos testing
|
|
- Context: diff only
|
|
|
|
### Step 3: Collect and Report
|
|
|
|
Parse each reviewer's output. Show findings:
|
|
|
|
```
|
|
── af-review: <project> ───────────────────────
|
|
Reviewers: guardian, skeptic
|
|
|
|
🛡️ Guardian: 2 findings (1 HIGH, 1 MEDIUM)
|
|
[HIGH] Timeout marks variant as done — loses batch state (fanout.py:552)
|
|
[MEDIUM] No JSON error handling on corrupted state (batch.py:310)
|
|
|
|
🤔 Skeptic: 1 finding (1 INFO)
|
|
[INFO] hash() non-deterministic across processes (fanout.py:524)
|
|
|
|
Total: 3 findings (1 HIGH, 1 MEDIUM, 1 INFO)
|
|
────────────────────────────────────────────────
|
|
```
|
|
|
|
### Step 4: Evidence Gate (if --evidence)
|
|
|
|
When `--evidence` is active, apply the evidence requirements from `archeflow:check-phase`:
|
|
- Scan findings for banned phrases ("might be", "could potentially", etc.)
|
|
- Check for evidence markers (exit codes, line numbers, reproduction steps)
|
|
- Downgrade unsupported findings to INFO
|
|
|
|
---
|
|
|
|
## Integration with Sprint Runner
|
|
|
|
The sprint runner can invoke `af-review` automatically:
|
|
|
|
| Sprint trigger | Review action |
|
|
|----------------|--------------|
|
|
| Task marked DONE_WITH_CONCERNS | Run Guardian on the agent's changes |
|
|
| Task is L/XL estimate | Run Guardian + Skeptic after completion |
|
|
| Task involves security keywords | Run Guardian automatically |
|
|
| User requests | Run specified reviewers |
|
|
|
|
---
|
|
|
|
## Cost
|
|
|
|
Review-only is 60-80% cheaper than full PDCA:
|
|
- No Explorer research (~30% of PDCA cost)
|
|
- No Creator planning (~20% of PDCA cost)
|
|
- No Maker implementation (already done)
|
|
- Only reviewer token costs remain
|