to-prd

---
name: to-prd
description: "Synthesize conversation into PRD Forgejo issue. Use when 'create PRD from this conversation', 'spec to issue', 'productize this discussion', or after grill-with-docs (W4.5) elicitation."
mode: [engineering]
effort: medium
version: 1.0.0
tier: [admin]
attribution: "Cherry-picked from mattpocock/skills (MIT, see CREDITS.md)"
---

# To PRD — Conversation to Product Requirements Document

Synthesize the current conversation (or a referenced discussion) into a structured Product Requirements Document, then optionally publish it as a Forgejo issue using the `prd` template. Pairs upstream with `grill-with-docs` (W4.5 — fills gaps via documentation grilling) and downstream with `to-issues` (W6.5 — decomposes the PRD into vertical slices).

**Announce:** "Synthesizing conversation into PRD using to-prd..."

## When to invoke

- User says: "create a PRD from this conversation", "productize this discussion", "spec this out", "turn this into a Forgejo issue"
- After `grill-with-docs` produces a gap-filled discussion ready to formalize
- A brainstorm or design discussion needs to become a tracked deliverable
- Stakeholders ask for a written spec before engineering kicks off

## Anti-pattern: Premature decomposition

Do NOT skip straight to vertical slices (`to-issues`) from a raw conversation. PRDs exist to capture **intent, scope, and acceptance criteria** at the product level — once shared, they become the contract that slices must satisfy. Skipping the PRD step means slices encode tacit assumptions only the original participants remember.

If the conversation is trivial (single bugfix, isolated tweak), use `task-framing` to confirm complexity tier before invoking this skill. PRDs are for features and changes that affect more than one user-visible behavior.

## Workflow

1. **Gather context** — read the conversation, referenced documents, and any linked issues. If gaps exist (missing persona, undefined success metric, ambiguous scope), invoke `grill-with-docs` first or surface the gap to the user via AskUserQuestion.
2. **Extract** — pull the following from the discussion:
   - **Problem statement** — what hurts today, who hurts, how often
   - **Stakeholders** — primary user persona(s), secondary affected roles
   - **Acceptance criteria** — observable behaviors signaling "done"
   - **Scope** — what is in this PRD
   - **Non-goals** — what is explicitly out (prevent scope creep)
   - **Risks** — what could go wrong, mitigations considered
   - **Open questions** — unresolved decisions blocking implementation
   - **Success metrics** — how we measure that the PRD shipped well
3. **Format** — render as markdown using the PRD template (mirrors `.forgejo/ISSUE_TEMPLATE/prd.md`).
4. **HITL review** — print the rendered PRD and ask the user via AskUserQuestion: scope correct? Acceptance criteria observable? Anything missing from non-goals? Iterate until approved.
5. **Publish (optional)** — only after explicit user approval AND the `--create-in <repo>` flag is set, post the PRD as a Forgejo issue. Default behavior is `--dry-run` (print to stdout, no API call).

## CLI

```bash
# Default: synthesize and print the PRD to stdout (no side effect)
atlas to-prd --from-conversation

# Synthesize from a markdown file (e.g., a meeting transcript)
atlas to-prd --from-file path/to/discussion.md

# After HITL approval, publish to Forgejo
atlas to-prd --from-conversation --create-in axoiq/synapse

# Override the issue template (rare — defaults to prd)
atlas to-prd --from-conversation --create-in axoiq/synapse --template prd
```

`--dry-run` is the default. The `--create-in` flag is the only way to write to Forgejo. There is no `--auto-confirm` shortcut: HITL approval is mandatory before any API call.

## Workspace Mode (v8.1.0+)

When ATLAS workspace is detected (`~/.atlas/runtime/workspace.json` shows `workspace` non-null), this skill ALSO emits a `WI-YYYY-NNNN-prd-slug.md` to the workspace `backlog/_inbox/` with full attribution metadata.

