| name | idea-refiner |
| description | Refine an early idea or creative concept into a coherent, evidence-aware design and durable Markdown master spec/PRD. Use when the user wants to explore, challenge, clarify, or develop an idea before implementation, including related-work research, core-mechanism design, product design, maturity progression, or handoff across Agent sessions. |
Idea Refiner
Turn an early idea into one evidence-bounded product design and durable Markdown PRD while preserving the user's product identity.
Global contract
- Use the writable workspace by default; reuse equivalent existing paths. If durable writes are unavailable or forbidden, explain the recovery limitation, suggest writable access, and never claim temporary/chat state is durable.
- Before asking the user for a fact or recording it as unknown, inspect available, directly relevant files, evidence, code, or public sources; do not ask the user to guess what the Agent can determine. Separate facts, inference, assumptions, unknowns, and user preferences.
- Ask one independent high-impact decision at a time, with a recommendation and main tradeoff; persist accepted answers immediately.
- For each tension, derive the smallest complete set of materially distinct live directions from the current evidence and frontier. Treat the previous turn's option count, lettering, and confirmation format as non-binding rather than as a template; reuse the same form only when the current tension independently warrants it, and never add weak alternatives merely to reach a preferred count.
- Keep one current authority per step.
- Treat
show, report, ask, and user-visible as outgoing-chat obligations; treat persist, record, maintain, and write as artifact obligations. A durable file does not substitute for required chat-visible UX.
- Existing code is evidence only: this Skill does not edit implementation code or tests. Route code changes downstream unless the user makes a separate explicit implementation/development request. “Continue refining” is not implementation intent.
Start or resume
- Inspect the workspace without recursively scanning archives.
- Follow an explicitly named authority entry; never infer authority from mtime or competing filenames.
- Load only the current step, required upstream closure/index sections, live risks/prerequisites, necessary terms, and directly relevant code/evidence.
- Resume the declared step; otherwise start at Step 0.
- Before durable writes or any resume/branch/history/high-impact revision, read references/artifact-lifecycle.md.
Do not load full history, inactive branches, raw validation, complete query logs, or stale exports unless a concrete conflict, restoration, impact audit, or user request requires them.
Progressive disclosure
Read only active references; keep every reference one hop from this file.
Workflow
Step 0 — Normalize the Idea Brief
Capture problem and/or creative proposition, user/situation, core objects/actions, value mechanism, likely form/differentiation, constraints, resource/maturity limits, and fact/assumption/unknown boundaries. Persist a compact baseline and revision record, normally in docs/idea/idea-brief.md. Do not research related work, validate, or design implementation.
Complete when: Steps 1–2 can proceed without inventing the proposition or comparison anchor. Unknowns and provisional assumptions may remain, but neither an unknown placeholder nor an Agent-authored assumption closes Step 0 when it silently selects among plausible interpretations that would materially change Step-1 risk routing or Step-2 related-work families or comparison level. Preserve a small affordable set of parallel anchors when possible; otherwise remain in Step 0 and ask one question that best separates the consequential interpretations.
Step 1 — Scan delivery risk
Under stated resources—or a marked provisional solo/small-team baseline with time, budget, data, credentials, special access, and long-term operations left unknown—record the top one or two delivery risks and every potential hard blocker inside the current Idea Brief or equivalent Step-0 authority. Distinguish blocked form, blocked maturity gate, and invalid core premise. Use only continue exploration or user decision required; require a user decision only for a confirmed blocker that destroys the core value premise when no reasonable form or scope adjustment preserves it. Otherwise continue. Do not expand into market, business-value, or architecture analysis.
Complete when: major risks, affected gates, evidence/assumptions, and routing consequences are explicit without overstating feasibility or blocking on unverified concerns.
Step 2 — Map related work
Read references/related-work.md. Discover and verify relevant products, projects, research, creative works, workflows, and mechanisms. Default to related-work framing, not market or competitor analysis.
Complete when: the current related-work map has adequate family coverage, evidence-sufficient classifications for important candidates, explicit coverage gaps, a Step-3 input package, and delayed Step-4 implementation-reference leads.
Step 3 — Define the Idea core
Read references/idea-definition.md. Build a dynamic agenda and grill one product-identity tension at a time. Step 3 alone decides what the product is; evidence gaps return to Step 2 and mechanism questions go to Step 4.
Complete when: one definition-sufficient identity remains, active branches are closed, unknowns have handoff contracts, the closure audit passes, and the user confirms the combined definition.
Step 4 — Converge the core-mechanism solution
Read references/core-solution.md. Deepen only implementation references relevant to the confirmed core; compare implementation units and their viable combinations; then grill the remaining solution tradeoffs.
Validation is optional. Recommend it only when results could change a decision and a diagnostic minimum carrier is possible. If recommending or executing it, read references/validation.md and record an explicit execution disposition before work. Honor it: execute-now-current-task continues through carrier creation, execution, write-back, and reporting unless new permission or a prerequisite blocks it.
Complete when: one current core-mechanism solution states the main solution, necessary fallbacks, implementation-unit composition, invariants, evidence status, assumptions, risks, and reopen conditions; the downstream-consumption audit passes; and the user confirms it for Step 5. Validation, zero unknowns, and a production architecture are not required.
Step 5 — Grow the product design
Read references/product-design.md. Maintain one agenda and one PRD through core-validation prototype → usable MVP → production product. Use behavior slices for coverage and one decision tension at a time for grilling. At each gate report achieved standard, live limits, and next-gate delta; never suggest exit. Continue until the user explicitly finalizes or production design completes.
Distinguish maturity design completion from maturity achievement. A gate's product design may be complete while its carrier is unbuilt or its evidence unavailable. When an accepted deferred validation reaches its recorded carrier trigger, restore its execution disposition before ordinary grilling continues; do not let internal freeze or protocol packages become hidden maturity gates.
Complete when: the requested boundary has coherent behavior and acceptance, decidable tensions are closed, risks/prerequisites are consumable, the closure audit passes, and the user confirms the whole design. Declare only the last completed gate.
Conditional engineering handoff
Closing, exporting, reviewing, presenting, or archiving a PRD is not engineering intent. At final Step-5 closure, give one brief non-directive capability notice that an engineering-planning handoff is available after explicit downstream intent; the notice does not constitute engineering intent or start the readiness audit. Do not ask a follow-up question, recommend implementation/readiness, or run the audit automatically. Only after a closed PRD receives explicit implementation, development, planning, issue/task breakdown, engineering-team handoff, or readiness intent, read references/engineering-handoff.md and run its audit.
Routing and reporting
- Step 2 supplies evidence; Step 3 owns identity; Step 4 owns the mechanism; Step 5 owns product behavior; architecture and implementation belong downstream.
- Product ambiguity returns to Step 5, mechanism mismatch to Step 4, and identity/core change to Step 3. Reopen only affected scope and preserve independent valid work.
- Steps 0–2 proceed automatically unless a material ambiguity requires the user. Steps 3–5 ask one decision at a time.
- When the user confirms a completed step, confirmation alone continues the workflow unless the user explicitly pauses, stops, or requests review. Close compactly and enter the next step in the same response; do not require a second “continue” message or stop at “ready to enter.”
- At transitions report only completion state, authoritative path, live risks/assumptions, and next step—not the full artifact.
