Product planning

---
name: product-planning-doc-pack
description: Turn a software product, feature, tool or app idea into a short set of working planning docs before any code is written - PRD, architecture, surface spec (UX, CLI or API), data sources, a milestone-by-milestone implementation plan built from thin end-to-end slices, risks and agent guidance. Use when the user says "write a PRD", "make a planning pack", "scope this properly", "plan this before we build it", "prepare docs before building", or has a promising but fuzzy idea for a new repo or substantial feature.
---

# Product Planning Doc Pack

Turn a promising but unclear software idea into a compact set of working documents that make it clear what to build first and why.

The job is **planning, not implementation and not launch prep**. A good pack lets someone (or a coding agent) start the first slice tomorrow knowing who it's for, what's in and out of v1, how it fits together, where the data comes from, and what could kill it.

Avoid documentation theatre. If a section doesn't change what gets built, tighten it or delete it.

## When to use

- Starting a new product, tool, library, CLI, API or substantial feature.
- Creating a repo before scaffolding it.
- Turning a messy idea into a PRD plus build plan.
- "Write a PRD", "make a planning pack", "scope this properly", "prepare docs before building".
- There's real uncertainty about product, UX, API, data or architecture.

Do not use when:
- the change is small and obvious;
- a PRD already exists and the user only wants implementation tasks;
- the user only wants brainstorming, or wants the idea challenged (use the `challenge-me` skill if installed);
- the product is finished and the user wants demo or launch material;
- the user explicitly wants code now and accepts the ambiguity.

## Output location

Write files under `planning-docs/`:

```text
planning-docs/
  prd.md
  architecture.md
  surface-spec.md
  source-map.md
  implementation-plan.md
  risks.md
  agent-guidance.md
```

Optional: `eval-plan.md` for AI or model-heavy products; `research-notes.md` when outside research shaped decisions.

Add `planning-docs/` to `.gitignore` by default, for new and existing repos, unless the user wants the pack committed. It keeps working plans out of the project's real docs. Use `agent-guidance.md` instead of editing a root `AGENTS.md` or `CLAUDE.md`, unless the repo owner asks.

## Process

1. **Ground the context.** In an existing repo, read the README, manifests, existing docs, relevant tests, routes, schemas, commands or UI, and any `AGENTS.md`/`CLAUDE.md`. For a new project, look at linked docs, similar tools or competitors. If something can be inspected, inspect it. If not, ask one or two high-value questions, not a questionnaire.

2. **Pressure-test the idea lightly.** Who is the user? What painful job are they doing? What's the smallest useful v1? What's explicitly out? What assumption could kill it? If the idea is still mushy, suggest the `challenge-me` skill (if installed) before writing polished docs.

3. **Pick the surface type.**
   - **UX:** web, mobile, dashboard or visual app. Specify screens, flows, components and states, plus high-level design direction and anti-patterns.
   - **CLI:** commands, flags, JSON output, errors, exit codes.
   - **API or library:** public interfaces, examples, errors, compatibility.
   - **Hybrid:** only the surfaces that matter for v1.

   Don't force UX docs onto a CLI or library. Don't skip UX for a visual or operator-facing product.

4. **Write the docs** using `references/file-requirements.md` for what each file needs. Write decisions and assumptions, not essays: bullets, tables, examples and explicit non-goals.

5. **Plan vertical slices.** Plan the build as tracer bullets: thin slices that prove value end to end. Avoid horizontal milestones like "build backend", "build frontend", "write tests". The first slice should prove the architecture and the core value.

6. **Leave the plan maintainable.** `implementation-plan.md` is a working document with a status block and notes, so whoever builds it can update it as reality changes. To execute it, the user's agent can work milestone by milestone: build one slice, run its verification, update the status and notes, then move on.

7. **Run the final checklist** below, then reply in the output format.

## Quality rules

**Choose a sharp wedge.**

Weak: "A platform for everything." "A dashboard for all data." "A generic AI assistant for X."

