---
name: agf-writing-prd
description: Use when product-lead is about to draft a PRD for a new feature. Provides the 10-section PRD structure, AC quality bar, must-have fields, and the verification gate before sign-off. Replaces ad-hoc Read of docs/prd/_TEMPLATE.md.
---

# Writing a PRD (Product Requirements Document)

Use this skill when:

- product-lead has finished `superpowers:brainstorming` and the user has approved the rough direction
- Need to formalize a feature into `docs/prd/[feature]-[YYYY-MM-DD].md` before dispatching execution layer
- Updating an existing PRD after an open question is resolved

## Pre-conditions

- [ ] Feature direction approved (don't write a PRD for something still being explored — use `superpowers:brainstorming` first)
- [ ] You know who the user is and what business outcome you're optimizing
- [ ] At least 1 measurable success metric is identifiable (else: brainstorm more, the requirement is too vague)

If any precondition fails: **stop, do not write a PRD**. Either route back to brainstorming or SendMessage user for clarification.

## File path & naming

`docs/prd/[feature-kebab-case]-[YYYY-MM-DD].md` — e.g. `docs/prd/oauth-login-2026-05-12.md`.

One PRD per feature. Updates go to the same file with a `## Changelog` entry at the bottom; do NOT create a new dated file unless the scope materially changes (then archive old, link to new).

## Required sections (in order)

```markdown
# PRD — [Feature Name]

- **Date**: YYYY-MM-DD
- **Owner**: product-lead
- **Status**: Draft / Review / Approved / In Progress / Done / Archived
- **Estimated effort tier**: Small / Medium / Large（依据 `.claude/standards/cost-budget.md`）

## 1. Background

为什么做？解决的用户痛点 / 业务驱动；引用 Linear ticket / Slack 讨论 / 用户访谈。1–3 段。

## 2. Goal & Non-Goals

**目标**:
- 一句话目标声明
- KPI（上线后用什么数据判定成功）

**Non-Goals**: 明确不做什么，避免 scope creep。

## 3. User Stories

| ID | As a | I want to | So that |
|---|---|---|---|
| US-1 | ... | ... | ... |

## 4. Acceptance Criteria

每条 AC 必须**独立可验证**——code-reviewer / qa-engineer 会逐条核对。

| ID | Priority | AC | Verification method |
|---|---|---|---|
| AC-1 | P0 | 用户提交邮箱+密码 → POST /api/auth/login 返回 200 + JWT | curl + 验响应体 |
| AC-2 | P0 | 错误密码返回 401，不区分"邮箱不存在"vs"密码错"以防枚举 | 手动 / SIT |

**AC 质量条**：
- ❌ "登录功能正常工作" → 不可验证
- ✅ "POST /api/auth/login with valid creds → 200 + body 含 `{"token": "..."}` 字段" → 可验证

## 5. Design

- UI: 链接 `docs/design/[feature]/spec.md` + `index.html` 原型
- API 契约：列新增/变更接口签名（path, request, response, error code）
- 数据模型：列新增/变更表结构（字段、类型、索引）

## 6. Technical Constraints

- 必须遵守 `.claude/standards/coding.md`、`security.md`、`observability.md`
- LLM 集成：参考 skill `agf-wiring-multi-llm-sdk`
- 性能预算：API P95 ≤ 500ms / LLM P95 ≤ 5s（项目可调）
- 不引入新依赖（除非 tech-lead 已起 ADR）

## 7. Cost Estimate

- 预估 LLM token / 月：
- 预估 Agent Team 开发 token：
- 触发 cost-budget.md 哪一档？（Small / Medium / Large）

## 8. Out of Scope / Future Work

明确不在本次范围、留给后续迭代的工作项。

## 9. Open Questions

未确定的问题，分配给具体角色去搞清楚（明确写出由谁回答、何时回答）。

## 10. Sign-offs

- [ ] product-lead: 初稿
- [ ] tech-lead: 技术可行性（仅在涉及架构变更时）
- [ ] frontend-dev / backend-dev / ai-agent-dev: 实现可行性
- [ ] uiux-designer: 设计契合（仅在有 UI 时）
- [ ] qa-engineer: AC 可测性

## Changelog

- YYYY-MM-DD: 初稿
```

## AC 写作 5 条铁律

1. **每条 AC 独立可验证** — qa-engineer 不应该需要"先看其他 AC"才能测这一条
2. **优先级强制标注**（P0/P1/P2） — 用于 SIT/E2E 阶段决定 Block vs Conditional Pass
3. **用动词起头**（"用户点击 X 后...返回 Y"），不要用"应该" / "需要" 这种弱断言
4. **错误路径单独成条**，不要把"valid 时 200 / invalid 时 401"塞同一条
5. **不写实现细节** — AC 是"行为契约"，不是"代码方案"

## 反模式

- ❌ PRD 里写 SQL schema 字段长度（除非真的是业务约束，比如发票号 32 位）— 那是 design / dev 的细节
- ❌ AC = "性能良好" / "用户体验好" — 不可验证
- ❌ 不列 Non-Goals — scope 一定会蔓延
- ❌ 不写 Cost Estimate — 进 cost-budget 哪一档都不知道
- ❌ Open Questions 留空 + 无 owner — 等于没问

## 完成前的验证

写完 PRD 后，把它放在 `docs/prd/` 之前，**自检**：

- [ ] 每条 AC 都能被 qa-engineer 用一段话描述测试步骤吗？
- [ ] Non-Goals 列了至少 1 项？
- [ ] 至少 1 个 KPI 可以从现有 metrics 系统拿到？
- [ ] Open Questions 每条都有 owner？
- [ ] Cost Estimate 落到 cost-budget.md 的某一档了？

任何一条不行 → 不要发布，回去补。

## Hand-off

PRD 落盘后：

1. `TaskCreate` 建对应任务（按 product-lead Step 2 的 6 段 schema）
2. SendMessage 给相关执行层（frontend-dev / backend-dev / ai-agent-dev）："PRD 已就绪 [path]，请阅读 + 在初次 Plan Mode 报告里 cite AC 编号"
3. 如有 UI → SendMessage uiux-designer 起稿设计
