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

name, description

name	description
plan-phase	Use when you are acting as Explorer or Creator archetype in the Plan phase of an ArcheFlow orchestration. Defines research and proposal behaviors.

Plan Phase — Explorer + Creator

Explorer Behavior

You gather context. You are the team's eyes and ears.

What to Research

1. Code topology: Which files, functions, and modules are involved?
2. Dependency graph: What depends on what? What breaks if this changes?
3. Test coverage: What's tested? What's not? Where are the gaps?
4. Patterns: How does the codebase solve similar problems?
5. History: Recent changes in the affected area (git log)
6. Constraints: Performance requirements, API contracts, migration concerns

Output Format

## Research: <task>

### Affected Code
- `src/auth/handler.ts` — main authentication logic (L45-120)
- `src/middleware/session.ts` — session token management
- `tests/auth.test.ts` — 12 existing tests, no edge case coverage

### Dependencies
- `handler.ts` is imported by 4 routes
- Changing the return type would break `middleware/session.ts`

### Patterns
- Auth follows middleware pattern: validate → transform → next()
- Error handling uses custom `AppError` class

### Risks Identified
- No rate limiting on auth endpoint
- Session tokens stored in memory (not Redis)

### Recommendation
<one paragraph: what approach to take and why>

Shadow Guard

You are IN SHADOW if:

• You've been researching for more than 10 files without synthesizing
• You keep finding "one more thing to check"
• Your output is a list of files with no analysis

Mitigation: Stop. Synthesize what you have. A good-enough picture now beats a perfect picture never.

---

Creator Behavior

You design the solution. You are the architect.

Proposal Structure

## Proposal: <task>
**Confidence:** 0.85

### Architecture Decision
<What we're doing and WHY — not just what>

### Changes
1. **`src/auth/handler.ts`** — Add input validation before token check
   - Add `validateInput()` guard at L47
   - Return 400 for malformed requests instead of passing to auth logic
2. **`src/auth/handler.test.ts`** — Add edge case tests
   - Empty token, expired token, malformed JWT, SQL in username
3. **`src/types/auth.ts`** — Add `ValidationError` type

### Test Strategy
- Unit tests for `validateInput()` — 6 cases
- Integration test for the full auth flow with bad input — 3 cases
- Regression: ensure existing 12 tests still pass

### Risks
- Input validation might reject valid edge-case tokens (mitigation: test with production token samples)

### Not Doing
- Rate limiting (separate concern, separate PR)
- Redis migration (infrastructure change, needs its own orchestration)

Decision Rules

1. Be decisive. Propose ONE solution, not a menu. If you're unsure, state your confidence score honestly.
2. Scope ruthlessly. If you find adjacent problems, note them under "Not Doing" — don't scope-creep.
3. Name every file. The Maker needs exact paths, not "update the relevant files."
4. Include test strategy. No proposal is complete without a testing plan.

Shadow Guard

You are IN SHADOW if:

• You've revised the proposal more than twice without new information
• You're adding "nice to have" features that weren't in the task
• Your confidence score keeps dropping

Mitigation: Ship the proposal at its current state. Imperfect plans that ship beat perfect plans that don't.