Start, a trial · installs only where you enable it

idea-refine

about 9,100 tokens

idea-refine as it installs, each line coloured by where its words came from.

  • 5 files
  • 4 edits
  • 87 sentences left out
  • 1 source
  • last changed 2026-10-19
  • trial

The text

SKILL.md

about 2,200 tokens
  • Addy Osmani's agent-skills
  • greenline

---

name: "idea-refine"

description: "Refines a raw idea the owner brings into a sharp, actionable concept through structured divergent and convergent thinking: sharpening questions, five to eight variations, two or three directions stress-tested, the hidden assumptions named and a not-doing list, in a one-pager in the reply. Use when an idea is still vague, before any change, or when the owner wants to expand options before converging on one; on \"ideate\" or \"refine this idea\"."

---

Addy Osmani's agent-skillsidea-refine/SKILL.md

# Idea Refine

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

greenlineOpens idea-refine: shape the owner's vague idea in conversation, editing nothing

idea-refine is a trial start for an idea the owner brings that is still vague, before any change. It runs as a conversation in the reply, edits no file, and needs no mode and no record. It differs from what-to-build, which proposes ideas from the repository's own evidence: here the idea is the owner's, in the request's own words. A direction the owner takes up becomes a change like any other: propose its mode and wait, as AGENTS.md says, open its record with a `## start` section carrying the one-pager's problem statement, direction, assumptions and not-doing list, and run the line from `frame`.

greenlinePoints at the skill's references page for paths and commands

Greenline's paths and commands for this skill stand on its references page, [references/greenline.md](references/greenline.md): read it when the work lands in the workspace.

Addy Osmani's agent-skillsidea-refine/SKILL.md

## 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.

Addy Osmani's agent-skillsidea-refine/SKILL.md

**Trigger Phrases:**

- "Help me refine this idea"

- "Ideate on [concept]"

greenlineThe one-pager is given in the reply, not saved as project state

The final output is a markdown one-pager given in the reply, containing:

Addy Osmani's agent-skillsidea-refine/SKILL.md

- Problem Statement

- Recommended Direction

- Key Assumptions

- MVP Scope

- Not Doing list

Addy Osmani's agent-skillsidea-refine/SKILL.md

## 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

Addy Osmani's agent-skillsidea-refine/SKILL.md

When the user brings an idea, in the request's own words, 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?

greenlineAsks the sharpening questions in the reply and waits for answers

Ask them in your reply, and wait for the answers. Do NOT proceed until you understand who this is for and what success looks like.

Addy Osmani's agent-skillsidea-refine/SKILL.md

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.

greenlineSearches and reads the repository, naming no single agent's tools

**If running inside a codebase:** Search and read the repository for relevant context: existing architecture, patterns, constraints, prior art. Ground your variations in what actually exists. Reference specific files and patterns when relevant.

Addy Osmani's agent-skillsidea-refine/SKILL.md

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?

greenlineReads the rubric only for the assumption audit and the MVP rules

Read `refinement-criteria.md` in this skill directory for the assumption audit and the MVP scoping rules.

Addy Osmani's agent-skillsidea-refine/SKILL.md

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:

