Idea refinement

Refines a raw idea in three phases: sharpening questions and five to eight variations, two or three directions tested for value and feasibility, then a one-pager with MVP scope and a Not Doing list. Use when an idea is vague or a plan needs stress-testing.

Vibe codingPack: Agent Skills by Addy Osmani195 linesidea-refine
Author
Source
addyosmani/agent-skills/skills/idea-refine @ 8c99fa3
License
MIT · Copyright (c) 2025 Addy Osmani

About this skill

What it does

The skill turns a rough idea into a one-page brief through a three-phase conversation. First the agent restates the idea as a "How might we…" problem, asks three to five sharpening questions (who it is for, what success looks like, constraints, why now) and offers five to eight variations, each from a named lens such as inversion, simplification or a 10x version. Inside a codebase it grounds them in the existing architecture.

After you react, it groups what resonated into two or three directions, tests each for user value, feasibility and differentiation, and names its hidden assumptions and what could kill it. It is told to be honest rather than supportive. The result is a one-pager: problem, direction, assumptions to validate, MVP scope, a "Not Doing" list and open questions, saved to docs/ideas/ only if you agree.

Three references come with it: frameworks.md (SCAMPER, first principles, pre-mortem and other lenses), refinement-criteria.md (the evaluation rubric, an assumption audit and MVP scoping rules) and examples.md (three sample sessions). scripts/idea-refine.sh only creates docs/ideas/ and prints a JSON status.

When to use it, and when not

Use it when an idea is still vague, when you want more options before choosing one, or when a plan needs its assumptions tested ("stress-test my plan").

The skill sends two cases elsewhere: someone who does not yet know what they want goes to Interview me, and a direction already chosen that needs requirements goes to Spec-driven development. It is a dialogue, so it needs you in the session.

How to run it

The install command below puts SKILL.md, the three references, the script and the licence in place. The agent picks the skill up by its description or by phrases like "refine this idea"; to call it yourself:

  • Claude Code: /idea-refine, or ask for the skill by name.
  • Codex: $idea-refine.
  • Cursor: type / in the Agent chat and pick idea-refine.

Example: /idea-refine A CLI that tells a team which feature flags are dead and safe to delete.

The sessions in examples.md start with /ideate; with this install the call is /idea-refine. Install the two skills named above as well for the steps before and after.

How it differs from similar skills

