---
name: to-prd
description: Turn the current conversation context into a PRD and write it to docs/work/prds/. Use when the user wants to materialize the discussion into a draft PRD that feeds the pnpm work pipeline.
---

This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know. If you need to interview first, invoke `grill-with-docs` instead.

The PRD lives on the filesystem (this repo does not use an issue tracker for work). The downstream pipeline is `pnpm work decompose` → epic + stories → tasks → sandcastle dispatch (see `docs/architecture/agent-first-workflow-and-conformance.md`).

## Process

1. **Explore the repo if you haven't already.** Use the project's domain vocabulary throughout (check `docs/glossary.md` if it exists, otherwise lift terms from `docs/architecture/vertical-feature-spec.md` §6 and the feature packages' `feature.manifest.ts`). Respect any ADRs in the area you're touching — they're at `docs/decisions/adr-NNN-<slug>.md`. Use `pnpm work status` to see in-flight epics.

2. **Sketch the major modules / packages.** Identify which existing packages (`packages/<feature>/`, `packages/core-*/`) you'll modify and which new ones — if any — you'll create. Actively look for **deep modules**: small interface, deep implementation, rarely-changing surface. The vertical-feature-package shape (entities → application → infrastructure → DI) is the default unit; resist scaffolding new core packages unless required.

   Check with the user that this module sketch matches their expectations. Confirm which modules they want tests written for. (The conformance system already mandates tests for every use case + controller; this question is about extra coverage — repository contract suites, integration tests, etc.)

3. **Pick a slug** for the PRD filename: `docs/work/prds/<kebab-slug>.prd.md`. No date prefix in the slug — the `created:` timestamp in frontmatter carries the date. Future task-tracker IDs (e.g. ClickUp) will land as `<task-id>-<kebab-slug>` once that integration ships; until then, bare slug only.

4. **Write the PRD using the template below**, then save it. Status starts at `draft`. The decomposer (`pnpm work decompose`) refuses to run on `draft` PRDs — the human flips it to `approved` after review.

<prd-template>

```markdown
---
id: <kebab-slug>
title: <Human-readable title>
type: prd
status: draft
author: <user>
elicitation-session: <agent-session-id-or-omit>
created: <ISO-8601-UTC-timestamp, e.g. 2026-05-14T19:23:45Z>
---

## Problem

What's broken or missing today? Who hurts because of it? Frame it from the user's perspective (where "user" may be a developer using the template, an end-user of an app built on it, or an AI agent operating in the codebase).

## Goal

What state are we trying to reach? One or two sentences.

## In scope

- Bullets of what this PRD covers.

## Out of scope

- Bullets of what's explicitly excluded. The explicit no-s are as valuable as the yes-s.

## Constraints

- Non-negotiables: existing ADRs to respect, conformance rules, performance budgets, compliance requirements, etc.
- Reference ADRs by ID: `ADR-014`, `ADR-017`, etc.

## Success criteria

- Verifiable outcomes. "Feature X passes `pnpm typecheck && pnpm test && pnpm conformance` green" is concrete; "feature X is great" is not.

## User stories

A numbered list. Cover all aspects of the feature, including edge cases.

1. As a `<actor>`, I want `<capability>`, so that `<benefit>`.
2. ...

## Implementation decisions

Decisions captured here so the decomposer (and downstream agents) don't re-litigate them. Include:

- Modules to be built / modified (by package or feature name — no file paths; those rot fast)
- Interface shapes (Zod schemas, TypeScript types, tRPC procedures) — describe in prose; inline only if a snippet encodes the decision more precisely than prose (e.g., a Zod schema, a discriminated union, a state machine)
- Architectural choices (DI factory shape, withSpan/withCapture wrapping, manifest entries, anchor placements)
- Schema changes (Payload collections, database migrations)
- Cross-feature interactions (event publish/consume pairs, realtime channels, audit emissions)
- Optional-core requirements (does this feature require `core-events`? `core-realtime`? `core-audit`?)

Do NOT include specific file paths or full code snippets — they go stale quickly. Prefer prose plus inline contracts (schemas, types) where they tighten the decision.

## Testing decisions

- What "good test" means for this feature (behavior through public interfaces, not implementation details)
- Which modules get repository contract suites (any new `IXRepository`)
- Which modules get use-case unit tests (every use case — that's a conformance rule)
- Integration / e2e coverage: which apps, which Playwright specs
- Prior art in the codebase: pointers to similar test patterns to mirror

## Open questions

- Q1: `<question>` — `<recommended answer>`
- Q2: ...

## Out of scope (deferred)

Things that are tempting to include but should be a separate PRD.

## Further notes

Anything else: stakeholders, related PRDs (`Builds on <prd-id>`, `Supersedes <prd-id>`), external references.
```

</prd-template>

## After writing

- Verify the file lives at `docs/work/prds/<slug>.prd.md`.
- Tell the user the path and remind them to review and flip `status: draft → approved` before running `pnpm work decompose`.
- If new domain terms were introduced or sharpened during synthesis, append them to `docs/glossary.md` (lazy-create if missing) — same rules as `grill-with-docs`.
