product-discovery
Run a product initiative as a tracked journey — not a toolbox of one-shot answers. Persistent state across sessions: living PRD, evidence-ty
Open source Open in the app JSON README (API)
About
Run a product initiative as a tracked journey — not a toolbox of one-shot answers. Persistent state across sessions: living PRD, evidence-typed hypotheses (REAL/SYNTHETIC/INFERRED), decision log. From one-sentence problem to PRD, AB test analysis, and GTM rollout to existing users — 19 configurable steps. Key features: • One-sentence start — describe your problem, get hypotheses + research plan in 60 seconds • 19-step pipeline across 3 phases: Problem Research → Solution Design + Validation → Launch • Living PRD that builds incrementally as you progress • Evidence typing (REAL/SYNTHETIC/INFERRED with confidence 0.0-1.0) • Cross-session continuity — resume exactly where you stopped • Personal context that grows: pm-profile.md, .product-corrections.md, .initiatives-digest.md • Tracker integration: push tickets to Jira /Linear / GitHub Issues via MCP • 5 pipeline templates: Quick / Full / Problem-only / Solution-only / Custom For PMs working on a real initiative who want a structured path
Details
- Kind
- Plugins
- Topic
- Productivity
- Publisher
- lenar-amirov
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 13
- Last push
- 2026-08-20T12:01:20Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
lenar-amirov/product-pipeline-public/product-discovery
README
# Product Discovery
**Run a product initiative as a tracked journey — from one-sentence problem to PRD, with persistent state across sessions.**
Not a toolbox of one-shot AI answers. A structured pipeline where every session adds to the same initiative — drill-down questions, evidence-typed hypotheses, a PRD that builds incrementally, and a decision log you can come back to next week.
Built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Powered by Double Diamond, Teresa Torres' Continuous Discovery, and Marty Cagan's Product Discovery.
> **Requires** Claude Code desktop app or CLI (not the web version — needs persistent local state).
---
## Why this, and not a PM skill toolbox?
There are great PM skill collections — [pm-skills](https://github.com/phuryn/pm-skills) (60+ skills), [Anthropic's official PM plugin](https://github.com/anthropics/knowledge-work-plugins) (`/write-spec`, `/synthesize-research`, `/competitive-brief`) — that you call ad-hoc. They're excellent for one-shot answers, and stateless by design.
**Product Discovery is different.** It's not a toolbox — it's a journey:
| | PM toolbox (pm-skills, Anthropic PM plugin) | Product Discovery (this) |
|---|---|---|
| **Unit of work** | One question, one answer | Point-entry jobs that accumulate into one tracked initiative |
| **State** | Stateless — Claude forgets next time | Persistent: hypothesis registry, decision log, living PRD, coverage map |
| **PRD** | Generated when you ask | Living document, sections fill as evidence arrives |
| **Evidence** | Free-form text | Typed (REAL / SYNTHETIC / INFERRED, confidence 0.0–1.0) in a machine-readable registry, validated every session |
| **Continuity** | Each session is a fresh start | Resume exactly where you stopped, with full context |
| **Best for** | Quick answers on any PM task | Working a real product initiative through to launch |
**Use a PM toolbox** when you want quick help with one specific task.
**Use Product Discovery** when you've committed to a real initiative and want a tracked path from problem to launch.
(They complement each other — you can install both.)
---
## Get started in 30 seconds
### 1. Get the tool
```bash
git clone https://github.com/lenar-amirov/product-pipeline-public.git pm-copilot
cd pm-copilot && claude
```
That's it. No questions, no restart, no required dependencies — bare
`python3` is enough (`pip3 install rich` is optional, for a prettier
dashboard).
**No git?** [Download ZIP](https://github.com/lenar-amirov/product-pipeline-public/archive/refs/heads/main.zip), unpack, open the folder in [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
**Where your work lives**: initiatives are created by the tool itself
inside this folder (`{your-name}/{initiative}/`) — gitignored by design,
so they never enter the public repo and never conflict with updates.
**Updates**: `git pull`. Your initiatives are untouched; if you've
customized `CLAUDE.md`, stash your changes first or work in a fork.
### 2. Describe your problem
You'll see:
```
╭────────────────────────────────────────╮
│ │
│ ◆ Product Discovery │
│ PM Copilot │
│ │
╰────────────────────────────────────────╯
What product problem are you working on?
Or start with a job right away:
"read this deck" · "I need an analyst brief" · "break down problem X"
```
Type one sentence. For example:
> Users add items to cart but never complete checkout on mobile
### 3. Value first — the initiative is created after
Claude runs the matching job immediately: for a problem statement you get
3–5 problem hypotheses (typed `INFERRED` until validated) with ONE sharp
challenge question woven in; for "here's a deck from the analyst" it
ingests the deck; for "I need an analyst brief" it writes the brief.
Only then it offers: *"Save this as initiative `<slug>`?"* — say yes and
the folder appears with a hypothesis registry, status and a decision log.
Close Claude, come back next week — the session resumes exactly where you
stopped, with the dashboard showing coverage, overdue dependencies and
evidence issues.
---
## How it works — jobs, not steps
You don't march through a checklist. You come with a moment — "read this
deck", "which hypotheses hold?", "tomorrow's the gate" — and call the
matching **job**. Each job works standalone and quietly records what it
learned into the initiative's state.
| Job | When you reach for it |
|---|---|
| `/hypotheses` | break a problem into testable hypotheses (MECE) |
| `/ingest` | you were handed a deck / export / wiki page — pull the numbers in |
| `/brief` | you need a brief for an analyst or designer |
| `/validate` | data arrived — confirm, refute or flag hypotheses against it |
| `/solutions` | turn confirmed problems into scored solution bets |
| `/sketch` | draw the screens for a solution |
| `/challenge` | rehearse a gate — three hostile stakeholders attack your deck |
| `/tickets` | break the solution into Jira/Linear/GitHub tickets |
| `/next` | "what's the most valuable thing to do now?" |
| `/deep-think` | a strategy question that isn't an initiative yet |
Legacy step commands (`/analyze-cjm`, `/validate-problems`, …) still work as
aliases — the numbered pipeline (steps 0–19) is the internal structure the
jobs draw on, not something you navigate by hand.
### Progress is evidence coverage, not "step N of 20"
The dashboard shows a **coverage map** of seven phases, computed from your
actual state — the registry, the artifacts, the gate checks — not from how
many commands you've run:
```
Frame 2/4 · Evidence 3/3 · Solution 0/2 · Bet 0/1 · Build 0/2 · Launch 0/3 · Learn 0/1
focus → Solution: no solutions linked to confirmed hypotheses yet
```
Gates (Problem Research Report, Solution Research Report) have **machine
preconditions**: you can't assemble the deck until ≥2 hypotheses are
confirmed REAL, the registry has no unreconciled contradictions, and the
frame (metric / target / kill criteria) is set. After launch, the **Learn**
phase closes the loop — actual vs target, production verdicts on each
hypothesis, and reusable facts banked for your next initiative.
### What you accumulate over the journey
| Artifact | What it is |
|----------|-----------|
| **CONTEXT.md** | The initiative's frame: metric, segment, baseline, constraints, OKR — never re-explained |
| **hypotheses.json** | Machine-readable hypothesis registry: status, evidence type, confidence, sources, full history of every transition. Validated on each session start; `registry.md` and `ost.md` (Opportunity Solution Tree) are generated views |
| **status.json** | Machine state: step statuses, `dependencies[]` (external work with owner + deadline, flagged OVERDUE on the dashboard), pipeline config — Claude resumes from here |
| **decisions.md** | Log of every meaningful decision and discussion across sessions |
| **hypotheses.md** | Narrative hypothesis analysis (the registry holds the machine state) |
| **.initiatives-digest.md** | Auto-generated cross-initiative summary + banked knowledge facts — Claude spots overlaps with past initiatives |
| **PRD.md** | Living document — sections fill as evidence arrives, not at the end |
| **Problem Research Report** | Gate deck: validated problem + solution sketch (gate-checked before assembly) |
| **Solution Research Report** | Gate deck: designed solution + AB test plan (gate-checked before assembly) |
| **tickets.md** | Dev tickets — pushed to Jira/Linear/GitHub via MCP if connected |
---
## What's bundled
| Component | Role |
|-----------|------|
| `CLAUDE.md` | Master prompt — session lifecycle, FIRST LAUNCH value-first flow, JOBS CATALOG |
| `.claude/settings.json` | `SessionStart` hooks: dashboard, initiatives digest, evidence audit |
| `.claude/skills/` | 23 specialized skills — problem structuring, ingestion, validation, scoring, gate rehearsal, PRD, post-launch review, etc. |
| `.claude/rules/` | Path-scoped rules: output formats, evidence typing, writing style |
| `template/` | Initiative scaffold copied for each new initiative |
| `tools/scripts/status.py` | Terminal dashboard: coverage map, OVERDUE dependencies, `/next` hint |
| `tools/scripts/hypotheses.py` | Hypothesis registry engine: add / set / validate / render (state + full history) |
| `tools/scripts/validate-evidence.py` | Evidence audit + `--gate` preconditions that block deck assembly |
| `tools/scripts/coverage.py` | The coverage map: 7 phases with exit criteria computed from actual state |
| `tools/scripts/scan-initiatives.py` | Regenerates `.initiatives-digest.md` — cross-initiative awareness at every session start |
| `tools/scripts/render-ost.py` · `render-pdf.py` · `generate-pptx.py` | Opportunity Solution Tree, PDF→PNG for `/ingest`, gate decks → .pptx |
| `tools/scripts/check-leaks.py` + `install-hooks.sh` | Pre-push guard against committing personal data (see Privacy) |
| `tools/web/` | Optional read-only web dashboard (Flask) + `static_export.py` — dependency-free single-file HTML export |
(Full inventory with the "why" of every file: [docs/REPO-MAP.md](./docs/REPO-MAP.md).)
### Your initiative folder
```
you/my-initiative/
├── CONTEXT.md ← metric, segment, baseline, constraints
├── CJM/ ← user journey screenshots
├── research/ ← analytics briefs, survey design, competitive analysis
└── output/ ← hypotheses, PRD, presentations, decision log
```
### No templates to choose — you run the jobs you need
There's no "pick a workflow" step. A new initiative starts with everything
available; you call the jobs your situation calls for, and the coverage map
shows what evidence is still missing. Got rich data already? Go straight to
`/ingest` and `/validate`. Fuzzy problem? Start with `/hypotheses`. Only a
strategy question? `/deep-think`. Each step carries a Core / Recommended /
Optional weight so `/next` knows what's safe to skip — but the choice of
what to do is always the job in front of you, never a template up front.
---
## Tracker integration
After Solution Research Report, push tickets to your tracker via MCP. Set the tracker in `CONTEXT.md` → `## Tracker` section.
### Jira + Confluence
MCP config lives in `.mcp.json` at the repo root — **gitignored**, because it holds your real API token. Never put credentials in `.claude/settings.json` (tracked by git).
1. Copy `.mcp.json.example` → `.mcp.json`
2. Fill in your Jira/Confluence URL and API token
(Atlassian Cloud: https://id.atlassian.com/manage-profile/security/api-tokens)
3. If your company runs a different Jira/Confluence MCP server package, put its `command`/`args` in — the example uses a placeholder package name
4. Restart Claude Code and approve the servers when prompted
### Linear
Add a `linear` entry to the same `.mcp.json` with the MCP server your team uses (API key: Linear → Settings → API → Personal API keys).
### GitHub Issues
No extra MCP — Claude Code uses `gh` CLI natively. Run `gh auth status` to verify you're logged in.
### No tracker
Skip MCP. `/create-tickets` writes `output/tickets.md` for manual copy-paste.
---
## Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — CLI, desktop app, or IDE extension (not web)
- Python 3.9+ (macOS system Python works; no packages required for the core)
- `pip3 install rich` — optional, prettier terminal dashboard (plain-text fallback works without it)
Optional, install on demand:
- `pip3 install python-pptx` — when you reach `/create-presentation` (step 10) or `/create-gate2-presentation` (step 15)
- `pip3 install flask markdown` — only if you want the optional Flask web dashboard at `tools/web/app.py`
---
## Optional: Flask web dashboard
`tools/web/app.py` provides a visual dashboard:
```bash
pip3 install flask markdown
PM_USERS=$(cat .pm-local) python3 tools/web/app.py
# open http://127.0.0.1:5000/{your-name}/
```
It binds to `127.0.0.1` and is a **local viewer** — it has no real authentication. Set `PIPELINE_HOST=0.0.0.0` only on a network you trust.
No Flask? `python3 tools/web/static_export.py <you>/<initiative>` emits a self-contained HTML dashboard for one initiative (no dependencies).
Most users don't need either — `tools/scripts/status.py` (auto-run at session start) shows the same info in the terminal.
---
## FAQ
**How do I continue working?**
Open Claude Code in the project directory. The SessionStart hook runs `status.py` which loads your last state. Type "continue" and Claude picks up where you stopped.
**Do I have to run every step?**
No. Run the jobs your situation needs; the coverage map shows what evidence is still missing, and `/next` recommends the most valuable action from your actual state. If you want to switch a specific step off, tell Claude "disable competitor research" — the per-step config lives in `output/status.json` → `pipeline_config`. (There are no workflow templates to pick — that model was retired.)
**Can I work on multiple initiatives in parallel?**
Yes. Each initiative is a separate folder with its own `CONTEXT.md`, `status.json`, `decisions.md`. Claude shows all initiatives at session start; you select one.
**What are Problem Research Report and Solution Research Report?**
Two presentations for stakeholders:
- **Problem Research Report** (after step 10) — validated problem + solution sketch
- **Solution Research Report** (after step 15) — designed solution + AB test plan
**What's the difference between step types?**
- **Core** — pipeline breaks without it
- **Recommended** — strongly suggested; skipping reduces confidence
- **Optional** — useful in specific contexts only
**Where are my personal preferences stored?**
- `pm-profile.md` — your role, company, working style (gitignored, personal)
- `.product-corrections.md` — accumulated corrections you've taught Claude (gitignored)
- `.initiatives-digest.md` — auto-generated overview of all your initiatives
---
## Get in touch
Product Discovery ships continuously — see [CHANGELOG](./CHANGELOG.md) for what's new and [docs/](./docs/) for the design decisions behind the tool. Real PM feedback shapes the next iterations.
- 🐛 **Bug?** → [open an issue](https://github.com/lenar-amirov/product-pipeline-public/issues/new?template=bug.yml)
- 💬 **Tried it? Share how it went** → [feedback issue](https://github.com/lenar-amirov/product-pipeline-public/issues/new?template=feedback.yml)
- 💭 **Questions, ideas, just want to chat** → [Discussions](https://github.com/lenar-amirov/product-pipeline-public/discussions)
- 🎉 **Show off your initiative** → [Discussions / Show & Tell](https://github.com/lenar-amirov/product-pipeline-public/discussions/categories/show-and-tell)
---
## Privacy
Product Discovery is local-first — there is no server, no telemetry, no analytics. Everything lives on your machine. Claude Code processes your conversation through Anthropic; integrations you connect (Jira / Linear MCP) see the ticket data you push.
Extra guard for contributors: `tools/scripts/install-hooks.sh` installs a
pre-push hook that blocks pushes containing initiative folders, credential
files, token-like values, or your personal markers from a gitignored
`.leak-patterns` file.
See [PRIVACY.md](./PRIVACY.md) for full details.
---
## License
MIT