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:
+PM must always output the following sections.
-- `## Research Inputs` (optional when relevant)
+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 |

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

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?

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，要轉成對本產品有意義的需求判斷

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.
 
 </prd-template>
 
@@ -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