Planning Docs — Design Docs and Product Specs

Planning docs live in the platform repo so engineering's source of truth stays in one place. Two kinds exist:

Product specs — what to build, from product's perspective.
Design docs — how to build it, from engineering's perspective.

Both follow lean section templates. The conventions below are deliberately minimal — they will be edited as we use them on real features.

Intake — where work enters

Work reaches engineering from several origins, not one. The mistake to avoid is building a separate pipeline per origin: there are several front doors, one shared spine. Match the entry artifact to the weight of the work; everything converges on the same downstream flow.

Origin	Typical weight	Entry artifact	Created via
A discussion that reached decisions	medium–high	decision record — ADR (technical) or decision log (product/business/process)	`/decision`
A product request, not yet technically scoped	varies	PRD	hand-authored under `docs/prds/`
An idea, not yet decided	low	proposal	`/propose`
A bug from support, a system-detected issue, a small customer POC	small	straight to a GitHub issue — no planning doc	`/breakdown` free-text

The shared spine all of these feed into:

entry artifact → /breakdown → tasks → (per task, if it needs how) deep-research → design doc → issues → DoD

A decision record sits above the tasks — its action items are the breakdown source. A design doc sits below a task — it is written per task, after research, only when the task is large enough to need a how. Routing between front doors is a one-line human judgment, not an automated step.

Classify by lifecycle stage, not by how implementation-shaped the content feels. A write-up full of schema, endpoints, and storage options still belongs in a proposal while the WHAT is undecided — a design doc presumes the WHAT is settled (it sits below an approved task / a ready-for-rd PRD). Reaching for a design doc just because the content "looks technical" skips the very decision the proposal exists to make. Symptom to catch: a design doc with no real related_prd / approved decision behind it — that is a proposal wearing the wrong template.

The product-spec front door is intentionally a stub here — its full intake shape is being defined separately. Treat this row as an anchor, not the final word.

When to write which

Scenario	What to create
Small, clear coding task	Skip both — go straight to GitHub issues using the issue format (see workflow memory).
Large or complex feature, scope decisions to make	Design doc → design review → GitHub issues.
Product brief that has not yet been technically scoped	Product spec → design doc → design review → GitHub issues.
Spec that has reached engineering	Spec stays as-is; a new design doc references it.

File locations and naming

Doc kind	Path	Filename
Product spec	`docs/prds/`	`<slug>-<clickup-id>.md`
Design doc	`docs/designs/`	`<slug>-<clickup-id>.md`
Decision record (technical)	`docs/adrs/`	`adr-NNN-<slug>.md`
Decision record (product/business)	`docs/decisions/`	`<slug>.md`

<slug> is short kebab-case (e.g., provider-validator-hook). <clickup-id> is the parent ClickUp task ID (e.g., CU-12345). Do not use placeholder IDs — if there is no ClickUp task yet, create one before the doc.

Decision records carry no <clickup-id>. They are upstream of task creation — the tasks are generated from the record, so the record cannot reference an ID that does not exist yet. ADRs are numbered adr-NNN; decision log entries are <slug>. See decision-record.

Product spec template

Copy this when starting a new spec under docs/prds/:

---
title: <spec title>
clickup_id: CU-XXXXX
product_owner: <name>
created: YYYY-MM-DD
---

# <Spec title>

## Why
The business problem or user pain this addresses. Two to four sentences.

## Outcome
What changes for the user when this ships. Observable, not internal.

## Requirements
Numbered, testable. Each line is a verifiable behavior.
1. ...
2. ...

## Out of scope
What is explicitly *not* in this spec.

## Success metrics
How we will know it is working. Measurable.

## Open questions for engineering
- ...

## References
- ClickUp: <link>
- Related specs or design docs: <link>

Design doc template

Copy this when starting a new design under docs/designs/:

---
title: <feature title>
clickup_id: CU-XXXXX
authors: [ariel@bewith.io]
created: YYYY-MM-DD
---

# <Feature title>

## Context
Two to four sentences: what the problem is and why it matters now.

## Goals
Bulleted, concrete, observable.

## Non-goals
What is explicitly *not* in the scope of this design.

## Options considered
### Option A — <short name>
What it is. Pros. Cons.

### Option B — <short name>
What it is. Pros. Cons.

## Decision
The chosen option, with one to three sentences of rationale.

## Implementation plan
The breakdown into coding tasks. Each becomes a GitHub issue per the project's issue format.

- [ ] Task 1: ...
- [ ] Task 2: ...

## Risks and open questions
- ...

## References
- ClickUp: <link>
- Related ADRs: <link>
- Related specs or design docs: <link>

Workflow

Spec lands first (if applicable). Product authors it; review happens in PR.
Design doc is written by engineering — typically with AI assistance — referencing the spec when one exists.
Design review happens on the design doc PR. The PR is the conversation surface — reviewers comment inline on the doc, the author resolves and updates, and an approach disagreement is raised here, before the code exists, where it is cheap to change (see Human Review in an AI Workflow). Design docs stay in-repo markdown; GitHub Discussions are reserved for RFC-shaped, cross-team, or durable debates that link back to the doc — see ADR-003.
Once the design doc is merged, the Implementation plan section is the source for GitHub issue creation. Each task becomes one issue.
Coding happens against those issues. The parent ClickUp task closes when all child issues close.

See the workflow memory (project_workflow_task_lifecycle) for the full lifecycle.

Conventions for both kinds of doc

All content in English. Chat with stakeholders can be in any language; the doc itself is English.
No placeholder values. If a section has no content, write a single sentence saying so (e.g., "No risks identified at design time."). Do not leave TBD or xxx.
Keep it short. A design doc longer than two scrolled pages is usually trying to do the job of an ADR or a runbook. Move that content to its proper home and link.
Edits welcome. These templates will evolve as we use them on real features. Open a PR against this file when a section consistently goes unused or a missing section keeps coming up.

Cross-references

artifact-types.md — decision tree for platform artifacts (when ADR vs design vs rule, etc.).
ai-engineering-strategy.md — the broader system that planning docs feed into.
Workflow memory (project_workflow_task_lifecycle) — the full task lifecycle these docs live inside.
GitHub issue format memory (project_gh_issue_format) — what each coding task issue looks like once extracted from the implementation plan.

Intake — where work enters​

When to write which​

File locations and naming​

Product spec template​

Design doc template​

Workflow​

Conventions for both kinds of doc​

Cross-references​