Arguments

[optional: path to plan document]

Fresh Eyes

Run a high-signal quality gate on a plan and improve it in place.

Input Resolution

Primary input: $ARGUMENTS

If a path is provided, use it. If no path is provided:

1. Check docs/plans/ for the most recent *.md.
2. If none, check docs/brainstorms/.
3. If still none, check current directory for plan-like markdown files.
4. If no candidate exists, ask the user for a path and stop.

Workflow

1. Re-anchor Project Constraints

Before reviewing, re-read AGENTS.MD and any local conventions relevant to planning. Use these constraints as hard checks while reviewing.

2. Build Plan Understanding First

Read the entire document once without editing. Capture:

• Goal and scope
• Target users/systems
• Execution phases
• Dependencies
• Validation strategy
• Declared risks

Do not edit during this pass.

3. Run Multi-Lens Review

Apply the review lenses in references/review-lenses.md.

At minimum, evaluate:

• Logical consistency (no contradictory steps)
• Feasibility and ordering (dependencies satisfied before use)
• Verifiability (tests and success checks are concrete)
• Scope discipline (no speculative or off-goal work)
• Operational safety (rollbacks, migration safety, observability where needed)

Record issues with severity (blocker, high, medium, low) and evidence.

4. Patch In Place with Minimal Diffs

Revise the document directly with targeted edits:

• Fix blockers/high issues first.
• Keep changes minimal and local.
• Preserve user intent and existing structure where possible.
• Avoid full rewrites.

If a major conceptual rewrite is required, pause and ask the user before proceeding.

5. Validation Pass

Re-read the edited plan end-to-end and verify:

• No contradictions introduced by edits
• Action sequence is executable
• Acceptance criteria are testable
• Risks and assumptions are explicitly stated

6. Commit the Plan Changes (Docs-Only)

If this directory is a git repo, commit the Plan edits as a docs-only commit so reviewers can diff/rollback the plan independently of code changes.

• Confirm changes are limited to the plan file: git status --porcelain and git diff -- <plan-path>
• Stage only the plan file: git add <plan-path>
• Commit with a descriptive subject and per-change bullets in the body:

git commit \
  -m "docs: <primary theme> in <slug> plan" \
  -m $'Changes:\n- <edit 1>\n- <edit 2>\n- <edit 3>'

Example:

git commit \
  -m "docs: tighten acceptance checks in search-api plan" \
  -m $'Changes:\n- Make validation commands explicit per milestone\n- Reorder steps to satisfy dependencies\n- Add rollback notes for migration step'

• Do not push unless the user explicitly asks.

7. Return Review Summary

Format results using assets/fresh-eyes-report-template.md.

Include:

• Path reviewed
• Findings by severity
• What was changed (with file line references)
• Residual risks or open questions
• Recommendation: proceed vs rework

Guardrails

• Prefer precision over volume.
• Remove ambiguity, not intent.
• Do not add speculative requirements.
• Do not mark a plan "ready" without verifiable acceptance criteria.