| name | pie-prd-author |
| description | Drafts or updates a PIE element PRD following the project conventions in docs/prds/README.md. Use when starting a new element that meets the PRD bar, or when a substantial change requires updating an existing PRD. |
| allowed-tools | Read, Write, Edit, Glob, Grep |
PIE PRD Author
Drafts or updates a PRD for a new element or substantial feature change.
When a PRD Is Required
From AGENTS.md (verbatim):
- New elements (net-new
@pie-element/* packages or substantial new interaction types).
- Non-trivial extensions of existing elements (anything that adds an authoring-visible config, a new mode, or a materially new delivery surface).
- Cross-cutting platform changes that touch model / session / event contracts across multiple elements (e.g. shared-stimulus container, parameterized items, event consistency work).
- Authoring-surface changes that shift how authors compose item content.
Does not require a PRD: bug fixes, refactors with no behaviour change, demo tweaks, docs / README changes, version bumps, dependency updates, or retroactive documentation of stable elements you are not actively changing.
Retroactive PRDs for existing elements: do not write them preemptively. Tests own behaviour; a PRD written after the fact drifts from the code and creates a second source of truth with no active reader. Exception: write a thin PRD for an existing element when you are about to touch it — capture only intent not derivable from the code (key non-goals, deliberate upstream divergences). One screen is enough.
Process
- Read
docs/prds/_template.md — this is the copy-paste starter.
- Read
docs/prds/venn-classification/PRD.md — canonical length and tone. Target that density.
- Read
CONTEXT.md, docs/prds/README.md, the relevant existing PRD if one exists, and nearby element examples. Use established repo terminology for model, session, mode, controller, and authoring concepts; do not invent synonyms.
- Identify the slug: element name or feature name in kebab-case. It becomes
docs/prds/<slug>/PRD.md.
- Check whether a PRD already exists at that path before creating a new one.
- Draft into
docs/prds/<slug>/PRD.md. Cover: Context, Goals, Non-goals, Proposed surface (Model, Session, Modes, Controller responsibilities, Authoring surface), Worked example, Accessibility, Open questions.
- Present the draft inline in the conversation and ask the user to confirm the status and content before writing to disk.
What to Cover
Model: list only the key fields with a one-line description each. No TypeScript interfaces — those live in code. 4–6 fields is the right depth.
Session: same discipline. At minimum cover the response shape and completed.
Modes: list which modes the element must handle (gather, view, evaluate, configure) and what each does.
Controller responsibilities: validate() rules (what it rejects and why), outcome() scoring policy, createCorrectResponseSession() invariant.
Authoring surface: what the author sees and can configure. Keep it behavioural, not visual-design-prescriptive.
Worked example: one concrete scenario — a real prompt, real tiles/choices, a submitted session as JSON, and the resulting score. This is the most valuable section for constraining implementation.
Accessibility: keyboard model, screen-reader annoucements, hit-target sizes, color-independence requirements. Be specific to this element's interaction type.
Open questions: only genuinely undecided items. When resolved, delete the bullet and inline the answer into the relevant section.
Length Discipline
Target: one screen (~60 lines of markdown). Red flags that indicate over-expansion:
- Full TypeScript interface definitions in the PRD body.
- Generic "Performance", "Security", or "Observability" sections with no element-specific content — omit them entirely.
- A dated "Decision log" section — inline rationale next to the Non-goal or field it applies to.
- Owner / date fields — git tracks these; do not add them.
- A "Resolved questions" section — resolved items are deleted and inlined.
Non-Goals Discipline
Every Non-goal that a reader might push back on must include a one-sentence inline reason. This is the section agents misread most often.
Example pattern:
- **No per-tile scoring weights.** All tiles score equally; weights add authoring complexity
with marginal pedagogical benefit for K-8 formative use.
Without the reason, an agent implementing the element may silently add weights because they seem obviously useful.
Status Rules
- New PRDs start as
Proposal.
- Transition to
Accepted only when the implementation contract is agreed (explicitly confirmed by the maintainer in conversation or PR review).
- Never add a
Shipped status — tests and release tags own that information.
- The optional
## Status log section records transitions only (Proposal → Accepted), not content edits. A fresh Proposal with no transitions does not need this section.
Facet Splitting Rule
The default is a single PRD.md covering all facets. Only split into delivery.md / authoring.md / print.md when a facet has outgrown approximately two screens of element-specific content. Model / Session / event shape always stays in PRD.md — never duplicate it into a facet file.
Tool Usage
- Read:
CONTEXT.md, docs/prds/README.md, docs/prds/_template.md, docs/prds/venn-classification/PRD.md, any existing PRD at the target path, and nearby element examples when terminology is unclear.
- Glob: find existing PRDs (
docs/prds/**/PRD.md) to check for prior art or a related element's surface.
- Grep: scan for terminology conflicts or existing usage of a proposed field name.
- Write / Edit: only after the user confirms the draft in conversation.