```markdown

# [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.

greenlineThe one-pager stays in the reply until a change carries it

The one-pager stays in the reply: a list of ideas is not project state. When the owner takes the direction up, the change's record carries it in its start section, and the full page may sit in the change's working files while the change runs.

Addy Osmani's agent-skillsidea-refine/SKILL.md

### 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 "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

greenlineHands over the one-pager; frame follows a direction taken up

## Handoff

Consumes: the owner's idea, in the request's own words; the repository, when the idea sits inside one Produces: the one-pager in the reply: the problem statement, the recommended direction, the key assumptions, the MVP scope and the not-doing list; nothing durable until the owner's yes Next: frame, under the mode the owner approves, for a direction the owner takes up

SKILL.md as installed, byte for byte SHA-256 e9422a7df3152b38fb247cf811484d2540cf3a3a42c141ff45d07db71c242c51

refinement-criteria.md

about 460 tokens
  • Addy Osmani's agent-skills
  • greenline

greenlineThe page keeps the assumption audit and MVP rules, not the dimensionsAddy Osmani's agent-skillsidea-refine/refinement-criteria.md

Use this page during Phase 2 (Evaluate & Converge) to audit a direction's assumptions and scope its MVP. Not every criterion applies to every idea — use judgment about which dimensions matter most for the specific context.

Addy Osmani's agent-skillsidea-refine/refinement-criteria.md

## Assumption Audit

For every idea direction, explicitly list assumptions in three categories:

### Must Be True (Dealbreakers)

Assumptions that, if wrong, kill the idea entirely. These need validation before building.

Example: "Users will share their data with us" — if they won't, the entire product doesn't work.

### Should Be True (Important)

Assumptions that significantly impact success but don't kill the idea. You can adjust the approach if these are wrong.

Example: "Users prefer self-serve over talking to a person" — if wrong, you need a different go-to-market, but the core product can still work.

### Might Be True (Nice to Have)

Assumptions about secondary features or optimizations. Don't validate these until the core is proven.

Example: "Users will want to share their results with teammates" — a growth feature, not a core value proposition.

Addy Osmani's agent-skillsidea-refine/refinement-criteria.md

## MVP Scoping Principles

When defining MVP scope for the chosen direction:

1. **One job, done well.** The MVP should nail exactly one user job. Not three jobs done partially.

2. **The riskiest assumption first.** The MVP's primary purpose is to test the assumption most likely to be wrong.

3. **Time-box, not feature-list.** "What can we build and test in [timeframe]?" is better than "What features do we need?"

4. **The 'Not Doing' list is mandatory.** Explicitly name what you're cutting and why. This prevents scope creep and forces honest prioritization.

5. **If it's not embarrassing, you waited too long.** The first version should feel incomplete to the builder. If it doesn't, you over-built.

frameworks.md

about 1,300 tokens
  • Addy Osmani's agent-skills
Addy Osmani's agent-skillsidea-refine/frameworks.md

# Ideation Frameworks Reference

Use these frameworks selectively. Pick the lens that fits the idea — don't mechanically run every framework. The goal is to unlock thinking, not to follow a checklist.

## SCAMPER

A structured way to transform an existing idea by applying seven different operations:

- **Substitute:** What component, material, or process could you swap out? What if you replaced the core technology? The target audience? The business model?

- **Combine:** What if you merged this with another product, service, or idea? What two things that don't usually go together would create something new?

- **Adapt:** What else is like this? What ideas from other industries, domains, or time periods could you borrow? What parallel exists in nature?

- **Modify (Magnify/Minimize):** What if you made it 10x bigger? 10x smaller? What if you exaggerated one feature? What if you stripped it to the absolute minimum?

- **Put to other uses:** Who else could use this? What other problems could it solve? What happens if you use it in a completely different context?

- **Eliminate:** What happens if you remove a feature entirely? What's the version with zero configuration? What would it look like with half the steps?

- **Reverse/Rearrange:** What if you did the steps in the opposite order? What if the user did the work instead of the system (or vice versa)? What if you reversed the value chain?

**Best for:** Improving or reimagining existing products/features. Less useful for greenfield ideas.

## How Might We (HMW)

Reframe problems as opportunities using the "How Might We..." format:

- Start with an observation or pain point

- Reframe it as "How might we [desired outcome] for [specific user] without [key constraint]?"

- Generate multiple HMW framings of the same problem — different framings unlock different solutions

**Good HMW qualities:**

- Narrow enough to be actionable ("...help new users find relevant content in their first 5 minutes")

- Broad enough to allow creative solutions (not "...add a recommendation sidebar")

- Contains a tension or constraint that forces creativity

**Bad HMW qualities:**

- Too broad: "How might we make users happy?"

- Too narrow: "How might we add a button to the settings page?"

- Solution-embedded: "How might we build a chatbot for support?"

**Best for:** Reframing stuck thinking. When someone is anchored on a solution, pull them back to the problem.

## First Principles Thinking

Break the idea down to its fundamental truths, then rebuild from there:

1. **What do we know is true?** (not assumed, not conventional — actually true)

2. **What are we assuming?** List every assumption, even the ones that feel obvious

3. **Which assumptions can we challenge?** For each, ask: "Is this actually a law of physics, or just how it's been done?"

4. **Rebuild from the truths.** If you only had the fundamental truths, what would you build?

**Best for:** Breaking out of incremental thinking. When every idea feels like a small improvement on the status quo.

## Jobs to Be Done (JTBD)

Focus on what the user is trying to accomplish, not what they say they want:

- **Functional job:** What task are they trying to complete?

- **Emotional job:** How do they want to feel?

- **Social job:** How do they want to be perceived?

Format: "When I [situation], I want to [motivation], so I can [expected outcome]."

**Key insight:** People don't buy products — they hire them to do a job. The competing product isn't always in the same category. (Netflix competes with sleep, not just other streaming services.)

**Best for:** Understanding the real problem. When you're not sure if you're solving the right thing.

## Constraint-Based Ideation

Deliberately impose constraints to force creative solutions:

- **Time constraint:** "What if you only had 1 day to build this?"

- **Feature constraint:** "What if it could only have one feature?"

- **Tech constraint:** "What if you couldn't use [the obvious technology]?"

- **Cost constraint:** "What if it had to be free forever?"

- **Audience constraint:** "What if your user had never used a computer before?"

- **Scale constraint:** "What if it needed to work for 1 billion users? What about just 10?"

**Best for:** Cutting through complexity. When the idea is growing too large or too vague.

## Pre-mortem

Imagine the idea has already failed. Work backwards:

1. It's 12 months from now. The project shipped and flopped. What went wrong?

2. List every plausible reason for failure — technical, market, team, timing

3. For each failure mode: Is this preventable? Is this a signal the idea needs to change?

4. Which failure modes are you willing to accept? Which ones would kill the project?

**Best for:** Phase 2 evaluation. Stress-testing ideas that feel good but haven't been pressure-tested.

## Analogous Inspiration

Look at how other domains solved similar problems:

- What industry has already solved a version of this problem?

- What would this look like if [specific company/product] built it?

- What natural system works this way?

- What historical precedent exists?

The key is finding *structural* similarities, not surface-level ones. "Uber for X" is surface-level. "A two-sided marketplace that solves a trust problem between strangers" is structural.

**Best for:** Phase 1 expansion. Generating variations that feel genuinely different from the obvious approach.

examples.md

about 5,000 tokens
  • Addy Osmani's agent-skills
Addy Osmani's agent-skillsidea-refine/examples.md

# Ideation Session Examples

These examples demonstrate what good ideation sessions look like across different kinds of ideas. Study the rhythm, tone, and structure — not just the content. The skill should feel equally at home with a vague startup concept, a feature for an existing product, or a process improvement.

---

## Example 1: Vague Early-Stage Concept (Full 3-Phase Session)

**User asks:** `I want to help small local restaurants compete with the big delivery platforms`

### Phase 1: Understand & Expand

**Skill response:**

> **How might we** give independent restaurants the reach and convenience customers expect from delivery platforms, without forcing them into a model that erodes their margins and brand?

That's a big space. Let me sharpen it:

1. **Which part of "compete"?** Customer acquisition? Delivery logistics? Online ordering UX? Loyalty/retention? Margin pressure from platform fees?

2. **Who are you building for?** The restaurant owner? The diner? Both?

3. **What's the constraint?** Are you thinking software? A cooperative model? Something physical?

**User responds:** "Restaurant owners. The core pain is that they're paying 25-30% commission to delivery apps but feel they can't opt out because that's where the customers are. I'm thinking software but I'm open."

**Skill continues:**

So the problem isn't delivery logistics — it's **customer dependency**. The platforms own the customer relationship, and restaurants are renting access to their own customers at 30% of revenue. That's the leverage to break.

Here are 6 variations:

1. **Direct Channel Toolkit:** Give restaurants their own branded ordering — web, SMS, maybe a lightweight app — so they can move existing customers off-platform. The core bet: customers who *already know* a restaurant will order direct if it's easy enough. You don't need to compete with DoorDash for discovery, just for reordering.

2. **Inversion — Charge the Customer, Not the Restaurant:** What if the delivery fee model flipped? Customers pay a small premium for direct ordering, restaurants pay zero commission. Position it as "support your local spot." The bet: enough customers care about supporting local businesses to pay $1-2 more per order.

3. **Constraint Removal — What If Delivery Weren't Required?** The platforms bundle discovery + ordering + delivery, but most of their cost (and the restaurant's commission) is delivery. What if you only solved ordering and pickup? Pickup-first model. Restaurants keep 100% of revenue, customers save the delivery fee. Works best in dense neighborhoods.

4. **Combination — Restaurant Collective:** A co-op model where 20-50 local restaurants in an area share a platform, split costs, and cross-promote each other. Individual restaurants can't afford marketing — but a neighborhood collective can. Think "local food hall" but digital.

5. **Audience Shift — For Regular Customers:** Don't try to acquire new customers. Build exclusively for a restaurant's existing regulars — the people who come in weekly. A loyalty/reorder tool that's dead simple: "Your usual?" one-tap reorder. The 80/20 bet: 20% of customers drive 80% of revenue, and those people don't need DoorDash to discover the restaurant.

6. **Expert Lens — What Restaurant Owners Actually Do:** Most small restaurant owners aren't looking at dashboards. They're in the kitchen. Any tool that requires them to "manage" something will fail. The winning approach might be something that runs itself — auto-texts regulars when they haven't ordered in 2 weeks, auto-posts the daily special, auto-handles reorders. Zero restaurant-side effort.

Variation 5 and 6 together are interesting. Instead of trying to out-platform the platforms, you'd build something hyper-narrow: a reordering and retention tool for a restaurant's best existing customers. No discovery, no delivery, no marketplace. Just "keep your regulars ordering direct."

Which directions interest you?

---

### Phase 2: Evaluate & Converge

**User responds:** "I love the regulars angle (5 and 6). The direct channel toolkit (1) feels necessary but boring. The co-op idea (4) is interesting but complex. Let me focus on 1 + 5 + 6 combined."

**Skill response:**

Good instincts. That combination has a clear thesis: **own the relationship with your best customers, make reordering effortless, and require zero effort from the restaurant owner.** Let me stress-test it.

**Direction A: The "Regulars Engine" (Variations 5 + 6 fused)** A tool focused entirely on a restaurant's existing repeat customers. Auto-reorder, auto-engagement, zero management.

- **Core bet:** A restaurant's top 20% of customers will shift to direct ordering if the experience is frictionless and personal. The restaurant doesn't need *new* customers — it needs to stop paying 30% on customers it already has.

- **User value:** High and immediate. Every direct reorder saves the restaurant 25-30% commission. If a regular orders $30/week, that's ~$400/year in saved fees per customer. 50 regulars = $20K/year. That's real money for a small restaurant.

- **Feasibility:** Medium. The ordering/payment tech is commodity. The hard parts: (a) how do you identify and onboard "regulars" without the restaurant doing manual work? (b) How do you handle the cold start — the first reorder needs an order history that lives on the delivery platform, not with you.

- **Differentiation:** High for the niche. Platforms optimize for marketplace dynamics (new customer discovery, driver logistics). Nobody is optimizing specifically for "keep your regulars ordering direct." It's too small for DoorDash to care about, which is exactly why it's a good wedge.

- **Hidden assumptions:**

- Regulars will install/use yet another ordering method (assumption most likely to be wrong)

- Restaurant owners will share customer contact info or let you access it

- Direct ordering won't cannibalize dine-in revenue

- **What could kill it:** If customers simply won't switch channels. Habit is powerful — even if DoorDash costs more, it's already on their phone.

**Direction B: Direct Channel + Retention Hybrid (Variation 1 + 5)** Branded ordering for the restaurant *plus* the retention automation. More complete but more complex.

- **Core bet:** Restaurants need both the channel (a way to accept orders) and the engine (a way to keep customers coming back through that channel).

- **User value:** Higher ceiling, but only if both parts work together. The ordering channel alone is a commodity (Square, Toast already do this). The retention layer alone has no channel to retain customers *on*.

- **Feasibility:** Lower. You're building two products and hoping they're better together.

- **Differentiation:** Medium. The combination is interesting, but each piece individually has competitors.

- **Hidden assumption:** That bundling these is better than partnering (e.g., retention layer on top of Square Online).

- **What could kill it:** Scope. Building two things well is exponentially harder than building one thing well.

**The honest read:** Direction A is the sharper bet. Direction B is safer but less differentiated. The biggest risk for A is the channel-switching problem — getting customers to order through a new method. If you can crack that (and variation 6's "zero effort" approach might help — an SMS-based reorder doesn't require a new app), the rest follows.

One thing I want to push back on: you said variation 1 feels "necessary but boring." That instinct to include the "necessary" thing is how products lose focus. If the regulars engine works, you can add a branded ordering channel later. But if you build the channel first, you're just another Square Online competitor.

---

### Phase 3: Sharpen & Ship

**Skill produces:**

# ReOrder: Keep Your Regulars Ordering Direct

## Problem Statement

How might we help independent restaurants retain their best existing customers through direct ordering, eliminating the 25-30% platform commission on the revenue that matters most?

## Recommended Direction

Build a **regulars-only retention engine** — not a marketplace, not a full ordering platform. Hyper-focused on one job: make it effortless for a restaurant's repeat customers to reorder directly.

The key insight is that restaurants don't need help *finding* their best customers — they know who walks in every Tuesday. They need help moving those relationships off-platform. And the tool needs to run itself, because the owner is in the kitchen, not at a dashboard.

SMS-first (not app-first) is likely the right channel. A text saying "Hey, want your usual Thursday order from Marco's?" with a one-tap confirmation is lower friction than any app install.

## Key Assumptions to Validate

- [ ] Repeat customers will reorder via SMS/direct link instead of their usual delivery app — test with 5 restaurants, 20 regulars each, measure conversion over 4 weeks

- [ ] Restaurant owners can identify their top 20-30 regulars and share contact info — test by asking 10 restaurant owners if they'd do this

- [ ] The commission savings ($8-10 per order) is motivating enough for owners to invest initial setup effort — interview 10 owners about platform fee pain

## MVP Scope

- SMS-based reordering for a restaurant's self-identified regular customers

- Restaurant owner adds regulars manually (name + phone + usual order) — 15-minute setup

- Customer receives a text with their usual order, confirms with a reply, pays via link

- Restaurant receives the order via text/simple dashboard

- No delivery — pickup only in v1

- No discovery, no marketplace, no app

## Not Doing (and Why)

- **Delivery logistics** — delivery is the expensive, complex part and not the core problem. Pickup-first validates demand without operational burden.

- **Customer acquisition/discovery** — that's the platform's game. Competing on discovery means competing with DoorDash's budget. We compete on retention instead.

- **Branded restaurant apps/websites** — commodity. Square and Toast already do this. Another branded channel doesn't solve the behavioral problem.

- **Menu management, POS integration** — scope creep. "Your usual" doesn't need a dynamic menu. Start with static orders.

- **Analytics dashboards** — the owner is in the kitchen. Build reporting that's passive (weekly text summary) not active (log in and look at charts).

## Open Questions

- What's the legal/compliance landscape for SMS marketing to restaurant customers?

- How do you handle menu/price changes for "usual" orders?

- Is there a way to bootstrap the regular customer list from existing POS data instead of manual entry?

- What's the pricing model? Per-order fee? Monthly subscription?

---

## Example 2: Feature Idea Within an Existing Product (Codebase-Aware)

**User asks:** `adding real-time collaboration to our document editor`

### Phase 1: Understand & Expand

**Skill response:**

> **How might we** let multiple people work on the same document simultaneously in a way that feels natural, not chaotic?

I scanned your codebase and see you're using a block-based editor architecture with a REST API for persistence. No WebSocket infrastructure currently. That's important context. A few questions:

1. **What's the collaboration pattern?** Are people editing the same paragraph at the same time (Google Docs style)? Or working in different sections (Notion style)? Or reviewing/commenting while one person edits?

2. **How many simultaneous users?** 2-3 (pair editing)? 10+ (team workspace)?

3. **What's driving this now?** Customer requests? Competitive pressure? Internal need?

**User responds:** "2-5 people, usually working in different sections. Customers keep asking. We're losing deals to Notion because they assume any modern editor has this."

**Skill continues:**

The competitive pressure framing matters — this might be a checkbox feature (must-have to stay in the consideration set) rather than a differentiator. That changes how much you should invest.

I see your document model uses independent blocks with a flat ordering system (`src/models/document.ts:45`). That's actually favorable — block-level granularity means conflicts are rarer than character-level editing.

Here are 5 variations:

1. **Block-Level Locking (Simplest Path):** When someone starts editing a block, it's locked for others. They see a presence indicator ("Alex is editing...") but can edit any other block freely. No conflict resolution needed. Your existing block model supports this with minimal changes — add a `locked_by` field and a WebSocket layer for presence.

2. **Inversion — Async-First Collaboration:** Instead of real-time co-editing, lean into async. Inline suggestions, comments, and proposed edits that the document owner merges. Like suggestion mode, but as the *primary* collaboration model. Bet: for 2-5 people in different sections, async might actually be *better* than real-time.

3. **Simplification — Presence Without Co-Editing:** Show who's viewing the document and what section they're looking at (cursors, avatars in margins), but don't enable simultaneous editing. People coordinate verbally. Sounds primitive, but might be 80% of the value at 10% of the engineering cost.

4. **Combination — Collaboration + Version Branches:** Let people create "branches" of a document, edit independently, then merge. Each person gets their own space, no conflicts during editing, and you build a merge UI. Plays to your existing versioning system.

5. **10x Version — AI-Mediated Collaboration:** Multiple people describe what they want in a section, and AI synthesizes their inputs into a draft they all iterate on. Nobody directly edits the same text — they all influence it. Radical, possibly too early, but worth naming.

Given your architecture and the competitive context, I'd push you toward variation 1 or 3. You need to close deals, which means you need this shipped, which means you need the simplest version that checks the box. Variation 1 gives you real co-editing. Variation 3 is even cheaper but might not satisfy the "we need real-time" checkbox.

---

*Phase 2 would cluster into "minimum viable co-editing (1 or 3)" vs. "differentiated collaboration model (2 or 4)" — evaluating whether to check the competitive box quickly or invest in something that becomes a selling point.*

*Phase 3 would produce a one-pager recommending block-level locking as the MVP, with a "Not Doing" list that includes character-level CRDT (too complex), offline sync (not needed for 2-5 users), and AI features (premature).*

---

## Example 3: Process/Workflow Idea (Non-Product)

**User asks:** `a better way to run our weekly team retrospectives — they've gotten stale and people dread them`

