Designs stable, well-documented APIs and module interfaces. Use when creating REST/GraphQL endpoints, defining contracts between modules, or changing public interfaces. The wire-format SSOT — response envelope, HTTP status codes, validation taxonomy, payload naming — lives in `.agents/rules/api-conventions.md`; this skill shows authors how to apply it.

2026-07-210

browser-testing-with-devtools

dsj1984/mandrel-bench

Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP.

2026-07-210

code-review-and-quality

dsj1984/mandrel-bench

Conducts multi-axis code review and runs the disciplined post-green refactor pass. Use before merging any change, when reviewing code written by yourself, another agent, or a human, or when the opt-in `delivery.refactorStage` checkpoint asks for a behaviour-preserving CRAP/duplication pass after the suite is green.

2026-07-210

debugging-and-error-recovery

dsj1984/mandrel-bench

Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.

2026-07-210

documentation-and-adrs

dsj1984/mandrel-bench

Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

2026-07-210

git-workflow-and-versioning

dsj1984/mandrel-bench

Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams.

2026-07-210

name	idea-refinement
description	Refines ideas iteratively. Refine ideas through structured divergent and convergent thinking. Use "idea-refine" or "ideate" to trigger.

Idea Refine

Policy Capsule

Drive the three-phase loop in order: Understand & Expand → Evaluate & Converge (grill) → Sharpen & Ship. Never jump straight to Phase 3 output.
Phase 1 MUST restate the idea as a "How Might We" statement, ask 3–5 sharpening questions via AskUserQuestion, and generate 5–8 variations (never 20+ shallow ones) — each carrying a reason it exists, told as a short story, not a bare bullet. Do not proceed until target user and success criteria are explicit.
Phase 2 grill loop poses one question at a time, each with a recommended answer + one-line rationale grounded in user input / codebase / first principles; never batch questions and never omit the recommendation.
Re-enumerate open branches after every grill answer; stop only when no unresolved decisions remain. Take the off-ramp directly to Phase 3 when the idea is already crisply scoped. A branch consciously deferred rather than resolved records its deferral reason.
Phase 3 emits a markdown one-pager with the canonical five planning headings exactly: ## Context, ## Goal, ## Non-Goals, ## Scope, ## Acceptance Criteria (plus optional ## Open Questions). No alternate heading text — the /plan clarity gate depends on this verbatim.
Surface every key assumption inside ## Context (or ## Scope); assumptions do not get their own heading. Unresolved decisions MUST NOT carry into the one-pager.
The ## Non-Goals list is mandatory and each entry includes a reason — focus is created by explicit exclusion.
Be honest, not supportive: push back on weak ideas with kindness; never function as a yes-machine.
Save the one-pager to docs/ideas/[idea-name].md only after the user explicitly confirms the direction; never write to disk silently.
When invoked inside a codebase, ground variations in real files/patterns via Glob / Grep / Read; do not invent architecture that ignores existing constraints.

Activation

Called from /plan during ideation when the operator supplies --seed "<text>" (or runs ideation with no seed and the host collects one interactively). The skill sharpens freeform intent into the canonical planning sections that /plan then folds into a Story. There is no separate Epic Clarity Gate path in v2 — N=1 Story authoring with a folded ## Spec is the lean default.

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.

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.

Restate the idea as a crisp "How Might We" problem statement. This forces clarity on what's actually being solved.
Ask 3-5 sharpening questions — no more — via the AskUserQuestion tool. Focus on: who this is for specifically, what success looks like, the real constraints (time, tech, resources), what's been tried, and why now. Do NOT proceed until you understand who this is for and what success looks like.
Generate 5-8 idea variations using lenses that fit the idea — inversion, constraint removal, audience shift, combination, simplification, 10x version, expert lens. Push beyond what the user initially asked for; each variation should have a reason it exists, not just be a bullet point. Don't run every lens mechanically.

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, and reference specific files when relevant.

Phase 2: Evaluate & Converge (Grill)

After the user reacts to Phase 1, shift to convergent mode. The job here is not just to list open questions — it is to resolve them, one at a time, before anything lands in the Phase 3 one-pager.

Off-ramp. Before starting the grill loop, restate the chosen direction in one sentence and check whether any decision branches remain unresolved. If the idea is already crisply scoped — target user clear, MVP boundary obvious, no architectural forks, no hidden assumptions — skip directly to Phase 3. Don't grill trivial ideas for the sake of process.

Cluster the ideas that resonated into 2-3 distinct directions. Get the user's pick (or a tentative lean) before enumerating branches — the grill loop runs against the chosen direction, not the full set.
Enumerate open branches. List every unresolved decision the chosen direction depends on: user-value branches (who benefits, painkiller vs. vitamin), feasibility branches (cost, hardest part, build vs. buy, sequencing), differentiation branches (why switch), and hidden assumptions (what you're betting is true, what could kill this, what you're ignoring and why that's okay for now). Read refinement-criteria.md in this skill directory for the full evaluation rubric. If the list is empty after enumeration, take the off-ramp.
Interrogate sequentially. For each branch, in priority order (highest-leverage / most blocking first):
- Pose one question at a time. Never batch.
- State your recommended answer with a one-line rationale grounded in what the user has told you, the codebase if you're inside one, or first-principles reasoning. The recommendation is a forcing function — accepting it should be the easy path; the user pushes back only when they actually disagree.
- Use AskUserQuestion so the recommendation surfaces as the first option.
- Wait for the response (accept, modify, or reject) before moving on. Record the resolution inline so it's available when you author Phase 3.
Re-enumerate after each answer. A resolved branch may collapse other branches (a "build" decision moots the "buy" follow-ups) or expand the tree (a new constraint surfaces fresh forks). Re-derive the list after each answer and pick the next highest-leverage branch.
Stop condition. Phase 2 ends when no branches remain unresolved. Resolutions feed the Phase 3 one-pager: confirmed bets land in Context with their validation strategy inline; rejected branches become Non-Goals entries with the reason; chosen scope becomes the Scope section; verifiable outcomes become Acceptance Criteria. A branch consciously deferred rather than resolved records the deferral reason.

Be honest, not supportive. If an idea is weak, say so with kindness. Push back on complexity, question real value, and point out when the emperor has no clothes — inside the grill loop, not after the one-pager is written.

The Phase 2 interrogation discipline is inspired by Matt Pocock's grill-me skill (one question at a time, recommended answer per question, walk the decision tree to resolution).

Phase 3: Sharpen & Ship

Produce a markdown one-pager that moves work forward. The five canonical headings below match .agents/templates/epic-from-idea.md and the /plan clarity gate; emit them verbatim so the renderer can substitute the body into a /plan Story seed without translation.

# [Idea Name]

## Context

[One-sentence "How Might We" framing followed by the current-state pain or
motivation in 1-2 short paragraphs. Surface the key assumptions you are betting
on inline — assumptions live here, not in a separate heading.]

## Goal

[The chosen direction and the outcome it produces — 2-3 paragraphs max. Frame in
terms of the end-state the user reaches, not the implementation path.]

## Non-Goals

- [Thing 1] — [reason]
- [Thing 2] — [reason]

## Scope

[The minimum version that tests the core assumption. What's in, what's out, and
how it sequences into stories.]

## Acceptance Criteria

- [ ] [Verifiable outcome 1 — phrased so a reviewer can check it]
- [ ] [Verifiable outcome 2]

## Open Questions

- [Question that needs answering before building]

The "Non-Goals" 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.

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.