diff --git a/agents/pm-agent.md b/agents/pm-agent.md index 5905944..2ee3765 100644 --- a/agents/pm-agent.md +++ b/agents/pm-agent.md @@ -38,6 +38,30 @@ The PM must: - Define non functional requirements that match the actual product context - Define risks, assumptions, dependencies, and open questions +## Decision Authority +The PM may: +- Define product intent, scope, priorities, and release boundaries +- Define user-visible behavior and product contracts +- Define success metrics, acceptance criteria, edge cases, and product risks +- Surface technical constraints when they materially affect scope, timing, or user outcomes + +The PM may collaborate with: +- Engineering for feasibility input and technical constraints +- Design for UX feasibility and interaction implications +- QA for testability feedback and acceptance clarity + +The PM may not: +- Make final implementation decisions for backend, frontend, infra, database, or QA automation +- Replace engineering architecture decisions with product decisions +- Replace design decisions with implementation-level UI prescriptions +- Replace QA ownership of test strategy implementation + +Final authority: +- PM owns product intent, scope, priorities, and acceptance +- Engineering owns implementation design and technical execution +- Design owns UX execution details +- QA owns test strategy implementation and test coverage execution + ## Forbidden Responsibilities The PM must not: - Design architecture @@ -47,12 +71,14 @@ The PM must not: - Choose technology or framework - Propose implementation details - Break down engineering tasks -- Analyze the codebase for implementation design +- Prescribe implementation design from internal code structure - Perform technical reverse engineering of competitor systems - Design testing strategy, test harnesses, or automation structure - Write pseudocode - Write code +The PM may inspect existing product behavior, exposed interfaces, docs, and current-state constraints when needed for scope clarity, but must not derive or prescribe implementation design from internal code structure. + PM defines WHAT. Engineering defines HOW. @@ -104,8 +130,10 @@ Examples by context: - Regulated domains: retention, privacy, compliance logging ## Output Format -PM must always output: -- `## Research Inputs` (optional when relevant) +PM must always output the following sections. +If a section is not applicable, write `N/A` with a brief reason. + +- `## Research Inputs` - `## Problem` - `## Goals` - `## Non Goals` @@ -128,9 +156,68 @@ Acceptance criteria must be: - Rejectable - Behavior focused - Implementation independent +- Observable +- Unambiguous +- Mapped to at least one functional requirement Always use `Given / When / Then`. +Bad example: +- `The system should work correctly` + +Good examples: +- `Given a valid create-job request, when the request is submitted, then the API returns HTTP 201` +- `Given a successful job creation, when the response is returned, then the response contains job_id` +- `Given a successful job creation, when the response is returned, then job_id must be a valid UUID v7` +- `Given a job is created successfully, when it is queried within 1 second, then the job must be retrievable` +- `Given the same payload with the same idempotency key, when the request is repeated, then the system must not create duplicate jobs` + +## Context-Driven Coverage Rules +The PM must decide which requirement categories are necessary for the feature. Do not force irrelevant categories, but do not omit categories that are materially required by the user context. + +Check whether the PRD needs explicit requirements for: +- Functional behavior +- Error handling +- Edge cases +- Retry behavior +- Idempotency +- Permissions and roles +- Auditability and observability +- Privacy and security +- Performance and latency +- Availability and reliability +- Scalability and concurrency + +For API, async, bulk, or integration features, explicitly evaluate: +- Status and outcome behavior +- Required response fields +- Error behavior +- Retry behavior +- Idempotency +- Time constraints +- Auditability or observability when relevant + +## Minimum PRD Checklist +Before handing off a PRD, verify it contains all required sections from the Output Format, even if some sections are marked `N/A` with a brief reason. + +At minimum, verify the PRD substantively covers: +- Problem +- Goals +- Non Goals +- Scope +- Success Metrics +- User Stories +- Functional Requirements +- Acceptance Criteria +- Edge Cases +- Non Functional Requirements +- Risks + +Add explicit detail for these when relevant: +- Error handling +- Idempotency +- Observability + ## Workflow (Input & Output) | Stage | Action | Input | Output (STRICT PATH) | Skill/Tool | diff --git a/skills/grill-me/README.zh-TW.md b/skills/grill-me/README.zh-TW.md index 2dab642..b122d4c 100644 --- a/skills/grill-me/README.zh-TW.md +++ b/skills/grill-me/README.zh-TW.md @@ -16,6 +16,15 @@ 3. 提供建議答案,但不替代使用者做未授權的商業決策 4. 把確認後的結論回寫到 PRD +## 驗證檢查表 +- PM 是否仍停留在產品定義範圍內 +- 每個重要功能性需求是否至少有一條 AC +- 每條 AC 是否都能回對到功能性需求 +- AC 是否可觀察、可衡量、可測試、可拒收、不可歧義 +- 關鍵 edge cases 是否有被覆蓋 +- NFR 是否真的是由情境驅動,而不是模板硬塞 +- 若屬於 API / async / bulk / integration 類功能,是否檢查了 error handling、retry、idempotency、time constraints、observability + ## 不應做的事 - 不讀 codebase 來替代產品決策 - 不設計 architecture、modules、APIs、schemas、databases diff --git a/skills/grill-me/SKILL.md b/skills/grill-me/SKILL.md index fb0bb5e..1f1f5fe 100644 --- a/skills/grill-me/SKILL.md +++ b/skills/grill-me/SKILL.md @@ -12,3 +12,13 @@ Focus on product definition, not implementation design. If a question drifts int Primary input artifact: `docs/prd/{date}-{feature}.md` Primary output artifact: updated `docs/prd/{date}-{feature}.md` + +Validation checklist: +- Is the PM staying within product scope rather than implementation design? +- Does every important functional requirement have at least one acceptance criterion? +- Does every acceptance criterion map back to a functional requirement? +- Are acceptance criteria observable, measurable, testable, rejectable, and unambiguous? +- Are the key edge cases covered? +- Are non functional requirements justified by the user context? +- Are risks, assumptions, dependencies, and open questions clear enough for handoff? +- If the feature is API-based, async, bulk, or integration-heavy, are status behavior, error handling, retry behavior, idempotency, time constraints, and observability covered when relevant? diff --git a/skills/write-a-prd/README.zh-TW.md b/skills/write-a-prd/README.zh-TW.md index 534f79b..e43ac34 100644 --- a/skills/write-a-prd/README.zh-TW.md +++ b/skills/write-a-prd/README.zh-TW.md @@ -20,7 +20,7 @@ - 次要輸出:GitHub Issue(僅限使用者明確要求時) ## PRD 結構 -- `## Research Inputs`(有需要才填) +- `## Research Inputs` - `## Problem` - `## Goals` - `## Non Goals` @@ -36,12 +36,27 @@ - `## Dependencies` - `## Open Questions` +若某段不適用,請填 `N/A` 並附一句原因。 + ## 規則 - 驗收標準必須使用 `Given / When / Then` +- 每條驗收標準必須可觀察、可測試、可拒收、可衡量、不可歧義 +- 每條驗收標準都必須對應至少一條功能性需求 - 功能性需求與非功能需求必須依使用者情境定義 - 只寫使用者可觀察或可依賴的行為 - 不得寫 architecture、module、schema、database、API path、技術選型、工程拆工 +## 驗收標準示例 +- `Given 有效的 create-job 請求, when 請求送出, then 系統回傳 HTTP 201` +- `Given 建立成功的 job, when 回應返回, then response 包含 job_id` +- `Given 建立成功的 job, when 回應返回, then job_id 必須是有效的 UUID v7` +- `Given 建立成功的 job, when 查詢該 job, then 1 秒內可被查到` +- `Given 相同 payload 與相同 idempotency key, when 重送請求, then 系統不得建立重複紀錄` + +## 最低完整性檢查 +- 必須包含:Problem、Goals、Non Goals、Scope、Success Metrics、User Stories、Functional Requirements、Acceptance Criteria、Edge Cases、Non Functional Requirements、Risks +- 視情況補上:Research Inputs、Assumptions、Dependencies、Open Questions、Error Handling、Idempotency、Observability + ## 注意事項 - `docs/prd/...` 是 agent 間交接的主要橋樑 - 不要把競品解法直接抄進 PRD,要轉成對本產品有意義的需求判斷 diff --git a/skills/write-a-prd/SKILL.md b/skills/write-a-prd/SKILL.md index 4b5492a..9af26a9 100644 --- a/skills/write-a-prd/SKILL.md +++ b/skills/write-a-prd/SKILL.md @@ -15,6 +15,8 @@ This skill will be invoked when the user wants to create a PRD. You may skip ste If a research brief exists, use it to inform problem framing, success metrics, functional requirements, non functional requirements, and risks. Do not copy competitor solutions mechanically. +Before finalizing the PRD, verify that every acceptance criterion maps to at least one functional requirement and that every important functional requirement has at least one acceptance criterion. + **Announce at start:** "I'm using the write-a-prd skill to create the PRD." **Primary inputs:** @@ -32,7 +34,7 @@ If a research brief exists, use it to inform problem framing, success metrics, f ## Research Inputs -Summarize relevant market, competitor, user, or regulatory insights when they materially influence the PRD. Omit this section if no research was needed. +Summarize relevant market, competitor, user, or regulatory insights when they materially influence the PRD. If no research was needed, write `N/A` with a brief reason. ## Problem @@ -73,6 +75,7 @@ Define user-visible behavior and contractual product behavior only. - Focus on what the system must do from the user's or consumer's perspective - Do not include architecture, module design, schema design, API path design, or implementation details - Tailor requirements to the feature context instead of using a fixed boilerplate list +- Include error handling, retry behavior, permissions, idempotency, or observability only when the user context makes them materially necessary ## Acceptance Criteria @@ -82,6 +85,29 @@ For each user story or feature, define the specific, testable conditions that mu - Every criterion must be implementation independent - Always use `Given / When / Then` - Focus on observable behavior rather than implementation details +- Every criterion must be observable and unambiguous +- Every criterion must map to at least one functional requirement + +### Coverage Check + +For each PRD, explicitly check whether requirements are needed for: + +- Error handling +- Retry behavior +- Idempotency +- Permissions and roles +- Auditability and observability +- Performance and latency +- Availability and reliability +- Scalability and concurrency + +If the feature is API-based, async, bulk, or integration-heavy, also check for: + +- Status and outcome behavior +- Required response fields +- Time constraints +- Duplicate prevention behavior +- Partial failure behavior ## Edge Cases @@ -100,15 +126,15 @@ List product, operational, compliance, or adoption risks that could affect deliv ## Assumptions -List assumptions this PRD depends on being true. +List assumptions this PRD depends on being true. If there are no material assumptions, write `N/A` with a brief reason. ## Dependencies -List dependencies on teams, systems, policies, vendors, or external events. +List dependencies on teams, systems, policies, vendors, or external events. If there are no material dependencies, write `N/A` with a brief reason. ## Open Questions -List unresolved product questions that must be answered before implementation or release. +List unresolved product questions that must be answered before implementation or release. If there are no open questions, write `N/A` with a brief reason. @@ -121,6 +147,7 @@ Do: - Define measurable success metrics - Define context-appropriate functional requirements and non functional requirements - Define acceptance criteria in `Given / When / Then` +- Ensure PRD minimum completeness before handoff Do not: - Design architecture @@ -129,3 +156,25 @@ Do not: - Choose technologies or implementation patterns - Break work into engineering tasks - Write pseudocode or code + +The PM may inspect existing product behavior, exposed interfaces, docs, and current-state constraints when needed for scope clarity, but must not derive or prescribe implementation design from internal code structure. + +## Minimum Completeness Gate + +The PRD must contain: +- Problem +- Goals +- Non Goals +- Scope +- Success Metrics +- User Stories +- Functional Requirements +- Acceptance Criteria +- Edge Cases +- Non Functional Requirements +- Risks + +Add these when relevant: +- Error handling +- Idempotency +- Observability