### Phase 1: Understand & Expand

**Skill response:**

> **How might we** make retrospectives genuinely useful — something the team looks forward to — instead of a recurring meeting people endure?

Before expanding:

1. **What's stale about them?** Same format every time? Same people talking? Action items that never get done? Topics feel repetitive?

2. **Team size and dynamic?** 5 people who all speak up, or 15 where 3 dominate?

3. **What does a *good* retro look like to you?** Have you had one that worked? What made it different?

**User responds:** "8 people, maybe 3-4 actually talk. Same 'what went well / what didn't / action items' format for a year. The action items pile up and nothing changes. People think it's theater."

**Skill continues:**

The action item problem is the real signal. If nothing changes after the retro, people rationally disengage. The meeting isn't stale — it's **broken at the output layer**. The format might be fine if the follow-through worked.

Here are 6 variations:

1. **Fix the Output, Not the Meeting:** Keep the retro format but completely change what happens after. One action item max per retro. Assigned an owner and a deadline during the meeting. Next retro starts with a 5-minute demo of the completed action. If it's not done, that *becomes* the retro topic. The constraint of one item forces prioritization.

2. **Inversion — Kill the Meeting:** Replace the synchronous retro with an async one. Everyone submits reflections in writing during the week. A rotating facilitator synthesizes themes and proposes one change. The "meeting" is a 15-minute standup to agree or disagree. Bet: writing produces more honest feedback than speaking in a group.