Sharper:
- "A CLI that gives on-call engineers JSON access to incident timelines."
- "A booking app that lets members of a small gym reserve classes from their phone."
- "A local-first log viewer for scheduled jobs on one machine."

**Prefer vertical slices.** A good slice proves one narrow user or developer flow, uses real data or clearly labelled fixtures, goes through the public interface, can be tested by behaviour, and can be demonstrated when done.

**Be honest about mocks.** Mocks and prototypes are fine; pretending they're real isn't. Label behaviour as real, mocked, simulated, fixture-backed, dry-run or future integration.

**Treat code quality as scope.** Encourage small composable modules, obvious names, data readers and adapters kept separate from UI, typed contracts where the language supports them, behaviour-focused tests, and deep modules that hide complexity behind a simple interface. No giant files, and no speculative plugin systems unless they're the v1 wedge.

## Output format

After writing the pack, reply with:

```markdown
**Files:** [created or updated, under planning-docs/]
**Thesis:** [one sentence: "X for Y who need Z"]
**Biggest open decision:** [the one that most changes the build, and who decides]
**First slice:** [the first end-to-end slice to build], or the next planning question if it isn't ready
```

## Common failure modes

1. **Starting with the scaffold:** scaffolding before the product shape is clear creates a repo-shaped to-do list.
2. **One giant PRD:** keep requirements, architecture, surface, sources, risks and plan in separate files.
3. **Implementation detail as the pitch:** keep technology choices in `architecture.md`, not the thesis.
4. **Hand-wavy data sources:** name each source and define its contract. "TODO: find data" is not a plan.
5. **Smuggling v2 into v1:** park broad integrations and plugin systems unless they're the wedge.
6. **Weak testing decisions:** "add tests" isn't a plan. Name the behaviours and interfaces to test.
7. **A static plan:** forgetting to give the plan status and notes, so it goes stale after the first milestone.
8. **Questionnaire first:** asking ten questions that reading the repo would have answered.

## Final checklist

- [ ] Files are under `planning-docs/`, gitignored unless the user asked otherwise.
- [ ] The product thesis is one sharp sentence.
- [ ] Target users or actors are specific.
- [ ] v1 scope and non-goals are explicit.
- [ ] The surface type was chosen: UX, CLI, API/library or hybrid.
- [ ] Sources, paths, APIs, environment variables and boundaries are named, with assumptions marked.
- [ ] Architecture covers modules, data flow, persistence and integration boundaries.
- [ ] The implementation plan has a status block, notes, milestones, vertical slices and verification steps.
- [ ] Risks cover product, technical, security/privacy and delivery, with kill or pivot conditions.
- [ ] Mocked, simulated or dry-run behaviour is labelled.

## References

- `references/file-requirements.md`: what each file in the pack must contain, including the implementation-plan template.

With thanks to Matt Pocock's skills for ideas such as tracer bullets and deep modules.

# Planning pack: file requirements

What each file in `planning-docs/` should contain. Load this while writing the pack. Drop any section that would not change what gets built.

## `planning-docs/prd.md`

Audience: product and engineering alignment.

Include:
- product thesis: "This is X for Y who need Z";
- problem statement from the user's perspective;
- target users / actors;
- goals and success criteria;
- v1 scope;
- explicit non-goals;
- user journeys or workflows;
- user stories where useful;
- functional requirements;
- non-functional requirements: privacy, performance, reliability, accessibility, cost, platform constraints;
- terminology/glossary if new terms appear;
- assumptions and open questions.

Keep implementation details out unless they are product-shaping decisions.

## `planning-docs/architecture.md`

Audience: implementers and reviewers.

Include:
- system overview;
- runtime model: local, hosted, hybrid, CLI-driven, API-driven, offline-first, etc.;
- major modules and responsibilities;
- data flow, preferably with Mermaid or a compact text diagram;
- persistence model;
- integration boundaries and external dependencies;
- security and privacy assumptions;
- failure modes and recovery behaviour;
- testing strategy at a high level.

