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

---
name: plan-phase
description: Use when acting as Explorer or Creator in the Plan phase. Defines output formats for research and proposals.
---

# Plan Phase

Explorer researches, then Creator designs. Sequential — Creator needs Explorer's findings.

## Explorer Output Format

```markdown
## Research: <task>

### Affected Code
- `path/file.ext` — description (L<start>-<end>)

### Dependencies
- What depends on what, what breaks if changed

### Patterns
- How the codebase solves similar problems

### Risks
- What could go wrong

### Recommendation
<one paragraph: approach + rationale>
```

## Creator Output Format

```markdown
## Proposal: <task>

### Mini-Reflect (fast workflow only — skip if Explorer ran)
- **Task restated:** <one sentence>
- **Assumptions:** 1) ... 2) ... 3) ...
- **Highest-damage risk:** <the one thing that would hurt most if wrong>

### Architecture Decision
<What and WHY>

### Alternatives Considered
| Approach | Why Rejected |
|----------|-------------|
| <option A> | <reason> |
| <option B> | <reason> |

### Changes
1. **`path/file.ext`** — What changes and why
2. **`path/test.ext`** — What tests to add

### Test Strategy
- <specific test cases>

### Confidence
| Axis | Score | Note |
|------|-------|------|
| Task understanding | <0.0-1.0> | <why> |
| Solution completeness | <0.0-1.0> | <gaps?> |
| Risk coverage | <0.0-1.0> | <unknowns?> |

### Risks
- <what could go wrong + mitigations>

### Not Doing
- <adjacent concerns deliberately excluded>
```

**Confidence triggers:** If any axis scores below 0.5, flag it to the orchestrator. Low task understanding → clarify with user. Low solution completeness → consider standard workflow. Low risk coverage → spawn targeted Explorer research.

## Creator with Prior Feedback (Cycle 2+)

When the Creator receives structured feedback from a prior cycle, the proposal must include an additional section addressing each unresolved issue:

```markdown
## Proposal: <task> (Revision — Cycle N)

### What Changed (vs. prior proposal)
- <brief delta: what was added, removed, or redesigned>

### Prior Feedback Response
| Issue | Source | Action | Rationale |
|-------|--------|--------|-----------|
| SQL injection in user input | Guardian | **Fixed** — added parameterized queries | Direct security fix |
| Assumes single-tenant | Skeptic | **Deferred** — multi-tenant out of scope | Not in task requirements |
| Test names unclear | Sage | **Accepted** — routed to Maker | Implementation concern |

### Architecture Decision
<revised design addressing feedback>

### Changes
<updated file list>

### Test Strategy
<updated test cases>

### Confidence
| Axis | Score | Note |
|------|-------|------|
| Task understanding | <0.0-1.0> | <why> |
| Solution completeness | <0.0-1.0> | <gaps?> |
| Risk coverage | <0.0-1.0> | <unknowns?> |

### Risks
<updated risks — include any new risks from the revision>

### Not Doing
<updated scope boundaries>
```

**Rules for addressing feedback:**
- **Fixed:** Changed the design to resolve the issue. Explain how.
- **Deferred:** Not addressing now, with explicit reason. Must not be a CRITICAL finding.
- **Accepted:** Acknowledged and routed to Maker for implementation-level fix.
- **Disputed:** Disagrees with the finding. Must provide evidence or reasoning.

CRITICAL findings cannot be deferred or disputed — they must be fixed or the proposal will be rejected again.

## Task Granularity

Each change item in the Creator's proposal must be a **2-5 minute task** — specific enough that the Maker can implement it without interpretation.

### Requirements per Change Item

Every item in the `### Changes` section must include:

1. **Exact file path** — `src/auth/handler.ts`, not "the auth module"
2. **What to change** — a code block showing the target state or transformation
3. **How to verify** — a command or check that confirms correctness

### Good Example

```markdown
1. **`src/auth/handler.ts:48`** — Add input length validation before token processing
   ```typescript
   if (!token || token.trim().length === 0) {
     throw new ValidationError('Token must not be empty');
   }
   ```
   **Verify:** `npm test -- --grep "empty token"` passes
```

### Bad Example

```markdown
1. **Auth module** — Fix the validation logic
```

This is too vague. Which file? Which function? What does "fix" mean? The Maker will guess.

### Granularity Check

- If a single change item would take **>5 minutes**, split it into smaller items
- If a non-trivial task has **<2 change items**, it is under-specified — the Creator missed something
- Each item should touch **1-2 files** at most. Cross-cutting changes need separate items per file.

---

## Explorer Skip Conditions

Not every task needs Explorer research. Use this decision table:

| Condition | Skip Explorer? | Reason |
|-----------|---------------|--------|
| Task names specific files (1-2) and change is clear | **Yes** | Context is already known |
| Bug fix with stack trace or error message | **Yes** | Root cause is locatable without research |
| High confidence + small scope (single function/class) | **Yes** | Creator can mini-reflect instead |
| Task contains "investigate", "research", "explore" | **No** | Explicit research request |
| Task affects >3 files or unknown scope | **No** | Need dependency mapping |
| Unfamiliar area of codebase (no recent commits by team) | **No** | Need pattern discovery |
| Security-sensitive change (auth, crypto, input handling) | **No** | Need risk surface mapping |

When Explorer is skipped, Creator MUST include the **Mini-Reflect** section in its proposal to compensate for missing research context.