3. **Audience Shift — Retro for the Quiet Ones:** Design the format for the 4-5 people who don't talk. Anonymous submission of topics. Dot-voting to prioritize. Small-group breakouts (pairs) before full-group discussion. The loud voices still participate, but the structure prevents them from dominating.

4. **Simplification — The One Question Retro:** Each retro has exactly one question, and it changes every week. "What's one thing that slowed you down?" "What did you learn that the team should know?" "If you could change one thing about how we work, what?" The constraint forces depth over breadth.

5. **Combination — Retro + Experimentation:** Treat each retro output as a hypothesis. "We believe that [change] will improve [outcome]." Run it as a 2-week experiment. Next retro: did it work? Keep, modify, or kill. Turns the retro into a continuous improvement engine with built-in accountability.

6. **Expert Lens — What Facilitators Know:** Experienced facilitators say the #1 retro killer is lack of safety, not format. People won't say what's really wrong if they fear consequences. The fix might not be structural — it might be starting with an anonymous "team health check" score (1-5) each week. When safety is high, retros naturally improve.

The interesting tension: variations 1 and 5 fix the *output* problem (nothing changes). Variations 2, 3, and 4 fix the *input* problem (same voices, same topics). Variation 6 says both are symptoms of a deeper issue. Where do you think the real bottleneck is?

