idea-os

An operating system for turning a raw idea into a build-ready plan. Takes a rough problem statement and produces four files: clarifying questions, deep research, a PRD, and a phased execution plan with platform/stack picks, a user-journey diagram, and kill criteria.

What it produces

Four files in the current working directory (use pwd). Filenames are canonical.

1. questions.md — sharp clarifying questions (skip if the brief is already dense or run is autonomous)
2. research.md — market, competitors, SWOT, JTBD, distribution, risks, insights
3. PRD.md — problem, users, scope, non-goals, metrics, solution shape
4. plan.md — user journey + mermaid, platform + stack, phased build, kill criteria, next steps

Workflow — 5 phases, in order

Do not skip or reorder. Weak inputs produce weak outputs; each phase feeds the next.

Phase 1 — Triage

Classify the idea on two axes. Depth of research, PRD, plan, and question-count scale with tier; vocabulary scales with sophistication.

Idea tier (T1/T2/T3) — complexity:

• T1 (Simple) — single-user utility, weekend hobby, CLI, small app with no network effects
• T2 (Moderate) — multi-user app, SaaS MVP, AI wrapper with distinct users and workflows
• T3 (Complex) — marketplace, two-sided network, B2B SaaS with procurement, regulated or deep tech

Sophistication (S1/S2/S3) — builder vocabulary:

• S1 — first-time builder, non-technical. Explain every term, no frameworks by name
• S2 — hobbyist or junior PM. Introduce frameworks with one-line definitions
• S3 — founder, senior PM, shipped before. Use the full vocabulary

State your classification in one line (e.g. "T2 · S2 — moderate SaaS, builder has shipped before") before proceeding. If ambiguous, ask at most one question.

See references/clarifying-questions.md for the question bank tiered to these levels.

Phase 2 — Clarify

Write questions.md using assets/questions-template.md. Pick 4–18 questions (count scales with complexity) matched to the idea type — SaaS, marketplace, consumer, AI wrapper, dev tool, hardware, content. Group into three buckets: Who and Pain · Scope and Wedge · Constraints and Goals.

Every question must be actionable — the answer must change what you build. Generic questions ("who is your user?") are rejected; force specifics ("describe the last time your target user hit this pain — what did they do instead?").

After writing, stop and wait for answers. Do not research yet.

Skip questions.md entirely if the brief is already dense; state assumptions and proceed.

Phase 3 — Research

Write research.md using assets/research-template.md. Use WebSearch + WebFetch for real signal. Never hallucinate numbers; flag [assumption] or cut.

Pre-flight checklist (a floor):

• ≥5 WebSearches + 2 WebFetches on named competitors (pricing, positioning, traction)
• ≥1 search on market size / category growth with a sourced number
• ≥1 search on "why now" — tech, behavioral, regulatory, or cost unlock
• 1 community scan (Reddit, HN, Discord, FB group) where the target user congregates
• Note the date of every source

Sections required (depth scales with complexity):

1. Problem validation → references/research-frameworks.md
2. Jobs-to-be-done → references/research-frameworks.md#jtbd
3. Market (TAM/SAM/SOM, segmentation, WTP) → references/market-analysis.md
4. Competitors (direct, indirect, substitutes; positioning map; feature matrix) → references/competitor-analysis.md
5. SWOT → references/research-frameworks.md#swot
6. Distribution (first 100 users, channel CAC, founder actions) → references/distribution.md
7. Risks
8. Insights — 3–7 non-obvious findings that change the build. Most valuable section; no filler.

Phase 4 — PRD

Write PRD.md using assets/PRD-template.md. Anatomy + tier-scaled sections + anti-patterns in references/prd-structure.md. Non-goals section is mandatory — it's where bad PRDs die.

Phase 5 — Plan

Write plan.md using assets/plan-template.md. Must include:

1. User journey (text + mermaid) → references/user-journey.md
2. Platform recommendation with reasoning tied to research → references/platform-recommendation.md
3. Stack recommendation (conservative / modern / cutting-edge matrix) → references/stack-recommendation.md
4. Phase breakdown (MVP → v1 → target) with scope, success metrics, kill criteria, distribution per phase → references/mvp-slicing.md
5. Metrics per phase (North Star + inputs + counter) → references/metrics-framework.md
6. Immediate next steps (3–5 actions for the next 1–2 weeks)

Autonomous mode

When there's no live user (batch run, test, dry-run, or the user said "just proceed"): still write questions.md to make decisions legible, then simulate plausible answers consistent with a stated persona at the chosen tier. At the top of research.md, add an Assumptions in lieu of answers block listing each assumed answer and flagging the load-bearing ones. The reader should see exactly what you decided for them.

Output conventions

• Write to pwd unless user specifies
• Use the target-market currency consistently (USD, INR, EUR, etc.)
• Relative links between files ([PRD](PRD.md))
• Header block at top of each file: idea title, date (ISO), tier (T1/T2/T3) + sophistication (S1/S2/S3)
• Render on GitHub — mermaid, tables, clean headings

Top anti-patterns

• Generic SWOT ("good team" — cut)
• Unsourced TAM numbers — source it or flag [assumption]
• PRD with no non-goals — reject
• Plan with no kill criteria — not a plan
• MVP as a feature checklist — MVP is a thin vertical slice, one user one job end-to-end
• Platform recommendation before understanding user context — research first

More in references/prd-structure.md (PRD anti-patterns) and references/mvp-slicing.md (MVP traps).

Example

examples/example-notion-for-dog-trainers.md is a reference-only walkthrough showing the quality bar. Do not load it unless you need calibration — it's 500+ lines.