This is a **DUAL WRITE** : Forgejo issue (existing) + workspace WI file (new).

### Process

1. Check if workspace state exists :
   ```bash
   if [ -f ~/.atlas/runtime/workspace.json ]; then
     WS_ROOT=$(python3 -c "import json; print(json.load(open('$HOME/.atlas/runtime/workspace.json'))['workspace']['root'])")
     USER=$(python3 -c "import json; print(json.load(open('$HOME/.atlas/runtime/workspace.json'))['user']['name'])")
   fi
   ```

2. Generate WI ID via `ops/next-id.py` :
   ```bash
   WI_ID=$($WS_ROOT/.venv/bin/python $WS_ROOT/ops/next-id.py)  # WI-2026-NNNN
   ```

3. Write to `backlog/_inbox/{WI_ID}-prd-{slug}.md` (write_auto capability — no HITL needed) :
   ```yaml
   ---
   id: WI-2026-NNNN
   type: epic                      # PRDs are epics
   status: backlog
   owner: unassigned
   product: synapse                # auto-detect from conversation
   priority: P2
   effort: XL                      # PRDs decompose later
   created: {ISO 8601}
   created_by: {workspace user}
   atlas_session_id: {ATLAS_SESSION_ID}
   labels: [prd, needs-decomposition]
   links:
     forgejo_issue: {url after Forgejo create}
   ---

   # PRD: {title}
   {full PRD body — Problem / Stakeholders / Acceptance criteria / etc.}
   ```

4. Cross-link Forgejo issue ↔ WI via `links.forgejo_issue` field.

5. Audit log : auto-written by `workspace-audit` hook.

### Backwards compatibility

- If workspace NOT detected : Forgejo-only behavior (existing)
- Plugin v7.16.1 / v8.0.0 : no behavior change

## PRD template (rendered output)

````markdown
# PRD: <Concise feature title>

## Problem

What hurts today, for whom, and how often. 2-4 sentences. Ground in observable user pain, not internal architecture concerns.

## Stakeholders

- **Primary user**: <persona> — what they need to be able to do
- **Secondary**: <role> — how this PRD affects them
- **Owner**: <team or person responsible for shipping>

## Acceptance criteria

- [ ] Observable behavior 1 (a user, system, or stakeholder can do X)
- [ ] Observable behavior 2
- [ ] Observable behavior 3

Each criterion must be checkable WITHOUT reading the implementation. Avoid "uses Redis" or "refactors X service" — those are implementation, not acceptance.

## Scope

What is included in this PRD. Bullet list of capabilities, screens, or workflows.

## Non-goals

What is explicitly out of scope. Prevents scope creep during implementation. Examples: "no mobile support in v1", "no bulk import", "no admin override workflow".

## Risks and mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Risk 1 | low/med/high | low/med/high | How we plan to handle it |

## Open questions

- [ ] Question blocking implementation start
- [ ] Question that can be deferred until slice N

## Success metrics

How we will know the PRD shipped well after launch. Quantitative when possible (latency, adoption %, error rate); qualitative as a fallback (user interview signals).

## Source

- Conversation: <session ID, date, or transcript link>
- Related issues: #N, #M
- Related docs: `.blueprint/path/to/relevant.md`
````

## HITL gate (non-negotiable)

Before any Forgejo API write:

1. Render the full PRD markdown to the user.
2. Ask via AskUserQuestion:
   - "Problem statement accurate?"
   - "Acceptance criteria observable and complete?"
   - "Non-goals capture what should stay out?"
   - "Anything to add to risks or open questions?"
3. Iterate until the user explicitly approves the rendered PRD.
4. Only then call the Forgejo API to create the issue.

Never publish silently. The HITL gate is the entire point of `--dry-run` being default.

## Forgejo API call (after approval)

```bash
curl -X POST "${FORGEJO_API}/repos/axoiq/synapse/issues" \
  -H "Authorization: token ${FORGEJO_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PRD: <feature title>",
    "body": "<rendered PRD markdown>",
    "labels": ["needs-triage", "prd"]
  }'
```

