shipshitdev/shipcode/writing-prds

Writing Shipcode PRDs

A PRD in shipcode is the input contract for the pipeline's plan phase. A good PRD is what lets the planner agent produce a usable plan in one shot instead of burning turns asking the user "what did you mean by X?". A bad PRD causes planner thrash, review rejection, and verification failures downstream.

Storage Location

The GitHub issue body IS the PRD. There is no local sidecar file, no .shipcode/prds/ directory, no SQLite-only draft. One document per work item, one location: the body of a GitHub issue in the project's connected repo.

• Create a PRD by creating a GitHub issue whose body is clean PRD markdown.
• Edit a PRD by editing that issue's body.
• Version history is GitHub's issue edit history — no manual updated field bumping.
• The pipeline reads the issue body verbatim (packages/pipeline/src/pipeline.ts:581 — const prompt = \GitHub Issue #${issue.number}: ${issue.title}\n\n${issue.body ?? ''}\``) and feeds it into the planner agent. What you write in the issue body is exactly what the planner sees.

If shipcode's onboarding has not been completed (no GitHub repo connected), you cannot write a PRD yet. Complete onboarding first — shipcode is mandatory-GitHub by design.

Native GitHub Metadata

Do not put YAML frontmatter at the top of GitHub issue bodies. GitHub renders issue-body frontmatter as visible noise and already has native places for this metadata.

Use native GitHub and Projects fields instead:

• Issue type: Feature, Bug, or Task.
• Project status: Backlog, In Progress, Human Review, Done, or Deferred.
• Project priority: P0, P1, P2, or P3.
• Project complexity: Low, Medium, or High.
• Project blast radius: Contained, Cross-package, Cross-app, or Infra.

Rules:

• The PRD body starts with # PRD: <name> and contains only human-readable PRD content.
• Put card/list summaries in the issue title, project fields, or a short Executive Summary, not in hidden metadata.
• If the author cannot estimate complexity, set the project field to Medium and explain why in Risks & Open Questions.
• Draft is workflow state, not body text. Keep draft PRDs off the runnable kanban path through project status or app state.

Issue Title Style

The GitHub issue title is what the board shows most of the time. Keep it short.

• Prefer 4-7 words when possible.
• Prefer an imperative verb + object shape: Add pipeline checkpoints, Track CI blockers on issues, Expose model selectors in SettingsPanel.
• Put the detail in the Executive Summary and body, not in the title.
• Avoid titles chained together with and / while / during unless the feature is truly one inseparable unit.
• Avoid titles that restate the full implementation loop. The title names the work item; the PRD explains it.
• Keep the # PRD: name aligned with the final issue title's slugified form. If you shorten the title, shorten the PRD heading too.

Bad:

• Open draft PR during execution and ingest PR feedback into stabilization loop
• Treat CI failures as blocker state on GitHub issue tasks

Better:

• Add draft PR feedback loop
• Track CI blockers on issues

Required Sections

Every shipcode PRD must have these sections, in this order. Missing sections fail quality gate.

# PRD: <name>
 
## Executive Summary
<2–4 sentences. What is this feature, why now, who wins.>
 
## Problem Statement
<The concrete pain. Reference real incidents, real users, real metrics where possible.
Avoid "users might want..." — if you can't name the user, you don't have a problem yet.>
 
## Goals
-<measurable, verifiable goal>
-<measurable, verifiable goal>
 
## Non-Goals
-<thing this explicitly does NOT do — the more you list, the less scope creep downstream>
 
## User Stories
-As a <role>, I want <capability> so that <outcome>.
-Each story ends with "**Acceptance:**" followed by 1–3 concrete checks.
 
## System Specification
<Observable system contract for the feature. Include user-visible states, data
contracts, permissions/trust boundaries, failure behavior, and integration
points. Do not name files, functions, libraries, or implementation details.>
 
## Functional Requirements
<Numbered list. Each item must be verifiable by reading code or running it.
NO implementation details — "the system must do X", not "use Zustand to do X".>
 
## Non-Functional Requirements
<Performance, accessibility, error-handling, offline, observability.
Only list the ones that actually matter for this feature.>
 
## Feature Phase Breakdown
<Exactly three product-level phases, in order. These are the phases the planner
must translate into the three ordered ShipCodePlan steps.
1.Foundation/spec plumbing — contracts, persistence, configuration, or shared
   surfaces needed before behavior can be implemented.
2.Primary feature behavior — the actual user/system capability.
3.Hardening/verification/shipping polish — tests, error handling,
   observability, docs, or UI polish needed to ship confidently.
Each phase must include: purpose, in-scope behavior, out-of-scope behavior, and
a concrete completion signal.>
 
## Success Criteria
<The bar the pipeline's verification phase will check against.
Every bullet here becomes an entry in `PlanStructured.acceptanceCriteria`
(`packages/shared/src/types.ts:10`). Write them like test assertions.>
 
## Out of Scope
<Becomes `PlanStructured.outOfScope`. Be ruthless. Future-proofs the review phase.>
 
## Dependencies
<Other PRDs, packages, external APIs, feature flags. Reference by path or URL.>
 
## Verification Plan
<How the verifier will know this shipped correctly.
`tests`: list the test files/suites that must exist and pass.
`manual`: list the manual QA steps a human will run post-merge.
`both`: both sections.
Shipcode's verification phase (`packages/pipeline/src/pipeline.ts:380`) runs
`buildVerificationPrompt(plan, diff, plan.acceptanceCriteria)` — the clearer
this section is, the fewer verification retries you burn.>
 
## QA State
<Optional but required for features where ShipCode should collect browser QA evidence.
Include a fenced JSON block matching `FeatureQaState`.
Use `visualAssertions` for layout or placement requirements that should be proven by Playwright.
For example: target selector, route, assertion (`top-left-of-container`, `not-overlapping`, etc.),
container/reference selector, tolerance, and viewport.
Set `selectorReadiness` to `ready` only when stable selectors are part of the contract.>
 
## Risks & Open Questions
<Unknowns, edge cases, things that could kill the plan mid-execution.
Open questions get tracked here until answered, then deleted.>

Mapping to Shipcode's Pipeline

A PRD is read by the planner agent. Every section has a downstream consumer:

Do not write sections that describe files to change, function names, or implementation choices. Those belong in the plan, not the PRD. If the PRD author can't resist writing pseudo-code, put it under "Risks & Open Questions" as "I suspect we'll need to touch X" — not as a requirement.

Quality Gates

Before marking a PRD ready for the pipeline to consume, every one of these must be true:

• [ ] No placeholder text (TODO, TBD, <fill this in>) remains in any section.
• [ ] Goals has at least one measurable bullet.
• [ ] Success Criteria has at least one bullet, and every bullet is verifiable without judgement — it either passes or fails. "Feels fast" is not verifiable. "p95 latency < 300ms on the issues query" is.
• [ ] Out of Scope has at least one bullet. Empty Out of Scope is a tell that the author didn't scope the feature.
• [ ] User Stories has at least one story with explicit Acceptance bullets.
• [ ] System Specification names the observable states, data contracts, permissions/trust boundaries, and failure behavior that matter for the feature.
• [ ] Feature Phase Breakdown contains exactly three ordered phases, and each phase has a purpose, scope, and completion signal.
• [ ] Every external dependency in Dependencies is named (package, PRD path, or URL), not described vaguely.
• [ ] Verification Plan names either test file paths, suite names, or concrete manual steps — not "write some tests".

If any gate fails, keep it in draft/deferred workflow state and do not offer "Start pipeline" in the kanban.

Workflow

When the user says "write a PRD for X"

1. Verify GitHub is connected. The user must have completed shipcode onboarding with a repo selected. If not, stop and tell them to finish onboarding first — there is no other place a PRD can live.

1. Do not start writing immediately. Run a short elicitation pass first — you need answers before section-filling is meaningful:

• What problem does this solve, and for whom specifically?
• What does success look like — how would we measure it?
• What is explicitly out of scope?
• What's the complexity gut feel (low/medium/high) and why?
• Any hard constraints — deadlines, other projects in flight, package boundaries?

1. Check for an existing issue. Run gh issue list --search "<keywords>" --state all in the target repo. If a matching issue already exists, ask whether to edit it or create a fresh one.

1. Kebab-case the PRD name. If the proposed name has spaces, camelCase, or punctuation, kebab-case it: "Notification Center" → notification-center. This slug goes in the # PRD: heading.

1. Compress the issue title before writing the body. Default to a short imperative title, then derive the # PRD: heading from that final title. Put nuance in the Executive Summary, not the title.

1. Draft the PRD body using the template above, in a scratch buffer. Fill every required section. If you can't fill a section, ask the user — don't hallucinate requirements.

1. Run the quality gates against the draft. If any fail, keep the issue in draft/deferred workflow state and tell the user which gates failed. If they all pass, mark it ready through native project/app state.

1. Create the GitHub issue. Preferred: use the desktop app's Create PRD modal (which calls the github:create-issue IPC handler — the handler wraps gh issue create and upserts the cache). Alternative for CLI contexts: gh issue create --title "<Human Readable Title>" --body-file - with the PRD markdown piped on stdin.

1. Confirm the outcome to the user with the issue URL. Suggest next step: "Ready to hand this to the planner? Click Start pipeline in the kanban, or say: plan issue #N".

When the user says "plan the X PRD"