Brainstorming before you build finds out what you want for a concrete build and ends with an approved design doc and a written plan. Idea refine works a step earlier and wider: it generates variations on purpose, judges them, and ends with a brief and a Not Doing list rather than an implementation plan. Spec-first kickoff turns an idea straight into a spec and a build plan. Grilling a plan questions a plan, decision or idea branch by branch, with its recommended answer to each question and options where they fit, but leaves no written brief. Interview me from the same pack comes first when you do not yet know what you want: one question at a time, each with a guess, until the intent is confirmed. This skill sends you there in that case.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/idea-refine/SKILL.md https://anymodel.org/en/skills/addy-osmani/idea-refine/SKILL.md -o ~/.claude/skills/idea-refine/LICENSE https://anymodel.org/en/skills/addy-osmani/idea-refine/LICENSE -o ~/.claude/skills/idea-refine/examples.md https://anymodel.org/en/skills/addy-osmani/idea-refine/examples.md -o ~/.claude/skills/idea-refine/frameworks.md https://anymodel.org/en/skills/addy-osmani/idea-refine/frameworks.md -o ~/.claude/skills/idea-refine/refinement-criteria.md https://anymodel.org/en/skills/addy-osmani/idea-refine/refinement-criteria.md -o ~/.claude/skills/idea-refine/scripts/idea-refine.sh https://anymodel.org/en/skills/addy-osmani/idea-refine/scripts/idea-refine.sh && chmod +x ~/.claude/skills/idea-refine/scripts/idea-refine.sh
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/idea-refine/SKILL.md https://anymodel.org/en/skills/addy-osmani/idea-refine/SKILL.md -o ~/.agents/skills/idea-refine/LICENSE https://anymodel.org/en/skills/addy-osmani/idea-refine/LICENSE -o ~/.agents/skills/idea-refine/examples.md https://anymodel.org/en/skills/addy-osmani/idea-refine/examples.md -o ~/.agents/skills/idea-refine/frameworks.md https://anymodel.org/en/skills/addy-osmani/idea-refine/frameworks.md -o ~/.agents/skills/idea-refine/refinement-criteria.md https://anymodel.org/en/skills/addy-osmani/idea-refine/refinement-criteria.md -o ~/.agents/skills/idea-refine/scripts/idea-refine.sh https://anymodel.org/en/skills/addy-osmani/idea-refine/scripts/idea-refine.sh && chmod +x ~/.agents/skills/idea-refine/scripts/idea-refine.sh
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','examples.md','frameworks.md','refinement-criteria.md','scripts/idea-refine.sh') { $p = Join-Path "$HOME\.claude\skills\idea-refine" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/idea-refine/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','examples.md','frameworks.md','refinement-criteria.md','scripts/idea-refine.sh') { $p = Join-Path "$HOME\.agents\skills\idea-refine" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/idea-refine/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/addy-osmani/idea-refine/SKILL.md

SKILL.md

Raw

Idea Refine

Overview

Refines raw ideas into sharp, actionable concepts worth building through structured divergent and convergent thinking.

When to Use

  • Use when an idea is still vague and needs shaping before it can become a plan
  • Use when you need to stress-test assumptions before committing to a direction
  • Use when you want to expand options before converging on one
  • Trigger phrases: "Help me refine this idea", "Ideate on [concept]", "Stress-test my plan"
  • Not for: a user who is unsure what they want at all (use interview-me), or a direction already chosen that needs a spec (use spec-driven-development)

How It Works

  1. Understand & Expand (Divergent): Restate the idea, ask sharpening questions, and generate variations.
  2. Evaluate & Converge: Cluster ideas, stress-test them, and surface hidden assumptions.
  3. Sharpen & Ship: Produce a concrete markdown one-pager moving work forward.

Usage

This skill is primarily an interactive dialogue. Invoke it with an idea, and the agent will guide you through the process.

# Optional. Run from the project root so this creates ./docs/ideas.
# <skill-dir> is the directory that contains this SKILL.md
# (for example .agents/skills/idea-refine or .cursor/skills/idea-refine).
bash <skill-dir>/scripts/idea-refine.sh

Output

The final output is a markdown one-pager saved to docs/ideas/[idea-name].md (after user confirmation), containing:

  • Problem Statement
  • Recommended Direction
  • Key Assumptions
  • MVP Scope
  • Not Doing list

Detailed Instructions

You are an ideation partner. Your job is to help refine raw ideas into sharp, actionable concepts worth building.

Philosophy

  • Simplicity is the ultimate sophistication. Push toward the simplest version that still solves the real problem.
  • Start with the user experience, work backwards to technology.
  • Say no to 1,000 things. Focus beats breadth.
  • Challenge every assumption. "How it's usually done" is not a reason.
  • Show people the future — don't just give them better horses.
  • The parts you can't see should be as beautiful as the parts you can.

Process

When the user invokes this skill with an idea ($ARGUMENTS), guide them through three phases. Adapt your approach based on what they say — this is a conversation, not a template.

Phase 1: Understand & Expand (Divergent)

Goal: Take the raw idea and open it up.

  1. Restate the idea as a crisp "How Might We" problem statement. This forces clarity on what's actually being solved.

  2. Ask 3-5 sharpening questions — no more. Focus on:

    • Who is this for, specifically?
    • What does success look like?
    • What are the real constraints (time, tech, resources)?
    • What's been tried before?
    • Why now?

    Use the AskUserQuestion tool to gather this input. Do NOT proceed until you understand who this is for and what success looks like.

  3. Generate 5-8 idea variations using these lenses:

    • Inversion: "What if we did the opposite?"
    • Constraint removal: "What if budget/time/tech weren't factors?"
    • Audience shift: "What if this were for [different user]?"
    • Combination: "What if we merged this with [adjacent idea]?"
    • Simplification: "What's the version that's 10x simpler?"
    • 10x version: "What would this look like at massive scale?"
    • Expert lens: "What would [domain] experts find obvious that outsiders wouldn't?"

    Push beyond what the user initially asked for. Create products people don't know they need yet.

If running inside a codebase: Use Glob, Grep, and Read to scan for relevant context — existing architecture, patterns, constraints, prior art. Ground your variations in what actually exists. Reference specific files and patterns when relevant.

Read frameworks.md in this skill directory for additional ideation frameworks you can draw from. Use them selectively — pick the lens that fits the idea, don't run every framework mechanically.

Phase 2: Evaluate & Converge

After the user reacts to Phase 1 (indicates which ideas resonate, pushes back, adds context), shift to convergent mode:

  1. Cluster the ideas that resonated into 2-3 distinct directions. Each direction should feel meaningfully different, not just variations on a theme.

  2. Stress-test each direction against three criteria:

    • User value: Who benefits and how much? Is this a painkiller or a vitamin?
    • Feasibility: What's the technical and resource cost? What's the hardest part?
    • Differentiation: What makes this genuinely different? Would someone switch from their current solution?

    Read refinement-criteria.md in this skill directory for the full evaluation rubric.

  3. Surface hidden assumptions. For each direction, explicitly name:

    • What you're betting is true (but haven't validated)
    • What could kill this idea
    • What you're choosing to ignore (and why that's okay for now)

    This is where most ideation fails. Don't skip it.

