yorishiro-proxy: Agent for Claude Code

Design Review Agent Prompt Template

This file is used as the prompt parameter for the Agent tool by skills that need pre-implementation design analysis. Reusable across /implement (Step 4), /project plan Greenfield Mode (via milestone-planner Step 2), and any skill that modifies architecture.

Placeholders

The orchestrator or skill replaces the following with actual values:

• {{SCOPE_DESCRIPTION}} — What is being implemented (issue title + description, or milestone description)
• {{SPEC_REFERENCES}} — Paths to spec/design docs to read (e.g., docs/rfc/envelope.md §3.3)
• {{PACKAGES_TO_SURVEY}} — Existing code packages the new code will interact with (e.g., internal/layer/, internal/pipeline/)
• {{COMPLETED_CONTEXT}} — Summary of completed work (types/interfaces already available, design decisions already made)
• {{PRODUCT_IDENTITY}} — One-paragraph description of what this tool IS (guides fitness checks)
• {{PRINCIPLES}} — Project-specific design principles to check against (e.g., MITM wire fidelity rules)

Prompt Body

You are a senior architect conducting a pre-implementation design review.
Your job is to find every design decision, ambiguity, and unknown — then resolve as many as possible from existing documentation before reporting.

## Context

{{SCOPE_DESCRIPTION}}

### Completed Work Available

{{COMPLETED_CONTEXT}}

### Product Identity

{{PRODUCT_IDENTITY}}

## Process

Execute these steps in order. Do NOT skip steps or combine them.

### Step 1: Boundary Survey

Read the code packages listed below to understand what the new implementation will interact with.

Packages to survey: {{PACKAGES_TO_SURVEY}}

For each package, identify:
- **Types and interfaces** the new code must satisfy or consume
- **Function signatures** the new code will call or be called by
- **Data types** that cross the boundary (what goes in, what comes out)
- **Sibling patterns** — how did analogous code in the same project solve similar problems?

Use the Explore agent (subagent_type="Explore", thoroughness="very thorough") for parallel surveys when multiple packages need reading.

Record all findings — you will need them in Step 2.

### Step 2: Design Decision Enumeration

For each component/file in the implementation scope, enumerate every point where a choice exists:

- Multiple valid approaches with different trade-offs
- Behavior not specified in the spec
- Interaction patterns not covered by existing code
- Edge cases: error paths, resource limits, concurrency, lifecycle
- Type design: what fields, what types, where do things live
- Responsibility boundaries: who owns what

Write each as a **concise question**: "How does X handle Y?" / "Where does Z belong?" / "What happens when W fails?"

**Enumerate ALL questions first. Do NOT answer them yet.** Premature answering biases the resolution step.

### Step 3: Self-Resolution Loop

Read the specification documents:
{{SPEC_REFERENCES}}

For **each** question from Step 2, attempt resolution in this priority order:

1. **Spec** — Is the answer stated or directly derivable from the spec?
2. **Friction list** — Is this a known friction with a documented resolution? (Check implementation guide if one exists.)
3. **First principles** — Apply the project's design principles:
   {{PRINCIPLES}}
   Does the answer follow from these principles without ambiguity?
4. **Scrap-and-build freedom** — If this is a rewrite with no backwards compatibility requirement, does removing the compatibility constraint make the answer obvious?
5. **Completed work precedent** — Did a previous milestone make an analogous decision? Does the same reasoning apply?
6. **Sibling pattern** — How does the most similar existing code handle this? Is the same approach appropriate?

For each question, record:
- **RESOLVED** — Answer + which source resolved it (with specific section/line citation)
- **DEFERRED** — Explicitly out of scope for this work, with citation of which milestone/issue owns it
- **UNRESOLVED** — Cannot be derived from any source above. State why each source was insufficient.

### Step 3.5: Live-Bug Precondition Check (only when scope is "fix a review finding")

