to-prd

name	to-prd
description	Turn already-clarified requirements, conversation context, plans, or codebase findings into a durable PRD on the configured issue tracker. Use when Codex needs to synthesize intent into a parent contract before slicing work, without reopening a full requirements interview.

To PRD

Synthesize what is already known into a PRD issue. Do not run a broad interview. Ask only for missing facts that would make the PRD misleading or impossible to slice.

Read docs/agents/issue-tracker.md, docs/agents/triage-labels.md, docs/agents/domain.md, and docs/agents/verification.md if they exist. If they are missing, run setup-workflow first or proceed with an explicit local fallback only when the user asks.

Process

1. Gather Inputs

Use the current conversation, linked docs, existing issues, PRs, codebase facts, prototypes, and user-confirmed decisions.

Prefer durable inputs over chat memory when they exist. If the user gives a title, link, branch, or "recent discussion", resolve it yourself.

2. Explore Enough Code

Explore the current codebase only as much as needed to avoid a fake plan:

• Existing public interfaces and user-visible behavior.
• Relevant domain vocabulary from CONTEXT.md or CONTEXT-MAP.md.
• ADRs that constrain the area.
• Similar tests or delivery patterns.
• Verification commands from docs/agents/verification.md.

Do not design all future modules upfront. Note likely seams and capabilities only where they help slicing and acceptance.

3. Confirm The Delivery Shape

Before publishing, summarize:

• Problem and intended outcome.
• Major capabilities the system must have.
• Likely acceptance strategy.
• Known regression risks.
• Out of scope.

Ask for confirmation only if the shape is materially ambiguous.

4. Publish The PRD

Publish the PRD to the configured issue tracker.

If the tracker supports labels and docs/agents/triage-labels.md defines category/state labels:

• Apply category enhancement.
• Apply state ready-for-agent unless the PRD still needs user information.
• Apply state needs-info when missing information prevents safe slicing.

If publishing to local markdown fallback, the PRD must start with this header:

Type: PRD
Status: ready-for-agent | needs-info
Parent: None
Linked PR / Branch / Commit: None

Use this template:

Type: PRD
Status: ready-for-agent | needs-info
Parent: None
Linked PR / Branch / Commit: None

## Problem Statement

The problem from the user's perspective.

## Solution

The intended solution from the user's perspective.

## Capability Summary

- Capability 1: the system ability needed, stated without over-designing modules.
- Capability 2: ...

## User Stories

1. As an <actor>, I want <feature>, so that <benefit>.

## Implementation Decisions

- User-confirmed technical decisions.
- Known integration points, contracts, schema/API constraints, or migration constraints.
- Testing seams that should guide slicing.

Avoid file paths and code snippets unless a prototype snippet encodes a decision more precisely than prose.

## Acceptance Strategy

- How the finished work will be accepted.
- Public interfaces, commands, CI checks, demos, or manual checks that prove the behavior.
- Evidence that must be attached to slice issues or PRs.

## Regression Risks

- Existing behavior that could be broken.
- Baseline tests, manual checks, or CI checks that should protect it.
- Unknowns that must be tracked as risks.

## Testing Decisions

- What makes a good test for this work.
- Existing test patterns to follow.
- Commands from `docs/agents/verification.md` that are likely relevant.

## Out of Scope

- Explicit non-goals.

## Further Notes

- Open questions, dependencies, rollout notes, or follow-up ideas.

5. Finish

Return the PRD link or local path, the applied triage state, and any remaining risks. Do not split issues in the same step unless the user explicitly asks.