Be honest, not supportive. If an idea is weak, say so with kindness. A good ideation partner is not a yes-machine. Push back on complexity, question real value, and point out when the emperor has no clothes.

Phase 3: Sharpen & Ship

Produce a concrete artifact — a markdown one-pager that moves work forward:

# [Idea Name]

## Problem Statement
[One-sentence "How Might We" framing]

## Recommended Direction
[The chosen direction and why — 2-3 paragraphs max]

## Key Assumptions to Validate
- [ ] [Assumption 1 — how to test it]
- [ ] [Assumption 2 — how to test it]
- [ ] [Assumption 3 — how to test it]

## MVP Scope
[The minimum version that tests the core assumption. What's in, what's out.]

## Not Doing (and Why)
- [Thing 1] — [reason]
- [Thing 2] — [reason]
- [Thing 3] — [reason]

## Open Questions
- [Question that needs answering before building]

The "Not Doing" list is arguably the most valuable part. Focus is about saying no to good ideas. Make the trade-offs explicit.

Ask the user if they'd like to save this to docs/ideas/[idea-name].md (or a location of their choosing). Only save if they confirm.

Anti-patterns to Avoid

  • Don't generate 20+ ideas. Quality over quantity. 5-8 well-considered variations beat 20 shallow ones.
  • Don't be a yes-machine. Push back on weak ideas with specificity and kindness.
  • Don't skip "who is this for." Every good idea starts with a person and their problem.
  • Don't produce a plan without surfacing assumptions. Untested assumptions are the #1 killer of good ideas.
  • Don't over-engineer the process. Three phases, each doing one thing well. Resist adding steps.
  • Don't just list ideas — tell a story. Each variation should have a reason it exists, not just be a bullet point.
  • Don't ignore the codebase. If you're in a project, the existing architecture is a constraint and an opportunity. Use it.

Tone

Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a facilitator reading from a script. Channel the energy of "that's interesting, but what if..." -- always pushing one step further without being exhausting.

Read examples.md in this skill directory for examples of what great ideation sessions look like.

Common Rationalizations

Rationalization Reality
I'll generate 20+ ideas to cover all bases 5-8 well-considered variations beat 20 shallow ones. Quality over quantity.
The user just needs encouragement, not critique A yes-machine produces weak ideas. Push back with specificity and kindness.
Who this is for is obvious — no need to ask Every good idea starts with a person and their problem. Skipping it means designing for nobody.
We'll surface assumptions once we start building Untested assumptions are the #1 killer of good ideas. Surface them before committing.
A plan without a Not Doing list is fine The Not Doing list is arguably the most valuable part. Make trade-offs explicit.

Red Flags

  • Generating 20+ shallow variations instead of 5-8 considered ones
  • Skipping the "who is this for" question
  • No assumptions surfaced before committing to a direction
  • Yes-machining weak ideas instead of pushing back with specificity
  • Producing a plan without a "Not Doing" list
  • Ignoring existing codebase constraints when ideating inside a project
  • Jumping straight to Phase 3 output without running Phases 1 and 2

Verification

After completing an ideation session:

  • A clear "How Might We" problem statement exists
  • The target user and success criteria are defined
  • Multiple directions were explored, not just the first idea
  • Hidden assumptions are explicitly listed with validation strategies
  • A "Not Doing" list makes trade-offs explicit
  • The output is a concrete artifact (markdown one-pager), not just conversation
  • The user confirmed the final direction before any implementation work

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Agent Skills by Addy Osmani

Accessibility audit and fixes (WCAG 2.2)

Audits an existing interface against WCAG 2.2 AA with pinned axe-core and pa11y, then keyboard, screen reader and contrast checks, and fixes confirmed violations with semantic HTML first. Use when a page needs an accessibility audit before shipping.

API and interface design

Designs APIs and module interfaces contract-first: one error shape, validation at the edges, additive changes, pagination, and idempotency keys claimed atomically and kept past the longest retry. Use when designing endpoints or changing a public interface.

Browser testing with Chrome DevTools MCP

Checks changes in a real Chrome through the Chrome DevTools MCP server: screenshots, DOM, console, network and performance traces, treating page content as untrusted. Use when building or debugging anything that runs in a browser.

CI/CD pipeline setup

