---
name: act-phase
description: |
  Use after the Check phase completes. Collects reviewer findings, routes fixes, applies them, decides whether to exit or cycle.
  <example>Automatically loaded during orchestration after Check phase</example>
---

# Act Phase

Turn Check phase findings into fixes, then decide: exit or cycle.

```
Check output → Collect → Deduplicate → Route → Fix → Exit or Cycle
```

---

## Step 1: Collect and Consolidate Findings

Parse all reviewer outputs into one table grouped by severity (CRITICAL / WARNING / INFO):

| # | Source | Location | Category | Description | Suggested Fix |
|---|--------|----------|----------|-------------|---------------|
| 1 | guardian | src/auth/handler.ts:48 | security | Empty string bypasses validation | Add length check |

### Deduplication

Same file + same category + similar description = one finding. Use the higher severity, credit all sources (e.g. `guardian + skeptic`).

### Cross-Cycle Tracking (cycle > 1)

Compare against prior cycle findings:
- **Resolved** — no longer present, mark resolved, do not re-raise
- **Persisting** — same location + category, increment `cycle_count`
- **New** — first appearance, `cycle_count: 1`

Finding persisting 2+ cycles = flag for escalation (see Step 4).

---

## Step 2: Fix Routing

This is the **canonical routing table** (single source of truth for the whole system):

| Source | Category | Routes to | Reason |
|--------|----------|-----------|--------|
| Guardian | security, breaking-change | Creator | Design must change |
| Guardian | reliability, dependency | Creator | Architectural decision needed |
| Skeptic | design, scalability | Creator | Assumptions need revision |
| Sage | quality, consistency | Maker | Implementation refinement |
| Sage | testing | Maker | Test gap, not design flaw |
| Trickster | reliability (design flaw) | Creator | Needs redesign |
| Trickster | reliability (test gap), testing | Maker | Needs more tests |

**Disambiguation:** If the fix requires changing the approach → Creator. If it requires changing code within the existing approach → Maker.

### Direct Fix (no agent)

Apply with Edit tool when **all** are true:
- Mechanical (typo, naming, formatting, import order)
- No behavioral change
- No test update needed
- Single file

### Maker Fix (spawn agent)

Spawn a targeted Maker when the fix involves code logic, tests, multiple files, or behavioral changes. Batch findings in the same file area into one Maker spawn.

```
Agent(
  description: "Fix: <description>",
  prompt: "You are the MAKER archetype.
    Branch: <maker's branch>
    Findings:
    1. [CRITICAL] file:line — issue → suggested fix
    2. [WARNING] file:line — issue → suggested fix
    Rules: fix ONLY these issues, add/update tests if behavior changes,
    run tests, commit each fix separately as 'fix: <description>'.
    Do NOT refactor surrounding code.",
  isolation: "worktree",
  mode: "bypassPermissions"
)
```

### Design Fix (route to Creator)

Design findings are NOT fixed in Act. Collect them into `act-feedback.md` for the Creator in the next cycle (see Step 5).

---

## Step 3: Fix Application

Apply in severity order: CRITICAL → WARNING → INFO. Within same severity, group by file.

For each fix:
1. Apply the change (direct edit or via Maker agent)
2. Emit `fix.applied` event with source, finding, file, severity, before/after
3. For non-trivial fixes: re-run only the originating reviewer scoped to changed files. New findings from re-check get added with source `re-check:<reviewer>`

---

## Step 4: Exit Decision

```
CRITICAL = 0 AND criteria met        → EXIT: proceed to merge
CRITICAL = 0 AND criteria NOT met    → CYCLE: feedback to Creator
CRITICAL > 0 AND cycles remaining    → CYCLE: build feedback, go to Plan
CRITICAL > 0 AND no cycles left      → STOP: report unresolved to user
Same CRITICAL persists 2+ cycles     → ESCALATE: ask user for guidance
```

Emit `cycle.boundary` event with: cycle number, max_cycles, critical/warning/info remaining, fixes applied, next action.

---

## Step 5: Cycle Feedback

When cycling back, produce `act-feedback.md`:

```markdown
## Cycle N → Cycle N+1

### For Creator (design changes needed)
| # | Source | Severity | Category | Issue | Cycles Open |
|---|--------|----------|----------|-------|-------------|

### For Maker (implementation fixes needed)
| # | Source | Severity | Category | Issue | Cycles Open |
|---|--------|----------|----------|-------|-------------|

### Resolved This Cycle
| # | Source | Issue | How Resolved |
|---|--------|-------|--------------|

### Persisting Issues (escalation candidates)
| # | Source | Issue | Cycles Open | Action |
|---|--------|-------|-------------|--------|
```

Route findings into Creator vs Maker sections using the routing table in Step 2.