The Forgejo issue body uses the `prd` template at `.forgejo/ISSUE_TEMPLATE/prd.md` for repos that have it configured (web UI prefill); the API call here mirrors the same structure for programmatic creation. Reference: `.claude/references/forgejo-api.md`.

## Reuse and pairing

| Skill | Relationship |
|-------|--------------|
| `grill-with-docs` (W4.5 upstream) | Fills gaps in the conversation via documentation grilling BEFORE PRD synthesis |
| `to-issues` (W6.5 downstream) | Consumes the published PRD and decomposes it into vertical-slice Forgejo issues |
| `plan-builder` | Use AFTER PRD approval for the 15-section engineering plan (complementary; PRD captures product intent, plan captures execution architecture) |
| `task-framing` | Use BEFORE to-prd to confirm the work warrants a PRD (trivial tasks skip this) |
| `brainstorming` | Use BEFORE to-prd if the conversation has not yet converged on a single feature |

**Workflow chain**: `brainstorming` → `grill-with-docs` (W4.5) → `to-prd` (this skill) → `plan-builder` → `to-issues` (W6.5) → implementation per slice.

## Domain glossary respect

Use the project's vocabulary in the rendered PRD. The PRD becomes the contract that downstream issues reference, so terminology drift here propagates everywhere:

- Synapse: Part lifecycle (G→E→M→I→S), Engineering Chain (IMPORT→CLASSIFY→ENGINEER→...), MBSE 4-layer (QUOI/OÙ/COMMENT/QUI), Personas (I&C/EL/ME/...)
- AXOIQ: Programme PROG-003, G-gates (G0-G7), Cockpit, NeSy 72→97

When the conversation introduces ambiguous terms (e.g., "the dashboard" — which dashboard?), surface the ambiguity in **Open questions** rather than guessing.

## Counter-examples (rejected PRD patterns)

| Bad PRD shape | Why rejected | Fix |
|---|---|---|
| Acceptance criteria == implementation steps ("uses Postgres trigger") | Couples to internals, brittle | Restate as user-observable behavior |
| No non-goals section | Scope will creep during implementation | Always include, even if "no non-goals identified" |
| Single stakeholder = "the user" | Unclear which persona | Name the specific persona (I&C engineer, PM, admin) |
| Success metrics = "feature works" | Not measurable | Define a quantitative or qualitative signal |
| Open questions = empty | Almost always wrong; reflect honestly | List unresolved decisions, even small ones |
| Problem statement = solution-shaped ("we need a button to X") | Inverts problem and solution | Restate the underlying user pain |

If the synthesized PRD matches one of these patterns, iterate before presenting to the user.

## Pocock attribution

Adapted from `mattpocock/skills/engineering/to-prd` (MIT). Synapse-specific changes:

- Forgejo API instead of GitHub CLI for issue creation
- `.forgejo/ISSUE_TEMPLATE/prd.md` template alignment for web UI prefill
- Default `--dry-run` flag (HITL gate hardened beyond Pocock's quiz step)
- Explicit pairing with `grill-with-docs` (W4.5) upstream and `to-issues` (W6.5) downstream
- Domain glossary section (Synapse + AXOIQ vocabulary respect)
- Risks-and-mitigations table format (Synapse plan convention)

See `CREDITS.md` for full attribution chain.

## References

- Pocock origin: https://github.com/mattpocock/skills (engineering/to-prd)
- Forgejo API: `.claude/references/forgejo-api.md`
- Forgejo issue template: `.forgejo/ISSUE_TEMPLATE/prd.md`
- To-issues (downstream): `skills/to-issues/SKILL.md`
- Plan-builder: `skills/plan-builder/SKILL.md`
- Memory: `memory/lesson_cherrypick_distribute_vs_dedicated_wave.md`