Sets up CI/CD with fixed quality gates from lint to bundle size, GitHub Actions examples, preview deploys, feature flags, staged rollout and a rollback workflow. Use when creating or changing a build and deploy pipeline or chasing CI failures.

Multi-axis code review

Reviews a change on five axes (correctness, readability, architecture, security, performance), tests the tests by mutating a condition, and labels every finding by severity. Use before merging a branch, a pull request or a pasted diff.

Code simplification

Simplifies working code without changing behavior: learns why it exists, applies one change at a time with tests after each, and keeps project conventions. Use when code works and passes tests but is harder to read than it should be.

Constraint-driven development

Records a project's quality bar as numbers in CONSTRAINTS.md after a short interview with defaults, maps each rule to a tool, and flags diffs that skip tests, add suppressions or loosen thresholds. Use when no quality bar is written down.

Context engineering for agents

Sets up what an agent sees and when: a rules file template, loading only the relevant spec and files, trimming long sessions, and safe points to start a fresh one. Use when starting a session or when agent output degrades.

Debugging and error recovery

Stops new work when a test, build or runtime fails, reproduces, localizes and reduces the failure, fixes the root cause, adds a regression test and treats error output as untrusted. Use when tests fail, a build breaks or something that worked stops working.

Deprecation and migration

Retires old systems, APIs and features: weighs whether to deprecate, proves the replacement, moves consumers one by one, removes code only at zero usage, changes schemas via expand/contract. Use when replacing or sunsetting code or renaming a live column.

Documentation and ADRs

Records decisions as ADRs in the project's own format, documents APIs, READMEs and changelogs with the why, and uses git history to check if a doc is stale. Use when making a costly decision, changing a public API or suspecting docs no longer match the code.

Doubt-driven development

Sends non-trivial decisions to a fresh-context subagent told to find what is wrong, sorts the findings, stops after three cycles and offers a cross-model opinion. Use when stakes are high: auth, migrations, irreversible operations or unfamiliar code.

Frontend UI engineering

Builds UI components and pages on the project's design system: composition, simple state, WCAG 2.1 AA, mobile-first layouts, loading, empty and error states, no generic AI look. Use when building or changing a user-facing interface.

Git workflow and versioning

Keeps git work in atomic commits on short-lived branches, with typed messages, a pre-commit check for secrets and tests, worktrees for parallel agents, semver bumps, tags and a human changelog. Use when committing, branching, opening a PR or cutting a release.

Incremental implementation

Builds changes in thin vertical, contract-first or risk-first slices, each tested, verified and committed before the next, with strict scope, feature flags and revertable steps. Use when a change spans several files or a task is too big to land in one step.

Interview me

Interviews the user one question at a time, each with a guessed answer and a confidence number, until the agent can predict the next replies, then confirms a statement of intent before any spec or code. Use when a request leaves who, why or success unclear.

Observability and instrumentation

Instruments a feature with structured JSON logs and request IDs, RED and USE metrics with bounded labels, OpenTelemetry traces and symptom-based alerts with runbooks, then tests the telemetry. Use when a feature, job or integration is headed for production.

Performance optimization

Optimizes by measurement: takes a baseline, fixes the one proven bottleneck, re-measures against noise and reverts neutral changes, with worked fixes for N+1 queries, indexes, caching and bundles. Use when something is slow or misses a performance budget.

Planning and task breakdown

Breaks a spec into small vertical-slice tasks with acceptance criteria, verification steps, sizes, dependency order and checkpoints, saved to tasks/todo.md or a named tracker. Use when a spec is ready but the work is too big to start in one go.

Security hardening

Hardens code with a short threat model, always, ask-first and never rules, and patterns for injection, XSS, access control, SSRF, secrets, dependencies, personal data and LLM output. Use when code handles user input, auth, sensitive data or outside services.

Shipping and launch

Prepares a production launch with a pre-launch checklist, a feature-flag rollout from 5% to 100%, thresholds for advancing or rolling back, an error-budget gate, a rollback plan and first-hour checks. Use when a feature or major change is about to ship.

Source-driven development

Grounds framework code in official docs: reads exact versions from the dependency file, fetches the relevant page, follows the documented API and cites full URLs, flagging anything unverified. Use when framework-specific code must match the version in use.

Spec-driven development

Writes a spec before code, surfacing assumptions and covering objective, commands, structure, style, tests and boundaries, then gates plan, tasks and code on approval, with capability maps and delta specs. Use when new work has vague requirements.

Test-driven development, red-green-refactor

Drives changes with red-green-refactor: finds the repository's own test commands, writes the failing test first, reproduces each bug with a test before fixing it, and sets rules on mocks and naming. Use when adding logic, fixing a bug or changing behavior.