Danijel Martinek
bae4b66fa4
Convention shift: epic folders + PRD filenames + frontmatter id
fields are now bare slugs. The created: timestamp (Phase 2) carries
the date; folder names don't repeat it. A future <task-id>-<slug>
shape (e.g. ClickUp) lands cleanly when that integration ships.
Renames (git mv preserves history):
- docs/work/2026-05-13-binder-wrap-helper/
-> docs/work/binder-wrap-helper/
- docs/work/2026-05-14-library-evaluation-policy/
-> docs/work/library-evaluation-policy/
- docs/work/2026-05-14-ci-security-and-supply-chain/
-> docs/work/ci-security-and-supply-chain/
- docs/work/prds/2026-05-13-binder-wrap-helper.prd.md
-> docs/work/prds/binder-wrap-helper.prd.md
- docs/work/prds/2026-05-13-coverage-architecture.prd.md
-> docs/work/prds/coverage-architecture.prd.md
- docs/work/prds/2026-05-14-library-evaluation-policy.prd.md
-> docs/work/prds/library-evaluation-policy.prd.md
- docs/work/prds/2026-05-14-ci-security-and-supply-chain.prd.md
-> docs/work/prds/ci-security-and-supply-chain.prd.md
Frontmatter updates inside the renamed files: epic id, epic prd,
story epic, PRD id, PRD builds-on all drop date prefixes.
System folder + state file move:
- New docs/work/_system/ holds framework-managed state.
- docs/work/_state.json -> docs/work/_system/_state.json.
- state-builder.mjs adds _system to SKIP_FOLDERS.
- cli.mjs + state-sync-guard.mjs + .husky/pre-commit point at the
new path.
template-reset-v1 epic deleted entirely (one-off cleanup epic from
the pre-date-convention era; status was already done).
Generator-template updates (so new artifacts ship in the right
shape):
- .sandcastle/decomposer.prompt.md emits bare-slug folder names +
ISO created: timestamp.
- .claude/skills/to-prd/SKILL.md template uses bare-slug filename +
bare-slug id field + ISO created: timestamp.
Doc reference updates: glossary, runbook, agent-first-workflow-
and-conformance, reviewer prompt, ADR-020, ADR-022, ADR-023 all
point at the new paths/slugs.
109 lines
5.6 KiB
Markdown
109 lines
5.6 KiB
Markdown
---
|
|
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`.
|