# Discovery Plan

> discovery-plan

- Skill: `subvisual/discovery-plan` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add subvisual/discovery-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/subvisual/discovery-plan/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: subvisual (https://skillmd.com/u/subvisual)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/subvisual/discovery-plan

---


# discovery-plan

Turn what discovery learned — and did not learn — into the two durable planning
artifacts, compiled together in one pass so they cannot drift:

- **`docs/product/ateam-plan.md` — the plan built for the A-Team agents.**
  Goals (each traced to the jobs it serves) and the deliverables to reach v0,
  grouped into initiatives with owners and dates, gated by decision criteria.
  This is what the A-Team runs against — and how anyone reading the repo
  understands where the work is going. Not a project plan and not the research
  plan; the name says whose plan it is.
- **`docs/product/research-plan.md` — the research plan.** The document that
  ships together with the v0 final outputs: **open questions** (what the v0
  was built without knowing), **assumptions + confidence** (everything agents
  and humans assumed, what would disprove each, the cheapest probe), and
  **technical research** (services, stack, and the cost breakdown of every
  integration in play).

The split line: *what we'll do* goes in ateam-plan.md; *what we don't know, assumed,
or researched* goes in research-plan.md. The same compile step writes both —
a deliverable that closes an unknown appears in ateam-plan.md as work and in
research-plan.md as the question it closes.

**A third artifact, at the pr phase only** — `docs/product/project-plan.md`,
the plan for the **project after v0**: what is left undone, what the epics say
comes next, what the surviving open questions imply for the roadmap. It is the
plan the *human team* picks up, as distinct from ateam-plan.md (the plan to
*reach* v0, for the agents) and research-plan.md (the disclosure *shipping
with* v0). Three plans, three horizons; conflating them under one name is what
made this file necessary. Write it only when invoked by the pr phase's plan
refresh — mid-run there is no v0 yet to plan past, and a project plan written
from intentions is fiction.

This is the bridge from evidence into definition (`prd-writer`, `wireflow`,
`page-brief`) — and the reason stopping discovery loses nothing: every
non-blocking unknown lands in the research plan instead of dying in a chat.
This skill **consumes** finished jobs and synthesis; it never mints or rewrites
jobs (`jobs-to-be-done`) and never synthesizes raw evidence
(`research-synthesis` first).

## Where it writes

`<target>/docs/product/ateam-plan.md` + `<target>/docs/product/research-plan.md`
(+ `<target>/docs/product/project-plan.md`, pr phase only) —
repo-first-and-always; a Cowork folder is a valid target, never a blocker.
Durable rules apply to all: **update-only** (refresh what changed, keep what
holds — a rebuild that drops content is a forbidden overwrite), mandatory
**read-back** before writing, one commit per run naming what changed
(`docs(plan): compliance unknown resolved; 2 new dev-phase assumptions`).

**All plans stay live.** Re-run this skill at any phase — after a brainstorm
adds ledger entries, after a synthesis lands verdicts, after design or dev
surface new assumptions — and it folds the new material into both files.
Keeping them current downstream is the PM's standing duty; this skill is how
it's done.

## Inputs

- `docs/product/context.md` — the Know/Don't-Know ledger is the primary feed:
  surviving unknowns become open questions; ledger assumptions carry their
  confidence in.
- `docs/product/research/` — synthesis runs; cite them as the evidence spine
  (verdicts included), never duplicate their content.
- `docs/product/jtbd/` — active jobs, ids + verbatim headlines. Suggested new
  jobs must pass through `jobs-to-be-done` before entering either plan; the
  plans hold proper job statements or an explicit `TBD`, nothing in between.
- The current problem statement, constraints, stakeholder goals, timelines.
- Connectors (Notion, Granola, Slack, ops API) if available — pulled material
  the plans lean on is staged verbatim into `input/<date>-<source>-pulled/`
  per the contract. Never block on a connector.

## Outputs

- `ateam-plan.md` in the shape of `references/plan-template.md`: Goals (job-traced) ·
  Deliverables to reach v0 · Initiatives (owner, date) · Decision criteria ·
  Status.
- `research-plan.md` in the shape of `references/research-plan-template.md`:
  Evidence spine (cited) · Open questions · Assumptions (confidence + disproof
  + cheapest probe) · Technical research (services, stack, integration costs) ·
  Research activities (owner, date).
- `project-plan.md` in the shape of `references/project-plan-template.md` —
  **pr phase only**: Where the v0 leaves us · What comes next (each item traced
  to an epic or job) · What the open questions imply · Known debt from the v0 ·
  Not planned. Omitted entirely on every other invocation.
- The closing handoff: **Next likely skill(s)** · **What to pass forward** ·
  **Suggested next prompts**.

## Workflow

1. **Load the ledger and the evidence.** Read `context.md` (ledger first),
   the `research/` runs, and the active jobs. If raw evidence is still
   unsynthesized, stop and route to `research-synthesis` — a plan built on
   un-digested mess plans the wrong unknowns.
2. **Evidence spine first** (research-plan side). Cite the synthesis runs and
   summarize each verdict in a line — which jobs stand solid, which need
   discovery work.
3. **Fix the job framing.** Ids + verbatim headlines. Challenged/refinement
   verdicts and new-job signals route through `jobs-to-be-done`; unresolved
   jobs enter as `TBD` with resolving them listed as a research activity.
4. **Split the ledger.** Surviving unknowns → research-plan **open questions**
   (each tagged with what changes if answered; a still-open blocking unknown
   is stated loudly at the top). Ledger and brainstorm assumptions →
   research-plan **assumptions**, each with confidence, disproof, cheapest
   probe. Never let an assumption hide inside polished prose.
5. **Technical research** (research-plan side). Services, stack, and every
   integration in play: options considered, cost (money, effort, risk),
   chosen or open. Unanswerable API questions become research activities.
6. **Goals and deliverables** (PLAN side). Goals traced to jobs; the
   deliverables that must exist to reach v0 — including resolution
   deliverables that close research-plan questions. Group into initiatives
   with owners (human or agent) and dates; define the decision criteria that
   gate them.
7. **Cross-check.** Every research activity has a home in an initiative or is
   explicitly deferred; every resolution deliverable points at its question.
   The files must read as one plan split by audience — and when the project
   plan is in play (step 8), its "What comes next" must not contradict
   `ateam-plan.md`'s remaining deliverables: anything still listed as work to
   reach v0 is either done, carried forward, or explicitly dropped with a
   reason.
8. **The project plan — pr phase only.** When invoked by the pr phase's plan
   refresh (a v0 exists and is integrated), also compile
   `project-plan.md` per `references/project-plan-template.md`: where the v0
   leaves us, what comes next traced to epics/jobs, what the surviving open
   questions imply, the debt taken on purpose, and what is explicitly not
   planned. **Cite, never restate** — this file is the forward view across the
   others, and the only one allowed to speculate.
   **Ground "Where the v0 leaves us" in what actually shipped.** On a first v0
   run `ateam-product-report.md` does not exist yet — the plan refresh runs
   before it — so ground that section in `issues.md` statuses and the
   integrated feature branch. On a refresh, when the report does exist, cite it
   instead; it is the better-grounded source. Skip this step entirely on any
   other invocation: mid-run there is no v0 to plan past.
9. **Read-back, write, commit.** Present every draft you produced (or diffs, on
   refresh) for correction; write; update `updated:`/`evidence:` frontmatter;
   commit.
10. **Hand off.** Unknowns reduced enough to define scope → `wireflow` (map
   validated journeys) → `page-brief` (per-screen requirements) →
   `prd-writer`; page-light features go straight to `prd-writer`. Pass
   forward the problem statement, jobs, validated assumptions, and open
   questions.

## No human present

The read-back gate needs a human. With nobody present, deliver every draft in
your report only, write nothing durable, and state that the run awaits review.
Never commit an unreviewed research plan — it ships with the v0 as the honest
record; an unreviewed one is neither.

## Templates

- `references/plan-template.md` — `ateam-plan.md`
- `references/research-plan-template.md` — `research-plan.md`
- `references/project-plan-template.md` — `project-plan.md` (pr phase only)

## Examples

- Input: `examples/example-input.md` · Output: `examples/example-output.md`