---

*Phase 2 would evaluate in terms of: effort to try (most are free — just change how you run the next meeting), risk (variation 2 is the biggest departure), and whether the team's real problem is output (action items die) or input (not enough honesty).*

*Phase 3 would produce a one-pager recommending starting with variation 1 (one action item, demo next week) as a zero-cost experiment, combined with variation 3's anonymous submission. "Not Doing" list: new tools, elaborate facilitation techniques, or anything requiring budget. The first fix should take 0 minutes of prep and $0.*

---

## What to Notice in These Examples

1. **The restatement changes the frame.** "Help restaurants compete" becomes "retain existing customers." "Add real-time collaboration" becomes "let people work simultaneously without chaos." "Fix stale retros" becomes "fix the output layer."

2. **Questions diagnose before prescribing.** Each question determines which *type* of problem this actually is. The retro example reveals the problem is action item follow-through, not meeting format — and that changes every variation.

3. **Variations have reasons.** Each one explains *why* it exists (what lens generated it), not just *what* it is. The label (Inversion, Simplification, etc.) teaches the user to think this way themselves.

4. **The skill has opinions.** "I'd push you toward 1 or 3." "Variation 6 is worth sitting with." It tells you what it thinks matters and why — not just neutral options.

5. **Phase 2 is honest.** Ideas get called out for low differentiation or high complexity. The skill pushes back: "That instinct to include the 'necessary' thing is how products lose focus."

