From 29a1f7cd04ab82d3de6d81bff18b9466139dcc2a Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Thu, 29 Oct 2026 10:08:42 +0900 Subject: [PATCH 1/4] Form requirement hearing questions only in the orchestrator requirement-analyzer returned its own user-facing questions, including exclusion questions, without the convergence criteria that keep unrequested capabilities out of the hearing. Scope Confirmation also listed every unresolved product, UX, or operational question, which is wider than the hearing's one question per field below `ready`. The analyzer now returns scope and cost evidence only, and User decisions follows Hearing Step 1. The requirement criteria define a build-relevant item, so preconditions satisfied outside the repository change enter the hearing only from the user's wording. The PRD completeness check no longer asks for every stakeholder perspective. Co-Authored-By: Claude Opus 5.5 --- agents/prd-creator.md | 1 - agents/requirement-analyzer.md | 14 +++++--------- dev-skills/skills/requirement-convergence/SKILL.md | 2 +- .../requirement-convergence/references/criteria.md | 2 ++ dev-workflows-frontend/agents/prd-creator.md | 1 - .../agents/requirement-analyzer.md | 14 +++++--------- .../skills/requirement-convergence/SKILL.md | 2 +- .../requirement-convergence/references/criteria.md | 2 ++ .../skills/subagents-orchestration-guide/SKILL.md | 6 +++--- dev-workflows-fullstack/agents/prd-creator.md | 1 - .../agents/requirement-analyzer.md | 14 +++++--------- .../skills/requirement-convergence/SKILL.md | 2 +- .../requirement-convergence/references/criteria.md | 2 ++ .../skills/subagents-orchestration-guide/SKILL.md | 6 +++--- dev-workflows/agents/prd-creator.md | 1 - dev-workflows/agents/requirement-analyzer.md | 14 +++++--------- .../skills/requirement-convergence/SKILL.md | 2 +- .../requirement-convergence/references/criteria.md | 2 ++ .../skills/subagents-orchestration-guide/SKILL.md | 6 +++--- skills/requirement-convergence/SKILL.md | 2 +- .../requirement-convergence/references/criteria.md | 2 ++ skills/subagents-orchestration-guide/SKILL.md | 6 +++--- 22 files changed, 47 insertions(+), 57 deletions(-) diff --git a/agents/prd-creator.md b/agents/prd-creator.md index 04010989..8b184668 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/agents/requirement-analyzer.md b/agents/requirement-analyzer.md index e2f325ec..cb86bff6 100644 --- a/agents/requirement-analyzer.md +++ b/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-skills/skills/requirement-convergence/SKILL.md b/dev-skills/skills/requirement-convergence/SKILL.md index defb3cf7..bd20961f 100644 --- a/dev-skills/skills/requirement-convergence/SKILL.md +++ b/dev-skills/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-skills/skills/requirement-convergence/references/criteria.md b/dev-skills/skills/requirement-convergence/references/criteria.md index 3e8d0727..625980f7 100644 --- a/dev-skills/skills/requirement-convergence/references/criteria.md +++ b/dev-skills/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index 04010989..8b184668 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/dev-workflows-frontend/agents/requirement-analyzer.md b/dev-workflows-frontend/agents/requirement-analyzer.md index e2f325ec..cb86bff6 100644 --- a/dev-workflows-frontend/agents/requirement-analyzer.md +++ b/dev-workflows-frontend/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md index defb3cf7..bd20961f 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-frontend/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md index 3e8d0727..625980f7 100644 --- a/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows-frontend/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 77c4b778..39b8972f 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index 04010989..8b184668 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/dev-workflows-fullstack/agents/requirement-analyzer.md b/dev-workflows-fullstack/agents/requirement-analyzer.md index e2f325ec..cb86bff6 100644 --- a/dev-workflows-fullstack/agents/requirement-analyzer.md +++ b/dev-workflows-fullstack/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md index defb3cf7..bd20961f 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md index 3e8d0727..625980f7 100644 --- a/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows-fullstack/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 77c4b778..39b8972f 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index 04010989..8b184668 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -122,7 +122,6 @@ PRDs focus solely on "what to build." Implementation phases and task decompositi - In reverse-engineer mode, preserve observed measures and distinguish unknown business goals; derive no new target from a template. ### 4. Completeness Check -- Include all stakeholder perspectives - Consider edge cases - Clarify constraints diff --git a/dev-workflows/agents/requirement-analyzer.md b/dev-workflows/agents/requirement-analyzer.md index e2f325ec..cb86bff6 100644 --- a/dev-workflows/agents/requirement-analyzer.md +++ b/dev-workflows/agents/requirement-analyzer.md @@ -28,9 +28,9 @@ Start from the product responsibility the outcome implies, then scan broadly and Inspect a located responsibility further only when leaving it unchanged can affect the outcome, requirement confirmation, relative cost, or the analysis target. Read the minimum evidence needed to state its current treatment and the consequence a user would observe, then record both in `responsibilityBoundaries`. Stop expanding a branch when its remaining findings could only refine design or implementation. -### 2. Form Cost and Question Evidence +### 2. Form Cost Evidence -Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown or question only when its answer can change the outcome, current requirements, exclusions, Structural Scale, or the analysis target, and the repository cannot resolve it. +Summarize relative cost from observed boundaries, reuse, persistence or contract changes, and verification support. Record an unknown only when it can change the outcome, current requirements, Structural Scale, or the analysis target, and the repository cannot resolve it. Return the evidence for orchestrator judgment. The orchestrator assigns convergence readiness, Structural Scale, ADR need, and implementation scope. @@ -55,11 +55,8 @@ Return exactly one JSON object: "drivers": [ {"kind": "observed|inferred", "fact": "structural cost fact", "source": "request or path"} ], - "unknowns": ["fact that can change relative cost"] - }, - "questions": [ - {"decision": "outcome|requirement|exclusion|scale|analysis_target", "question": "specific unresolved question", "effect": "what changes based on the answer"} - ] + "unknowns": ["fact the repository cannot resolve that can change cost, scope, or scale"] + } } ``` @@ -67,9 +64,8 @@ Return exactly one JSON object: - Scope and cost evidence is shallow, compact, and source-backed. - Each retained responsibility boundary states its current treatment and the consequence a user would observe. -- Every user-facing or operational responsibility a cost driver or question relies on has a source-backed boundary entry, or is recorded as an unknown. +- Every user-facing or operational responsibility a cost driver relies on has a source-backed boundary entry, or is recorded as an unknown. - `executionRoute.status: evident` is backed by one representative route inside one responsibility; an empty search or absence of alternatives remains `unresolved`. -- Every question names the decision its answer can change. - Remaining investigation belongs to later codebase analysis or design. - Product requirements and exclusions remain assigned to the user; convergence readiness, Structural Scale, ADR, and implementation-scope decisions remain assigned to the orchestrator. - The response is one valid JSON object. diff --git a/dev-workflows/skills/requirement-convergence/SKILL.md b/dev-workflows/skills/requirement-convergence/SKILL.md index defb3cf7..bd20961f 100644 --- a/dev-workflows/skills/requirement-convergence/SKILL.md +++ b/dev-workflows/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/dev-workflows/skills/requirement-convergence/references/criteria.md b/dev-workflows/skills/requirement-convergence/references/criteria.md index 3e8d0727..625980f7 100644 --- a/dev-workflows/skills/requirement-convergence/references/criteria.md +++ b/dev-workflows/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 77c4b778..39b8972f 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner diff --git a/skills/requirement-convergence/SKILL.md b/skills/requirement-convergence/SKILL.md index defb3cf7..bd20961f 100644 --- a/skills/requirement-convergence/SKILL.md +++ b/skills/requirement-convergence/SKILL.md @@ -51,7 +51,7 @@ Render this shape at every requirements confirmation stop, whether or not the he |---------|----------| | **Confirmed scope** | The requirements and exclusions the user has already selected, in the user's wording | | **Decision evidence** | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost | -| **User decisions** | Each unresolved product, UX, or operational question, followed by the scope, outcome, or cost effects of its materially different answers | +| **User decisions** | One question per convergence field below `ready` (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers | | **Workflow** | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route | Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own settled boundary, which is a repository observation, and which is still open. diff --git a/skills/requirement-convergence/references/criteria.md b/skills/requirement-convergence/references/criteria.md index 3e8d0727..625980f7 100644 --- a/skills/requirement-convergence/references/criteria.md +++ b/skills/requirement-convergence/references/criteria.md @@ -19,6 +19,8 @@ Evaluation requests, speculative ideas, and prescribed mechanisms stay in active Flattening current state, desired future, and candidates into one requirement list makes a bloated plan look coherent because every item then reads as equally required. Label each build-relevant item; ask when its current-state or desired-future role is unclear rather than inferring it. +An item is build-relevant when the repository change can satisfy it. A precondition held outside that change, such as legal or policy review, contract execution, release execution, or organizational approval, enters `requirements[]` and the hearing only when the user's wording raises it. + ## nonGoals[] Capabilities deliberately excluded from this change, authored by the user. diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 77c4b778..39b8972f 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -19,7 +19,7 @@ This section governs the orchestrator's Agent prompt. Each specialist's agent de ### First Action Rule -When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence, cost evidence, and questions against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. +When receiving a new full-cycle task, retain the user's complete wording in the orchestrator and invoke requirement-analyzer with the Requirement Evidence Handoff below. Compare its scope evidence and cost evidence against that retained wording to judge requirement convergence and Structural Scale in the orchestrator. Dedicated design recipes use their own codebase-scoped bootstrap. **Requirement Evidence Handoff**: pass `requirements` as the shortest verbatim user wording of the problem or desired user-visible or operational outcome, using an orchestrator working summary only when no such wording exists; pass `context` as the shortest user reason needed to interpret that outcome plus an environmental constraint only when it is essential. Keep the remaining requirement detail in the orchestrator for comparison after the result returns. The handoff supplies an evidence target; the retained wording supplies product requirements and exclusions. Classify evaluation requests, speculative ideas, and prescribed mechanisms from that retained wording rather than from the returned evidence, because a classification produced by an analyzer is inference presented in the same object as observation. @@ -27,7 +27,7 @@ Build and judge the `convergence` record in the orchestrator with the requiremen ### Small Evidence Gate -Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` or `questions` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. +Classify Small when `scopeEvidence.executionRoute.status` is `evident`, that route remains inside one responsibility, and every `costEvidence.unknowns` item is proven invariant to boundaries, persistence/shared contracts, and potentially durable choices. Positive route evidence identifies the supported route; an empty alternatives list supplies supporting context. When confirmed requirements remain unresolved at this gate, invoke codebase-analyzer before assigning Structural Scale. Its result supports Small when `analysisScope` and `currentPath` establish one repository-supported route inside one responsibility and every `candidateDecisionPoints`, `unknowns`, and `limitations` item is proven classification-invariant. Other observed boundaries and outcomes route Medium or Large. Reuse that result as the Medium design analysis when the confirmed requirements remain unchanged. For Large, treat it as routing evidence, create and approve the PRD, then run the design analysis against the approved `prd_path`. ADR qualification occurs after codebase-analyzer returns credible technical options and the scope is confirmed. ### Requirement Change Detection During Flow @@ -260,7 +260,7 @@ Before post-implementation verifiers, collect retained verification limitations ## Handoff Contracts ### HC-01: requirement-analyzer → orchestrator and codebase-analyzer -- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence`, `costEvidence`, and `questions` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or question arrays supply supporting context. +- Invoke with the Requirement Evidence Handoff. The orchestrator compares the returned `scopeEvidence` and `costEvidence` against its retained user wording to judge convergence and Structural Scale. Small requires the positive `scopeEvidence.executionRoute` gate above; named route evidence proves Small eligibility, while empty boundary or unknown arrays supply supporting context. - Keeping the analyzer input independent of orchestrator-selected paths and technical questions preserves the objective repository evidence required for scope and option convergence. ### HC-01b: convergence record → document owner From ba87abf45f7ff46d2e7f0945c797d14784cf5277 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Thu, 29 Oct 2026 10:25:06 +0900 Subject: [PATCH 2/4] Keep preconditions outside the repository change out of PRDs Later design, review, and test selection treat PRD content as governing, but nothing kept release execution, organizational approval, and similar preconditions out of it. prd-creator also searched for regulatory facts on its own, and the PRD template invited delivery and sequencing risks, which belong to work planning. The PRD definition now states the same boundary the Design Doc already has, unless the user's wording raises such a precondition. The WebSearch trigger no longer lists regulatory facts, and PRD risks are limited to product risks that can change scope, success criteria, or acceptance. Co-Authored-By: Claude Opus 5.5 --- agents/prd-creator.md | 2 +- dev-skills/skills/documentation-criteria/SKILL.md | 2 +- .../skills/documentation-criteria/references/prd-template.md | 2 +- dev-workflows-frontend/agents/prd-creator.md | 2 +- dev-workflows-frontend/skills/documentation-criteria/SKILL.md | 2 +- .../skills/documentation-criteria/references/prd-template.md | 2 +- dev-workflows-fullstack/agents/prd-creator.md | 2 +- dev-workflows-fullstack/skills/documentation-criteria/SKILL.md | 2 +- .../skills/documentation-criteria/references/prd-template.md | 2 +- dev-workflows/agents/prd-creator.md | 2 +- dev-workflows/skills/documentation-criteria/SKILL.md | 2 +- .../skills/documentation-criteria/references/prd-template.md | 2 +- skills/documentation-criteria/SKILL.md | 2 +- skills/documentation-criteria/references/prd-template.md | 2 +- 14 files changed, 14 insertions(+), 14 deletions(-) diff --git a/agents/prd-creator.md b/agents/prd-creator.md index 8b184668..dce033f7 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-skills/skills/documentation-criteria/SKILL.md b/dev-skills/skills/documentation-criteria/SKILL.md index 1e6f67ac..9e47c721 100644 --- a/dev-skills/skills/documentation-criteria/SKILL.md +++ b/dev-skills/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-skills/skills/documentation-criteria/references/prd-template.md b/dev-skills/skills/documentation-criteria/references/prd-template.md index 8d814d76..d0fea276 100644 --- a/dev-skills/skills/documentation-criteria/references/prd-template.md +++ b/dev-skills/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index 8b184668..dce033f7 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md index 1e6f67ac..9e47c721 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md index 8d814d76..d0fea276 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-frontend/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index 8b184668..dce033f7 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md index 1e6f67ac..9e47c721 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md index 8d814d76..d0fea276 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index 8b184668..dce033f7 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, regulatory, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-workflows/skills/documentation-criteria/SKILL.md b/dev-workflows/skills/documentation-criteria/SKILL.md index 1e6f67ac..9e47c721 100644 --- a/dev-workflows/skills/documentation-criteria/SKILL.md +++ b/dev-workflows/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-workflows/skills/documentation-criteria/references/prd-template.md b/dev-workflows/skills/documentation-criteria/references/prd-template.md index 8d814d76..d0fea276 100644 --- a/dev-workflows/skills/documentation-criteria/references/prd-template.md +++ b/dev-workflows/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| diff --git a/skills/documentation-criteria/SKILL.md b/skills/documentation-criteria/SKILL.md index 1e6f67ac..9e47c721 100644 --- a/skills/documentation-criteria/SKILL.md +++ b/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/skills/documentation-criteria/references/prd-template.md b/skills/documentation-criteria/references/prd-template.md index 8d814d76..d0fea276 100644 --- a/skills/documentation-criteria/references/prd-template.md +++ b/skills/documentation-criteria/references/prd-template.md @@ -124,7 +124,7 @@ State observable success for the confirmed outcome. Include only sourced quantit - [Prerequisite requiring validation 2] ### Risks and Mitigation -Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance. +Include only evidenced product risks that can change scope, success criteria, or acceptance. | Risk | Impact | Probability | Mitigation | |------|--------|-------------|------------| From c54a78b5519fbcc31938d3768a6cb7d124d35541 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Thu, 29 Oct 2026 10:35:30 +0900 Subject: [PATCH 3/4] Bump version to 0.29.4 Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 8 ++++---- dev-skills/.claude-plugin/plugin.json | 2 +- dev-workflows-frontend/.claude-plugin/plugin.json | 2 +- dev-workflows-fullstack/.claude-plugin/plugin.json | 2 +- dev-workflows/.claude-plugin/plugin.json | 2 +- package.json | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 91033802..cc34e4e8 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.29.3", + "version": "0.29.4", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -80,7 +80,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.29.3", + "version": "0.29.4", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -149,7 +149,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.29.3", + "version": "0.29.4", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -235,7 +235,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.29.3", + "version": "0.29.4", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", "author": { "name": "Shinsuke Kagawa", diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index a14d0cb7..8c200bcd 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/.claude-plugin/plugin.json b/dev-workflows-frontend/.claude-plugin/plugin.json index 9c92a738..3d20fd3b 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 2b74dd75..fae66181 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index c6de3cd8..d97f4d9d 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.3", + "version": "0.29.4", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/package.json b/package.json index 4eecb89f..febc010a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.3", + "version": "0.29.4", "private": true, "type": "module", "engines": { From 3d4a3cd9fd56996bab11479982908d2672532d13 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Thu, 29 Oct 2026 10:42:58 +0900 Subject: [PATCH 4/4] State PRD precondition and WebSearch rules in positive form Co-Authored-By: Claude Opus 5.5 --- agents/prd-creator.md | 2 +- dev-skills/skills/documentation-criteria/SKILL.md | 2 +- dev-workflows-frontend/agents/prd-creator.md | 2 +- dev-workflows-frontend/skills/documentation-criteria/SKILL.md | 2 +- dev-workflows-fullstack/agents/prd-creator.md | 2 +- dev-workflows-fullstack/skills/documentation-criteria/SKILL.md | 2 +- dev-workflows/agents/prd-creator.md | 2 +- dev-workflows/skills/documentation-criteria/SKILL.md | 2 +- skills/documentation-criteria/SKILL.md | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/agents/prd-creator.md b/agents/prd-creator.md index dce033f7..c3cdd488 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-skills/skills/documentation-criteria/SKILL.md b/dev-skills/skills/documentation-criteria/SKILL.md index 9e47c721..2565155c 100644 --- a/dev-skills/skills/documentation-criteria/SKILL.md +++ b/dev-skills/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index dce033f7..c3cdd488 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md index 9e47c721..2565155c 100644 --- a/dev-workflows-frontend/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-frontend/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index dce033f7..c3cdd488 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md index 9e47c721..2565155c 100644 --- a/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md +++ b/dev-workflows-fullstack/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index dce033f7..c3cdd488 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -21,7 +21,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow 3. Define success metrics 4. Clarify scope (what's included/excluded) 5. Verify consistency with existing systems -6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs do not already determine that decision. Record the authoritative source and the decision it affects +6. **Verify decision-changing external value evidence**: Use WebSearch when current market, competitor, or compatibility facts can change business value or MVP scope and the user, accepted contracts, usage evidence, and existing PRDs leave that decision open. Record the authoritative source and the decision it affects ## When PRD is Needed diff --git a/dev-workflows/skills/documentation-criteria/SKILL.md b/dev-workflows/skills/documentation-criteria/SKILL.md index 9e47c721..2565155c 100644 --- a/dev-workflows/skills/documentation-criteria/SKILL.md +++ b/dev-workflows/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. diff --git a/skills/documentation-criteria/SKILL.md b/skills/documentation-criteria/SKILL.md index 9e47c721..2565155c 100644 --- a/skills/documentation-criteria/SKILL.md +++ b/skills/documentation-criteria/SKILL.md @@ -11,7 +11,7 @@ This file holds the routing decision: which documents a change requires and wher Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed. -- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so release execution, organizational approval, and other preconditions held outside the repository change stay out of it unless the user's wording raises them. +- **PRD** — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it. - **ADR** — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it. `Accepted` records the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the confirmed outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan.