project-discovery

name	project-discovery
description	Runs the discovery front-end that precedes planning — brainstorm the idea, research the market landscape + technical approach, brainstorm and author the PRD, then author the docs the project needs. Use at the very start of a project (greenfield) or before a significant new initiative on an existing codebase (brownfield). Delegates to the researcher, product-owner, and architect subagents and writes the standardized docs/ tree.
tags	[]

Project Discovery

Overview

Discovery is everything that happens before /solo:plan — the messy front of the funnel where an idea becomes a grounded, written product definition. Skipping it is the #1 cause of building the wrong thing well. This skill runs it as four ordered steps and lands the results in the standardized docs/ tree.

It supports two entry modes:

• Greenfield — a brand-new project starting from an idea (or a product doc).
• Brownfield — a new initiative on an existing codebase: audit first, then the same four steps constrained by what already exists.

Discovery is autonomous by default: run the steps, make reversible calls, and only stop at real forks (see the operating manual, CLAUDE.md §7). Each step delegates to the specialist subagent and produces reviewable docs.

The four steps

1. Brainstorm idea   →  product-owner   →  docs/idea.md, docs/product/brief.md
2. Research          →  researcher      →  docs/research/*
3. Brainstorm PRD    →  product-owner   →  docs/product/prd.md (+ personas, stories)
4. Author docs       →  architect       →  docs/engineering/* (skeleton), gaps filled

1 — Brainstorm the idea

Delegate to product-owner. Expand the one-line seed into a shaped concept: problem, who has it, why now, core value, riskiest assumption. Diverge (options), then converge (a recommendation + reason). Write docs/idea.md and docs/product/brief.md. Gate: confirm the framing with the human before spending research effort — this is the cheapest place to correct course.

2 — Research the landscape

Delegate to researcher. Two tracks, run together:

• Market landscape — competitors, positioning, gaps, table stakes.
• Technical approach — viable architectures/stacks, trade-offs, lock-in. Adversarially verify load-bearing claims; cite sources. Write docs/research/*.

3 — Brainstorm & author the PRD

Delegate to product-owner. From the brief + research, brainstorm scope options, converge, and author docs/product/prd.md: problem, goals & non-goals, users, key journeys, functional requirements, success metrics, explicit out-of-scope. Add personas.md and user-stories.md (Given/When/Then). Gate: PRD approval.

4 — Author the needed docs

Delegate to architect. Stand up the docs/engineering/ skeleton (architecture.md, tech-stack.md, interfaces/, decisions/) enough to hand off to /solo:plan, and fill any doc gap the project needs. Don't over-produce — author what the next phase actually consumes.

Brownfield mode — audit first

Before step 1, delegate to architect + researcher to write docs/audit/:

• codebase-map.md — what exists and where (use solo-scout, ripgrep, the file tree).
• architecture-current.md — how it works today.
• constraints.md — what must not break; migration limits; existing patterns to match.

Then run steps 1–4 constrained by the audit: the idea is scoped to the existing system, research focuses on the delta, the PRD respects current behavior, and the architect changes only what the goal requires (Decision Ladder, honor existing style).

Anti-over-engineering guardrails

• Time-box divergence. Brainstorm a few real options, not twenty. Converge fast.
• Author what's consumed. A doc that no later phase reads is waste — cut it.
• One fact, one home. Respect the docs/ folder ownership; never duplicate.
• Discovery ends when planning can start. The exit test: could /solo:plan write a defensible brief, architecture, and module decomposition from these docs? If yes, stop researching and start building.

Handoff

Discovery feeds /solo:plan, which synthesizes .solo/spec/PROJECT_BRIEF.md, docs/engineering/architecture.md, and the module decomposition from these docs. Route with /solo:discover (umbrella), or run the steps individually via /solo:brainstorm, /solo:research, /solo:prd.