From 878a45109ddadef0a1dd49b0048fd7bed0dbd3b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=80=A7=E9=A9=8A?= Date: Fri, 10 Apr 2026 16:04:29 +0800 Subject: [PATCH 1/4] fix pm --- agents/pm-agent.md | 83 ++++++++++++++++++++++++++++++ skills/grill-me/README.zh-TW.md | 9 ++++ skills/grill-me/SKILL.md | 10 ++++ skills/write-a-prd/README.zh-TW.md | 6 +++ skills/write-a-prd/SKILL.md | 51 ++++++++++++++++++ 5 files changed, 159 insertions(+) diff --git a/agents/pm-agent.md b/agents/pm-agent.md index 5905944..0af2d83 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 @@ -128,9 +152,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 system returns a success response` +- `Given a successful job creation, when the response is returned, then it contains a job identifier` +- `Given a duplicate request under retry conditions, when the same request is repeated, then the system does not create a duplicate job` + +## 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: +- Problem +- Goals +- Non Goals +- Scope +- Success Metrics +- User Stories +- Functional Requirements +- Acceptance Criteria +- Edge Cases +- Non Functional Requirements +- Risks + +Strongly recommended when relevant: +- Research Inputs +- Assumptions +- Dependencies +- Open Questions +- 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..5fbf25d 100644 --- a/skills/write-a-prd/README.zh-TW.md +++ b/skills/write-a-prd/README.zh-TW.md @@ -38,10 +38,16 @@ ## 規則 - 驗收標準必須使用 `Given / When / Then` +- 每條驗收標準必須可觀察、可測試、可拒收、可衡量、不可歧義 +- 每條驗收標準都必須對應至少一條功能性需求 - 功能性需求與非功能需求必須依使用者情境定義 - 只寫使用者可觀察或可依賴的行為 - 不得寫 architecture、module、schema、database、API path、技術選型、工程拆工 +## 最低完整性檢查 +- 必須包含：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..f4751f8 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:** @@ -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 @@ -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,27 @@ Do not: - Choose technologies or implementation patterns - Break work into engineering tasks - Write pseudocode or code + +## 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: +- Research Inputs +- Assumptions +- Dependencies +- Open Questions +- Error handling +- Idempotency +- Observability -- 2.40.1 From 6fc1c557afd8e47f42ac7e052bb1270afa3d9c40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=80=A7=E9=A9=8A?= Date: Fri, 10 Apr 2026 16:08:37 +0800 Subject: [PATCH 2/4] fix pm --- agents/pm-agent.md | 12 ++++++++---- skills/write-a-prd/README.zh-TW.md | 7 +++++++ skills/write-a-prd/SKILL.md | 2 ++ 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/agents/pm-agent.md b/agents/pm-agent.md index 0af2d83..905525f 100644 --- a/agents/pm-agent.md +++ b/agents/pm-agent.md @@ -71,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 to keep requirements grounded, but must not derive or prescribe implementation design from internal code structure. + PM defines WHAT. Engineering defines HOW. @@ -162,9 +164,11 @@ Bad example: - `The system should work correctly` Good examples: -- `Given a valid create-job request, when the request is submitted, then the system returns a success response` -- `Given a successful job creation, when the response is returned, then it contains a job identifier` -- `Given a duplicate request under retry conditions, when the same request is repeated, then the system does not create a duplicate job` +- `Given a valid create-job request, when the request is submitted, then the system 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 is a valid UUID v7` +- `Given a successful job creation, when the job is queried, then it is queryable within 1 second` +- `Given the same payload and the same idempotency key, when the request is repeated, then the system does not create a duplicate record` ## 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. diff --git a/skills/write-a-prd/README.zh-TW.md b/skills/write-a-prd/README.zh-TW.md index 5fbf25d..e6698fd 100644 --- a/skills/write-a-prd/README.zh-TW.md +++ b/skills/write-a-prd/README.zh-TW.md @@ -44,6 +44,13 @@ - 只寫使用者可觀察或可依賴的行為 - 不得寫 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 diff --git a/skills/write-a-prd/SKILL.md b/skills/write-a-prd/SKILL.md index f4751f8..3049b4d 100644 --- a/skills/write-a-prd/SKILL.md +++ b/skills/write-a-prd/SKILL.md @@ -157,6 +157,8 @@ Do not: - Break work into engineering tasks - Write pseudocode or code +The PM may inspect existing product behavior, exposed interfaces, docs, and current-state constraints to keep requirements grounded, but must not derive or prescribe implementation design from internal code structure. + ## Minimum Completeness Gate The PRD must contain: -- 2.40.1 From 3bd83a68145e1a4d2e957fce51d36db4cc0046d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=80=A7=E9=A9=8A?= Date: Fri, 10 Apr 2026 16:13:53 +0800 Subject: [PATCH 3/4] fix pm --- agents/pm-agent.md | 22 ++++++++++------------ skills/write-a-prd/README.zh-TW.md | 4 +++- skills/write-a-prd/SKILL.md | 14 +++++--------- 3 files changed, 18 insertions(+), 22 deletions(-) diff --git a/agents/pm-agent.md b/agents/pm-agent.md index 905525f..b217b31 100644 --- a/agents/pm-agent.md +++ b/agents/pm-agent.md @@ -77,7 +77,7 @@ The PM must not: - Write pseudocode - Write code -The PM may inspect existing product behavior, exposed interfaces, docs, and current-state constraints to keep requirements grounded, but must not derive or prescribe implementation design from internal code structure. +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. @@ -130,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` @@ -164,11 +166,11 @@ Bad example: - `The system should work correctly` Good examples: -- `Given a valid create-job request, when the request is submitted, then the system 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 is a valid UUID v7` -- `Given a successful job creation, when the job is queried, then it is queryable within 1 second` -- `Given the same payload and the same idempotency key, when the request is repeated, then the system does not create a duplicate record` +- `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 it contains job_id` +- `Given a successful job creation, when job_id is returned, then it must be a valid UUID v7` +- `Given a job is created successfully, when it is queried within 1 second, then the job can be retrieved` +- `Given the same request payload is retried with the same idempotency key, when the request is repeated, then no duplicate job is created` ## 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. @@ -210,10 +212,6 @@ Before handing off a PRD, verify it contains: - Risks Strongly recommended when relevant: -- Research Inputs -- Assumptions -- Dependencies -- Open Questions - Error handling - Idempotency - Observability diff --git a/skills/write-a-prd/README.zh-TW.md b/skills/write-a-prd/README.zh-TW.md index e6698fd..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,6 +36,8 @@ - `## Dependencies` - `## Open Questions` +若某段不適用，請填 `N/A` 並附一句原因。 + ## 規則 - 驗收標準必須使用 `Given / When / Then` - 每條驗收標準必須可觀察、可測試、可拒收、可衡量、不可歧義 diff --git a/skills/write-a-prd/SKILL.md b/skills/write-a-prd/SKILL.md index 3049b4d..9af26a9 100644 --- a/skills/write-a-prd/SKILL.md +++ b/skills/write-a-prd/SKILL.md @@ -34,7 +34,7 @@ Before finalizing the PRD, verify that every acceptance criterion maps to at lea ## 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 @@ -126,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. @@ -157,7 +157,7 @@ Do not: - Break work into engineering tasks - Write pseudocode or code -The PM may inspect existing product behavior, exposed interfaces, docs, and current-state constraints to keep requirements grounded, but must not derive or prescribe implementation design from internal code structure. +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 @@ -175,10 +175,6 @@ The PRD must contain: - Risks Add these when relevant: -- Research Inputs -- Assumptions -- Dependencies -- Open Questions - Error handling - Idempotency - Observability -- 2.40.1 From dc7f865bf094777875eea3365b4c26b707016433 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=80=A7=E9=A9=8A?= Date: Fri, 10 Apr 2026 16:17:25 +0800 Subject: [PATCH 4/4] fix pm --- agents/pm-agent.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/agents/pm-agent.md b/agents/pm-agent.md index b217b31..2ee3765 100644 --- a/agents/pm-agent.md +++ b/agents/pm-agent.md @@ -167,10 +167,10 @@ Bad example: 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 it contains job_id` -- `Given a successful job creation, when job_id is returned, then it must be a valid UUID v7` -- `Given a job is created successfully, when it is queried within 1 second, then the job can be retrieved` -- `Given the same request payload is retried with the same idempotency key, when the request is repeated, then no duplicate job is created` +- `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. @@ -198,7 +198,9 @@ For API, async, bulk, or integration features, explicitly evaluate: - Auditability or observability when relevant ## Minimum PRD Checklist -Before handing off a PRD, verify it contains: +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 @@ -211,7 +213,7 @@ Before handing off a PRD, verify it contains: - Non Functional Requirements - Risks -Strongly recommended when relevant: +Add explicit detail for these when relevant: - Error handling - Idempotency - Observability -- 2.40.1