mandrel 1.57.0

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -0,0 +1,317 @@
+---
+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 (not 20+ shallow ones); 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.
+- Phase 3 emits a markdown one-pager with the canonical five Epic headings exactly: `## Context`, `## Goal`, `## Non-Goals`, `## Scope`, `## Acceptance Criteria` (plus optional `## Open Questions`). No alternate heading text — the `/epic-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; 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.
+
+Refines raw ideas into sharp, actionable concepts worth building through
+structured divergent and convergent thinking.
+
+## How It Works
+
+1.  **Understand & Expand (Divergent):** Restate the idea, ask sharpening
+    questions, and generate variations.
+2.  **Evaluate & Converge (Grill):** Cluster the resonant directions, then
+    walk each unresolved decision branch — one question at a time, with a
+    recommended answer — until no branches remain.
+3.  **Sharpen & Ship:** Produce a concrete markdown one-pager moving work
+    forward.
+
+## Activation
+
+Called from `/epic-plan` Phase 1 (ideation entry, when no `<epic#>` is
+supplied or `--idea "<seed>"` is passed) and Phase 6 (Epic Clarity Gate,
+when an existing Epic body fails the section-presence rubric). In Phase 6
+the skill is seeded from the **current Epic body** — not a blank seed —
+with the rubric gap list (`missingOrPlaceholder`) as the convergence
+target.
+
+## Usage
+
+This skill is primarily an interactive dialogue. Invoke it with an idea, and the
+agent will guide you through the process.
+
+```bash
+# Optional: Initialize the ideas directory
+bash /mnt/skills/user/idea-refine/scripts/idea-refine.sh
+```
+
+**Trigger Phrases:**
+
+- "Help me refine this idea"
+- "Ideate on [concept]"
+- "Stress-test my plan"
+- "Grill me on this"
+- "Walk me through the decision tree"
+
+## Output
+
+The final output is a markdown one-pager saved to `docs/ideas/[idea-name].md`
+(after user confirmation), containing the five canonical Epic sections:
+
+- Context (problem framing + current state)
+- Goal (desired outcome)
+- Non-Goals (explicit exclusions)
+- Scope (the in-scope MVP and how it tests the core assumption)
+- Acceptance Criteria (how we'll know it worked)
+
+Assumptions and open questions are recorded in the body of the relevant
+section (typically under Context or Scope) rather than carved into their
+own headings — the canonical five drive the `/epic-plan` clarity gate.
+
+## 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 (Grill)
+
+After the user reacts to Phase 1 (indicates which ideas resonate, pushes back,
+adds context), 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.
+
+1. **Cluster** the ideas that resonated into 2-3 distinct directions. Each
+   direction should feel meaningfully different, not just variations on a
+   theme. Get the user's pick (or a tentative lean) before enumerating
+   branches — the grill loop runs against the *chosen* direction, not the
+   full set.
+
+2. **Enumerate open branches.** List every unresolved decision the chosen
+   direction depends on. Use the stress-test rubric and the assumption
+   surfaces below as your source material:
+
+   - **User value branches.** Who benefits and how much? Painkiller or
+     vitamin? Which segment first?
+   - **Feasibility branches.** Technical/resource cost. Hardest part. Build
+     vs. buy. Sequencing.
+   - **Differentiation branches.** What makes this genuinely different?
+     Why would someone switch?
+   - **Hidden assumptions.** What you're betting is true (but haven't
+     validated). What could kill this. What you're choosing to ignore (and
+     why that's okay for now).
+
+   Read `refinement-criteria.md` in this skill directory for the full
+   evaluation rubric. Treat each unresolved item as a branch to grill on.
+   If the list is empty after enumeration, take the off-ramp.
+
+3. **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 already 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 the `AskUserQuestion` tool 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.
+
+4. **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). Don't pre-compute the full
+   question list — re-derive it after each answer and pick the next
+   highest-leverage branch.
+
+5. **Stop condition.** Phase 2 ends when no branches remain unresolved.
+   Resolutions feed directly into the Phase 3 one-pager: confirmed bets
+   land in the **Context** section with their validation strategy
+   inline; rejected branches become **Non-Goals** entries with the
+   reason; chosen scope becomes the **Scope** section; verifiable
+   outcomes from the resolved decisions become **Acceptance Criteria**.
+
+**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 — and do
+it inside the grill loop, not after the one-pager is already written.
+
+> The Phase 2 interrogation discipline is inspired by Matt Pocock's
+> [`grill-me`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md)
+> skill (one question at a time, recommended answer per question, walk the
+> decision tree to resolution).
+
+#### Phase 3: Sharpen & Ship
+
+Produce a concrete artifact — a markdown one-pager that moves work forward.
+The five canonical headings below match `.agents/templates/epic-from-idea.md`
+and the `/epic-plan` clarity gate; emit them verbatim so the renderer can
+substitute the body into a new Epic without translation.
+
+```markdown
+# [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]
+- [Thing 3] — [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]
+- [ ] [Verifiable outcome 3]
+
+## 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.
+
+### 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.
+
+## 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 "Non-Goals" list
+- Ignoring existing codebase constraints when ideating inside a project
+- Jumping straight to Phase 3 output without running Phases 1 and 2
+- Batching grill-loop questions (asking 3+ at once) instead of one at a time
+- Posing grill questions without a recommended answer — the recommendation
+  is the forcing function, not optional
+- Carrying unresolved branches into the Phase 3 one-pager (assumptions are
+  fine; *unresolved decisions* are not)
+
+## 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
+- [ ] Every open decision branch was either resolved in the grill loop or
+      consciously deferred (with the deferral reason recorded)
+- [ ] A "Non-Goals" 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