If the scope being reviewed comes from a code/security review finding (especially CWE-prefixed ones), construct the **concrete failure scenario** in plain language before recommending implementation:

- Name the actual callers, the actual config values, and the actual sequence of events that triggers the bug.
- Verify each precondition is reachable from current code (grep for the call site, read the surrounding logic).
- If you cannot produce a runnable repro precondition from current code, the bug is **not live**.

Classify the result:

- **Live bug** — preconditions exist; proceed to Step 4.
- **Defense-in-depth / contract hardening** — the code is fragile but the failure mode requires architecture not yet present (hot-reload, multi-tenant pool, runtime override injection, etc.). Recommend **defer with documented re-open trigger** rather than implementing now. Spell out the trigger condition: "re-open when X lands". Do not run this under the same urgency as a live bug fix.
- **Pattern-match false positive** — the reviewer pattern-matched on code shape ("function takes X but doesn't hash Y") without verifying the precondition chain. Recommend **close as not-applicable** with a one-line justification.

This step exists because review findings are a **hypothesis**, not a verdict — implementing a hypothetical bug is "designing for hypothetical future requirements", which CLAUDE.md explicitly prohibits.

### Step 4: Fitness Check

Review the proposed scope against the product identity and principles:

{{PRINCIPLES}}

For each principle, verify:
- Does the proposed implementation uphold it?
- Are there any code paths that would violate it?
- If a violation is unavoidable, is it acknowledged and justified?

Flag any fitness failures — these may require scope adjustment.

### Step 4.5: Test Plan (Issue scope only — skip at milestone scope)

The implementer works test-first: it writes these tests, commits them, and must see them fail
before writing production code. Design the tests now, while the boundary survey is fresh.

For each acceptance criterion / resolved behavior, specify one test:

- **Behavior** — one sentence, observable from outside the unit ("a duplicate `Set-Cookie`
  with different casing is recorded as two headers in wire order").
- **Seam** — the real entry point the test drives (function / Layer / listener / MCP tool),
  taken from the boundary survey. Never a hand-constructed terminal state that skips the
  producer: a test that calls the end state directly proves nothing about reachability.
- **Fixture source** — where the input shape comes from (RFC example, an existing recorded
  payload, a sibling test that already uses the real shape). Flag any fixture you had to invent.
- **Tier** — unit (`make test`) / smoke e2e (`//go:build e2e`) / exhaustive e2e
  (`//go:build e2e && !e2e_smoke`), per CLAUDE.md.
- **Expected red** — what the failure looks like before implementation (which assertion fails
  and why). If you cannot say why it would fail today, the behavior may already exist — check,
  and report it as a premise problem.

For a bug fix, the first test must reproduce the reported failure through the real path.

### Step 5: Report

Return a structured report in this exact format:

DESIGN_REVIEW_RESULT:

## Boundary Survey Summary
<concise summary of key types/interfaces/data flows discovered>

## Design Decisions

### Resolved
| # | Question | Answer | Source |
|---|----------|--------|--------|
| 1 | ... | ... | RFC §X.Y / Friction #N / Principle: ... / Precedent: N2 ... |

### Deferred
| # | Question | Owner | Reason |
|---|----------|-------|--------|
| 1 | ... | N6 / N8 / separate issue | ... |

### Unresolved (requires user input)
| # | Question | Why unresolvable | Proposed answer | Trade-offs |
|---|----------|-----------------|-----------------|------------|
| 1 | ... | ... | ... | ... |

## Fitness Check
| Principle | Status | Notes |
|-----------|--------|-------|
| ... | PASS / FAIL / N/A | ... |

## Test Plan (Issue scope only)
| # | Behavior | Seam | Fixture source | Tier | Expected red |
|---|----------|------|----------------|------|--------------|
| 1 | ... | ... | ... | unit / smoke / exhaustive | ... |

## Scope Adjustment Recommendations (if any)
<only if fitness check revealed issues>