6. **The output is actionable.** The one-pager ends with things you can *do* (validate assumptions, build the MVP, try the experiment), not things to *think about*.

7. **The "Not Doing" list does real work.** It's specific and reasoned. Each item is something you might *want* to do but shouldn't yet.

8. **The skill adapts to context.** A codebase-aware example references actual architecture. A process idea generates zero-cost experiments instead of products. The framework stays the same but the output matches the domain.

The edits

Red is upstream's text; green is what greenline shipped in its place.

What the edit kinds mean
method
changes what the method does, under a recorded ruling
correction
fixes an error
scope
fits the text to this skill
pointer
re-points a reference
smaller edits
rename, relocate or adjust tool details
4 smaller edits

Renames, locations and tool details, each with its reason.

  1. Edit 1 tool details SKILL.md:52

    Upstream: When the user invokes this skill with an idea (`$ARGUMENTS`), guide them through three phases.

    Shipped: When the user brings an idea, in the request's own words, guide them through three phases.

    The idea arrives in the request's words, not an argument variable

    Full reason

    The idea is the request's own words, where upstream named one harness's argument variable (R21).

  2. Edit 2 tool details examples.md:9

    Upstream: **User invokes:** `/ideate I want to help small local restaurants compete with the big delivery platforms`

    Shipped: **User asks:** `I want to help small local restaurants compete with the big delivery platforms`

    The examples show the owner asking, not a slash command

    Full reason

    The example's request is the owner's words, where upstream showed one harness's slash command.

  3. Edit 3 tool details examples.md:132

    Upstream: **User invokes:** `/ideate adding real-time collaboration to our document editor`

    Shipped: **User asks:** `adding real-time collaboration to our document editor`

    The examples show the owner asking, not a slash command

    Full reason

    The example's request is the owner's words, where upstream showed one harness's slash command.

  4. Edit 4 tool details examples.md:178

    Upstream: **User invokes:** `/ideate a better way to run our weekly team retrospectives — they've gotten stale and people dread them`

    Shipped: **User asks:** `a better way to run our weekly team retrospectives — they've gotten stale and people dread them`

    The examples show the owner asking, not a slash command

    Full reason

    The example's request is the owner's words, where upstream showed one harness's slash command.

What greenline wrote

The full reason for every passage greenline wrote, in the order of the text.

  1. SKILL.md:10 method

    The opening in the start's own voice: when the block's situation sends an agent here, that the conversation edits no file, how it differs from what-to-build, and a direction taken up becoming a change under an approved mode, its record's start section carrying the one-pager. R1

  2. SKILL.md:12 pointer

    The front points at the skill's references page, where greenline's paths and commands for it stand since J-93 S2, so the front holds the method alone.

  3. SKILL.md:30 method

    The one-pager is given in the reply and, once a direction is taken up, carried by the change record's start section; a list of ideas is not project state (contradiction 33). R2

    Credits: Addy Osmani's agent-skills

  4. SKILL.md:67 method

    The sharpening questions are asked in the reply and their answers awaited, where upstream named one harness's question tool (R21). R3

    Credits: Addy Osmani's agent-skills

  5. SKILL.md:80 tool details

    Scanning the repository is searching and reading it, where upstream named one harness's tools (R21).

    Credits: Addy Osmani's agent-skills

  6. SKILL.md:95 method

    The rubric keeps its assumption audit and its minimum-product rules; its product-strategy taxonomy is dropped. R2

    Credits: Addy Osmani's agent-skills

  7. SKILL.md:138 method

    Where the one-pager lives: in the reply, then the change record and its working files once a direction is taken up, never a docs/ideas file (contradiction 33). Since J-93 S2 the front names greenline's homes and commands by their nouns, their paths and commands on the skill's references page. R4

  8. SKILL.md:178 pointer

    A start's handoff: the one-pager in the reply, and the step its hand reaches, frame under the approved mode for a direction taken up.

  9. refinement-criteria.md:3 method

    The page keeps the assumption audit and the minimum-product rules; the evaluation dimensions are dropped. R2

    Credits: Addy Osmani's agent-skills

  10. references/greenline.md:1 scope

    The skill's references page opens: greenline's mechanics for the skill, the paths and commands its front names by their nouns, held apart from the upstream prose since J-93 S2.

  11. references/greenline.md:5 relocate

    idea-refine's mechanics: the working files the full page may sit in, held apart since J-93 S2.

What it left out

Addy Osmani's agent-skills

