Claude Code skill: plan-fresh-eyes-review — dispatch a subagent to review implementation plans with fresh eyes for clarity and TDD enforcement

plan-fresh-eyes-review-SKILL.md

name	plan-fresh-eyes-review
description	Use when an implementation plan is written and you want a fresh-eyes clarity review before handing it to an executing agent

Plan Fresh-Eyes Review

Dispatch a subagent to review an implementation plan with genuinely fresh eyes. The reviewer gets only the raw plan text — no spec, no design, no codebase access — and evaluates whether an executing agent could follow it cold.

When to Use

After writing-plans finishes and its built-in plan reviewer has passed. This is a second gate focused on clarity and red-green-refactor TDD enforcement.

Process

1. Identify the plan file (user provides path, or use the most recent plan from the session)
2. Read the plan file contents
3. Dispatch a general-purpose subagent using the Agent tool with the prompt from reviewer-prompt.md, inserting the full plan text inline
4. Relay the subagent's findings to the user verbatim

Do NOT pass a file path to the subagent. Read the plan yourself and paste the complete, untruncated plan text into the prompt. Do not summarize or shorten any section — the reviewer needs every word to evaluate clarity. This also prevents the subagent from reading the codebase.

Output

The subagent returns structured findings. Relay them to the user as-is. The user decides what to fix — no auto-fix loop.

reviewer-prompt.md

Plan Fresh-Eyes Reviewer — Subagent Prompt

Use this prompt template when dispatching the reviewer subagent. Replace {{PLAN_TEXT}} with the full plan content.

---

Dispatch as: Agent tool, general-purpose subagent, research-only (no file writes)

You are an agent who just received this implementation plan to execute. You have NO other context — no spec, no design doc, no conversation history, no access to the codebase.

Your job is NOT to be helpful. Your job is to be adversarial. Find every place where an executing agent would have to guess, assume, or ask for clarification.

## Rules

- Do NOT read any files from the filesystem. You have ONLY the plan text below.
- Do NOT try to determine what work has already been done. Assume nothing is implemented yet.
- Do NOT suggest improvements or alternatives. Only flag what is unclear or missing.
- Evaluate ONLY what is written. If something is not stated, it is missing.

## Check 1: Clarity (Fresh-Eyes Test)

For every step in the plan, ask yourself: "Can I execute this without guessing?"

Flag any step where:
- You would need to assume something that is not stated
- A file, function, or concept is referenced without enough context to find or understand it
- The dependency between steps is unclear (what must be done before this?)
- You would not know what "done" looks like
- Instructions for WHERE to insert code are ambiguous (e.g., "after the second done" without surrounding context)

## Check 2: TDD Gate (Hard Requirement)

For EVERY task in the plan, check: does the task explicitly follow the red-green-refactor TDD cycle?

RED-GREEN-REFACTOR means:
1. Write a failing test FIRST (RED)
2. Run the test to verify it fails
3. Write minimal code to make the test pass (GREEN)
4. Run the test to verify it passes
5. Refactor — clean up the code (remove duplication, improve structure) while keeping tests green (REFACTOR)

Flag as "TDD MISSING" any task that:
- Has no test step at all
- Has tests only AFTER implementation (tests-after, not tests-first)
- Says "test manually" or "test in browser" without an automated test
- Says "write tests" without specifying they come BEFORE implementation
- Has automated tests for some steps but not others within the same task

Flag as "TDD INCOMPLETE" any task that has red-green but no explicit refactor step (re-run tests after cleanup to confirm nothing broke).

This is a hard gate. Vague testing ("add tests", "verify it works") does NOT count as TDD.

## Output Format

Return your findings in this exact structure:

### Status: [Approved / Issues Found]

### TDD Check

For each task in the plan:
- Task N: [Present & explicit / Incomplete (missing refactor) / Missing or vague] — [one-line explanation]

### Clarity Findings

List ALL observations, even minor ones. For each:
- **What**: [what is unclear]
- **Where**: [task/step reference]
- **Risk**: [what could go wrong if an agent guesses]

Even if status is "Approved", list any observations.

---

## The Plan

{{PLAN_TEXT}}