Call out deep module opportunities where complexity should hide behind a simple public interface: parsers, normalisers, policy engines, state machines, adapters, API clients.

## `planning-docs/surface-spec.md`

Audience: whoever implements the user-facing or developer-facing surface.

Infer which sections apply.

### UX section

Use for apps, dashboards, mobile products, websites, and visual tools.

Include:
- global shell/navigation;
- page-by-page or screen-by-screen structure;
- primary user flows;
- interaction states;
- empty, loading, error, offline, and permission-denied states;
- suggested component names;
- shared data contracts per page;
- copy/content requirements;
- accessibility notes;
- design direction and anti-patterns.

### CLI section

Use for terminal-first tools.

Include:
- commands and subcommands;
- flags/options;
- input/output formats;
- JSON/machine-readable mode if relevant;
- exit codes;
- examples;
- failure messages.

### API/library section

Use for APIs, SDKs, packages, and backend/library-first products.

Include:
- public interface shape;
- core concepts and terminology;
- example calls;
- errors and edge cases;
- versioning/backwards compatibility;
- behaviour-focused test examples.

## `planning-docs/source-map.md`

Audience: data-layer implementer.

Include:
- expected data sources: local files, APIs, CLIs, databases, RPCs, logs, user input, config, browser state, etc.;
- source-of-truth rules;
- environment variable overrides;
- read/write boundaries;
- normalised output contracts;
- scope model: global, per-user, per-workspace, per-project, per-team, per-entity, etc.;
- refresh/caching expectations;
- privacy/sensitive-data handling;
- assumptions needing confirmation.

If a path/API is unknown, write the assumption and how to verify it. Do not leave "TODO: find data" as the whole plan.

## `planning-docs/implementation-plan.md`

Audience: implementer or coding agent.

This is a **working document**, not a static plan. It should be safe for agents to update as milestones complete or assumptions change.

Start with:

```markdown
# Implementation Plan

## Current status

- Overall status: Not started / In progress / Blocked / Complete
- Last updated: YYYY-MM-DD
- Current milestone: Milestone N — name
- Current blocker: None / description
- Next action: one concrete next step

## Change log / notes

- YYYY-MM-DD — Initial plan created.
```

Then include milestones in dependency order. Each milestone should have:

```markdown
## Milestone N — Name

Status: Not started / In progress / Blocked / Complete
Goal: one sentence
Notes: working notes, discoveries, changed assumptions
Verification: command, manual check, or acceptance signal

## Slices

- [ ] Slice 1 — end-to-end behaviour or capability
- [ ] Slice 2 — end-to-end behaviour or capability
```

Rules:
- Use vertical slices, not horizontal layers.
- First slice should prove the architecture and core value.
- Include likely files/areas only when known.
- Include test strategy per milestone.
- Include verification commands where known.
- Keep deferred work parked clearly.

Default milestone shape:
1. Repo/bootstrap/hygiene.
2. Domain/source discovery.
3. First end-to-end tracer bullet.
4. Core workflow expansion.
5. Surface hardening.
6. Tests, docs, observability, release readiness.
7. Deferred extras.

## `planning-docs/risks.md`

Audience: decision-maker and implementer.

Include:
- product risks;
- technical risks;
- UX/API/CLI risks;
- security/privacy risks;
- delivery risks;
- scope creep traps;
- mitigations;
- kill/pivot conditions;
- assumptions to validate first.

## `planning-docs/agent-guidance.md`

Audience: future AI agents and contributors.

Use this instead of editing root `AGENTS.md` by default. The planning pack is usually private/working; root `AGENTS.md` should only change when the repo owner wants persistent repo-wide instructions.

Include:
- what the product is;
- current priority;
- non-goals;
- planning-docs structure;
- domain language / glossary pointer;
- testing expectations;
- UX/API/CLI expectations;
- security/privacy rules;
- local verification commands;
- how agents should work through the plan: one milestone at a time, verifying each slice before moving on;
- how agents should update `implementation-plan.md` status and notes.