Addy Osmani's agent-skills, idea-refine/SKILL.md: 8 of 137 sentences left out
  1. ```bash # Optional: Initialize the ideas directory bash skills/idea-refine/scripts/idea-refine.sh ``` left out: The script that creates a docs/ideas directory is dropped: the one-pager stays in the reply and the change record (contradiction 33, R21). R2
  2. 3 sentences taken
  3. "Stress-test my plan" left out: Stress-testing a plan is the anticipate step's direct ask, so this start's triggers keep the idea's two.
  4. 1 sentence taken
  5. The final output is a markdown one-pager saved to `docs/ideas/[idea-name].md` (after user confirmation), containing: left out: Saving the one-pager to docs/ideas gives way to the reply and the change record (contradiction 33). R2 replaced by line 30 of SKILL.md
  6. 32 sentences taken
  7. Use the `AskUserQuestion` tool to gather this input. left out: One harness's question tool gives way to questions asked in the reply. replaced by line 67 of SKILL.md
  8. 11 sentences taken
  9. **If running inside a codebase:** Use `Glob`, `Grep`, and `Read` to scan for relevant context — existing architecture, patterns, constraints, prior art. left out: One harness's search tools give way to searching and reading the repository. replaced by line 80 of SKILL.md
  10. 15 sentences taken
  11. Read `refinement-criteria.md` in this skill directory for the full evaluation rubric. left out: The full evaluation rubric gives way to the assumption audit and the MVP rules. R2 replaced by line 95 of SKILL.md
  12. 17 sentences taken
  13. Ask the user if they'd like to save this to `docs/ideas/[idea-name].md` (or a location of their choosing).
  14. Only save if they confirm. 2 sentences left out: Saving to docs/ideas gives way to the one-pager in the reply and the change record (contradiction 33). R2 replaced by line 138 of SKILL.md
