/refine-approach

name: refine-approach
user-invocable: true
description: Reviews and refines brainstorm or planning documents before implementation. Identifies gaps, clarifies assumptions, and ensures the approach is sound.
when_to_use: Use when user says "refine this", "review my approach", or "is this ready".
argument-hint: path to document to refine
compatibility: Designed for Claude Code (or similar products with agent support)

Refine Approach

Improve brainstorm and/or planning documents through structured review.

Step 1. Get the document that needs review

**Document path:** `$ARGUMENTS`

**If `$ARGUMENTS` is non-empty**, treat it as the document path and proceed to `Step 2. Assess`.

**If `$ARGUMENTS` is empty**, ask the user which document to review. Check `docs/brainstorm/` and `docs/plan/` for recent documents to suggest.

Step 2. Assess

Read the document, then ask and clarify:

• What is not clear?
• What is not necessary?
• What decision is being avoided?
• What assumptions are not stated or developed?
• What risks are not addressed?
• What part of the scope has been under-estimated?

Do not fix yet anything. Simply take notes about what you find to inform what you do in `Step 3. Evaluate and score`.

Step 3. Evaluate and score

Apply the following criteria to evaluate the document:

| Criteria | What to evaluate | |-----------|---------------| | **Clarity** | Problem statement is clear, no vague language ("probably," "consider," "try to") | | **Completeness** | Required sections present, constraints stated, open questions flagged | | **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) | | **YAGNI** | No hypothetical features, simplest approach chosen | | **Scope** | Scope is well defined and constrained, not overly ambitious |

If invoked during a brainstorm phase (after `/brainstorm`), validate that the document reflects with fidelity the user intent.

Step 4. Critical improvements

Among everything found in Steps 2-3, does one issue stand out? If something would significantly improve the document's quality, this is the **must address** item. Highlight it prominently.

Step 5. Update the document

Present your findings, then:

1. **Auto-fix** minor issues (vague language, formatting) without asking 2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning) 3. **Update** the document inline—no separate files, no metadata sections

Simplification Guidance

Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.

**Simplify when:**

• Content serves hypothetical future needs, not current ones
• Sections repeat information already covered elsewhere
• Detail exceeds what's needed to take the next step
• Abstractions or structure add overhead without clarity

**Don't simplify:**

• Constraints or edge cases that affect implementation
• Rationale that explains why alternatives were rejected
• Open questions that need resolution

Step 6: Next steps

After changes are complete, ask:

1. **Refine again** — another review pass 2. **Review complete** — document is ready

**When invoked directly by the user** (not as part of another skill), also determine the document type and offer clear context handoff as the first option:

**If the document is a brainstorm** (from `docs/brainstorm/`):

1. **Clear context and plan (Recommended)**: clear context for a fresh start, then plan 2. **Refine again** — another review pass 3. **Done for now** — document is ready

**If the document is a plan** (from `docs/plan/`):

1. **Clear context and build (Recommended)**: clear context for a fresh start, then build 2. **Refine again** — another review pass 3. **Done for now** — document is ready

**If the user selects "Clear context and plan"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path. Then stop.

**If the user selects "Clear context and build"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/build` with the actual plan file path. Then stop.

**When invoked by another skill** (e.g., from `/brainstorm` or `/plan`), only offer "Refine again" and "Review complete", then return control to the caller.

Iteration guidance

After 2 refinement passes, recommend completion—diminishing returns are likely. But if the user wants to continue, allow it.

What NOT to Do

• Do not rewrite the entire document
• Do not add new sections or requirements the user didn't discuss
• Do not over-engineer or add complexity
• Do not create separate review files or add metadata sections