Addy Osmani's agent-skills, idea-refine/refinement-criteria.md: 79 of 111 sentences left out
  1. Use this rubric during Phase 2 (Evaluate & Converge) to stress-test idea directions. left out: The rubric's use is the assumption audit and the MVP scope. R2 replaced by line 3 of refinement-criteria.md
  2. 1 sentence taken
  3. ## Core Evaluation Dimensions
  4. ### 1. User Value
  5. The most important dimension.
  6. If the value isn't clear, nothing else matters.
  7. **Painkiller vs. Vitamin:**
  8. **Painkiller:** Solves an acute, frequent problem.
  9. Users will actively seek this out.
  10. They'll switch from their current solution.
  11. Signs: people describe the problem with emotion, they've built workarounds, they'll pay for a solution.
  12. **Vitamin:** Nice to have.
  13. Makes something marginally better.
  14. Users won't go out of their way.
  15. Signs: people nod politely, say "that's cool," then don't change behavior.
  16. **Questions to ask:**
  17. Can you name 3 specific people who have this problem right now?
  18. What are they doing today instead?
  19. (The real competitor is always the current workaround.)
  20. Would they switch from their current approach?
  21. What would make them switch?
  22. How often do they encounter this problem?
  23. (Daily problems > monthly problems)
  24. Is this a "pull" problem (users are asking for this) or a "push" problem (you think they should want this)?
  25. **Red flags:**
  26. "Everyone could use this" — if you can't name a specific user, the value isn't clear
  27. "It's like X but better" — marginal improvements rarely drive adoption
  28. The problem is real but rare — high intensity but low frequency rarely justifies a product
  29. ### 2. Feasibility
  30. Can you actually build this?
  31. Not just technically, but practically.
  32. **Technical feasibility:**
  33. Does the core technology exist and work reliably?
  34. What's the hardest technical problem?
  35. Is it a known-hard problem or a novel one?
  36. Are there dependencies on third parties, APIs, or data sources you don't control?
  37. What's the minimum technical stack needed?
  38. (If the answer is "a lot," that's a signal.)
  39. **Resource feasibility:**
  40. What's the minimum team/effort to build an MVP?
  41. Does it require specialized expertise you don't have?
  42. Are there regulatory, legal, or compliance requirements?
  43. **Time-to-value:**
  44. How quickly can you get something in front of users?
  45. Is there a version that delivers value in days/weeks, not months?
  46. What's the critical path?
  47. What has to happen first?
  48. **Red flags:**
  49. "We just need to solve [very hard research problem] first"
  50. Multiple dependencies that all need to work simultaneously
  51. MVP still requires months of work — likely not minimal enough
  52. ### 3. Differentiation
  53. What makes this genuinely different?
  54. Not better — *different*.
  55. **Questions to ask:**
  56. If a user described this to a friend, what would they say?
  57. Is that description compelling?
  58. What's the one thing this does that nothing else does?
  59. (If you can't name one, that's a problem.)
  60. Is this differentiation durable?
  61. Can a competitor copy it in a week?
  62. Is the difference something users actually care about, or just something builders find interesting?
  63. **Types of differentiation (strongest to weakest):**
  64. **New capability:** Does something that was previously impossible
  65. **10x improvement:** So much better on a key dimension that it changes behavior
  66. **New audience:** Brings an existing capability to people who were excluded
  67. **New context:** Works in a situation where existing solutions fail
  68. **Better UX:** Same capability, dramatically simpler experience
  69. **Cheaper:** Same thing, lower cost (weakest — easily competed away)
  70. **Red flags:**
  71. Differentiation is entirely about technology, not user experience
  72. "We're faster/cheaper/prettier" without a structural reason why
  73. The feature that differentiates is not the feature users care most about 71 sentences left out: The product-strategy taxonomy, the evaluation dimensions, their red flags and the decision matrix, is dropped as ruled; the assumption audit and the MVP rules stay. R2
  74. 14 sentences taken
  75. ## Decision Framework
  76. When choosing between directions, rank on this matrix:
  77. | | High Feasibility | Low Feasibility |
  78. |--------------------|-------------------|-----------------|
  79. | **High Value** | Do this first | Worth the risk |
  80. | **Low Value** | Only if trivial | Don't do this |
  81. Then use differentiation as the tiebreaker between options in the same quadrant. 7 sentences left out: The product-strategy taxonomy, the evaluation dimensions, their red flags and the decision matrix, is dropped as ruled; the assumption audit and the MVP rules stay. R2

Addy Osmani's agent-skills, idea-refine/frameworks.md: all 104 sentences taken

Addy Osmani's agent-skills, idea-refine/examples.md: all 308 sentences taken

The ledger entry

greenline's ledger logs how each skill was made and changed, with a reason for each entry.

2026-10-19 2026-10-19-idea-refine-front-and-references

idea-refine's paths and commands move to a references page

The front names greenline's homes and commands by their nouns and points at a references page, which holds their paths and commands (J-93 S2).

Authorised by
2026-10-18 The operator's words of 2026-10-18 on the redesign (N-56, items 2 and 7), "we need the upstream prose upfront and references hold how to work meaning the artefacts etc" and, on the ingest procedures, "we wanna have there prose .. what we don't wanna have is there artefact system and fit them to use ours"; and J-93 S2's finalise words of 2026-10-19, "Fast route, merged slices, parallel jobs (Recommended)": a skill's front is the upstream prose its recipe cuts, and its mechanics, where its work lands, its section's form, its depths at each mode and its commands, stand on its references page
Pages it touched
SKILL.md, references/greenline.md
Rulings, R1 to R11
  1. The operator's rulings of 2026-10-04, "cool then lock everything in": a start that edits no file needs no mode and no record, and a direction taken up becomes a change under the mode the owner approves; R16 of 2026-10-07, a start chosen from the situation a request begins in
  2. The operator's rulings of 2026-10-08 on the intake R3 ("yes go ahead") and on the re-cut brief R22 ("yes amend, with one change"): idea-refine enters as a copy, a trial start named idea-refine; it keeps its assumption audit and its minimum-product rules and drops refinement-criteria's product-strategy taxonomy; and its one-pager stays in the reply and the change record, never a docs/ideas file, what-to-build's rule that a list of ideas is not project state winning (contradiction 33)
  3. The operator's ruling R21 of 2026-10-08 on harness-bound content ("harness specific skills have be re thought in to being usable on all harnesses") and the R3 ruling of that day, "yes go ahead", on the portable forms: idea-refine asks its questions in the reply, takes the idea from the request's own words, and its script is dropped
  4. The operator's rulings of 2026-10-08 on the intake R3 ("yes go ahead") and on the re-cut brief R22 ("yes amend, with one change"): idea-refine enters as a copy, a trial start named idea-refine; it keeps its assumption audit and its minimum-product rules and drops refinement-criteria's product-strategy taxonomy; and its one-pager stays in the reply and the change record, never a docs/ideas file, what-to-build's rule that a list of ideas is not project state winning (contradiction 33); The operator's words of 2026-10-18 on the redesign (N-56, items 2 and 7), "we need the upstream prose upfront and references hold how to work meaning the artefacts etc" and, on the ingest procedures, "we wanna have there prose .. what we don't wanna have is there artefact system and fit them to use ours": a skill's front is the upstream prose its recipe cuts, and greenline's mechanics, where the step's work lands, its section's form, its commands and its depths at each mode, stand on its references page (J-93 S2)
  5. The method items carry the operator's rulings of 2026-10-08 on the intake R3, "yes go ahead", the verdicts and the contradictions standing as recommended, the one-pager in the reply and the change record, never a docs/ideas file (contradiction 33)
  6. the operator's ruling R21 of 2026-10-08 on harness-bound and orchestration content ("harness specific skills have be re thought in to being usable on all harnesses") and the R3 ruling of that day, "yes go ahead", on the portable forms, the questions in the reply and the script dropped
  7. the operator's ruling R22 of 2026-10-08 on the re-cut brief, "yes amend, with one change": the roster table's names stand, router, diagnose and architecture-survey among them, with the trial names idea-refine, constraint-driven-development, correct and improve-instructions
  8. the operator's rulings of 2026-10-04, "cool then lock everything in": a start hands the job to a mode the owner approves, every change has one record with its working files and its folder, and a start that edits no file needs no mode and no record
  9. R16 of 2026-10-07, a start chosen from the situation a request begins in ("update the agents md created by greenline product to mention the kind with the skill table and also prose about when to use what kind skill")
  10. J-59, on the operator's words of 2026-10-09 ('okay then implement all of this'): a gist of at most twelve words on every account whose reason is stated; no text, measure or method changes
  11. The operator's words of 2026-10-18 on the redesign (N-56, items 2 and 7), "we need the upstream prose upfront and references hold how to work meaning the artefacts etc" and, on the ingest procedures, "we wanna have there prose .. what we don't wanna have is there artefact system and fit them to use ours"; and J-93 S2's finalise words of 2026-10-19, "Fast route, merged slices, parallel jobs (Recommended)": a skill's front is the upstream prose its recipe cuts, and its mechanics, where its work lands, its section's form, its depths at each mode and its commands, stand on its references page
2 earlier entries
  1. 2026-10-09 2026-10-09-idea-refine-gists

    Every account gets a short gist for the website

  2. 2026-10-08 2026-10-08-idea-refine-recipe

    Enters as a trial start that refines an idea in the reply

    Pages it touched: SKILL.md, examples.md, frameworks.md, refinement-criteria.md