refine: back design-doc behavioral assumptions with evidence

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "dev-workflows",
       "source": "./dev-workflows",
       "strict": true,
-      "version": "0.22.2",
+      "version": "0.22.3",
       "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",
@@ -82,7 +82,7 @@
       "name": "dev-workflows-frontend",
       "source": "./dev-workflows-frontend",
       "strict": true,
-      "version": "0.22.2",
+      "version": "0.22.3",
       "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",
@@ -154,7 +154,7 @@
       "name": "dev-workflows-fullstack",
       "source": "./dev-workflows-fullstack",
       "strict": true,
-      "version": "0.22.2",
+      "version": "0.22.3",
       "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",
@@ -243,7 +243,7 @@
       "name": "dev-skills",
       "source": "./dev-skills",
       "strict": true,
-      "version": "0.22.2",
+      "version": "0.22.3",
       "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",

agents/document-reviewer.md

@@ -88,6 +88,7 @@ For WorkPlan, additionally verify:
 - Failure scenario review: Identify failure scenarios across normal usage, high load, and external failures; specify which design element becomes the bottleneck
 - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing
 - Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using Grep/Glob. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but definition signature (method names, parameter types, return types) diverges from Design Doc description → `important` issue (category: `consistency`)
+- **Behavioral claim evidence check**: Scan the Design Doc for behavioral or factual claims it relies on — framework/library default behavior, a capability assumed already provided, or a feature assumed already implemented; declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely scan starting points (a hint set, not exhaustive). For each such claim, verify the Agreement Checklist "Assumed Behaviors" slot records it with either attached evidence (codebase file:line, command result, or authoritative doc) and Confirmed: Yes, or Confirmed: No plus a matching Risks and Mitigation row (matched by the restated claim) naming how it will be verified or guarded. A relied-upon behavioral claim absent from the slot, Confirmed: Yes without attached evidence, or Confirmed: No with no matching Risks and Mitigation row → `important` issue (category: `feasibility`)
 - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue
 - **Data design completeness check**: When document contains data-storage keywords (database, persistence, storage, migration) or data-access keywords (repository, query, ORM, SQL) or data-schema keywords (table, schema, column) but lacks data design content (no schema references, no "Test Boundaries" section with data layer strategy, no data model documentation) → `important` issue (category: `completeness`). Note: generic terms like "model", "field", "record", "entity" alone are insufficient to trigger this check — require co-occurrence with at least one data-storage or data-access keyword
 - **Code verification integration**: When `code_verification` input is provided, each item in `undocumentedDataOperations` absent from the document → `important` issue (category: `completeness`). Each discrepancy from code verification with severity `critical` or `major` → incorporate as pre-verified evidence in the corresponding review check

agents/technical-designer-frontend.md

@@ -109,7 +109,12 @@ Fill the Design Doc's "External Resources Used" subsection (under Background and
    - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency"
    - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies
 
-5. **Include in Design Doc**
+5. **Behavioral Claim Verification**
+   - For each factual claim the design relies on about behavior or current state — framework/library default behavior ("the router preserves scroll by default", "the form library resets on unmount"), a capability assumed already provided ("the hook already debounces", "the context already exposes Z"), or a feature assumed already implemented ("already handled by the parent") — attach one evidence source at design time: a codebase reference (file:line from Grep/Read), an executed command result, or an authoritative doc/spec URL.
+   - Claim supported by evidence → record it in the Design Doc's Agreement Checklist "Assumed Behaviors" slot with the evidence and Confirmed: Yes.
+   - Claim without locatable evidence → record it in the same slot with Confirmed: No, and add a matching Risks and Mitigation row that restates the claim (the shared lookup key) and states how it will be resolved: verified during implementation by a named method (command, test, or code-inspection point), or guarded by a fallback. This binds the unverified assumption to a follow-up rather than letting it pass silently.
+
+6. **Include in Design Doc**
    - Always include investigation results in "## Existing Codebase Analysis" section
    - Clearly document similar component search results (found components or "none")
    - Include dependency existence verification results (verified existing / requires new creation)

agents/technical-designer.md

@@ -111,13 +111,18 @@ Fill the Design Doc's "External Resources Used" subsection (under Background and
    - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency"
    - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies
 
-5. **Include in Design Doc**
+5. **Behavioral Claim Verification**
+   - For each factual claim the design relies on about behavior or current state — framework/library default behavior ("X defaults to Y"), a capability assumed already provided ("the service already returns Z", "the endpoint already validates W"), or a feature assumed already implemented ("already handled upstream") — attach one evidence source at design time: a codebase reference (file:line from Grep/Read), an executed command result, or an authoritative doc/spec URL.
+   - Claim supported by evidence → record it in the Design Doc's Agreement Checklist "Assumed Behaviors" slot with the evidence and Confirmed: Yes.
+   - Claim without locatable evidence → record it in the same slot with Confirmed: No, and add a matching Risks and Mitigation row that restates the claim (the shared lookup key) and states how it will be resolved: verified during implementation by a named method (command, test, or code-inspection point), or guarded by a fallback. This binds the unverified assumption to a follow-up rather than letting it pass silently.
+
+6. **Include in Design Doc**
    - Always include investigation results in "## Existing Codebase Analysis" section
    - Clearly document similar functionality search results (found implementations or "none")
    - Include dependency existence verification results (verified existing / requires new creation)
    - Record adopted decision (use existing/improvement proposal/new implementation) and rationale
 
-6. **Code Inspection Evidence**
+7. **Code Inspection Evidence**
    - Record all inspected files and key functions in "Code Inspection Evidence" section of Design Doc
    - Each entry must state relevance (similar functionality / integration point / pattern reference)
 

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.22.2",
+  "version": "0.22.3",
   "author": {
     "name": "Shinsuke Kagawa",
     "url": "https://github.com/shinpr"

dev-skills/skills/documentation-criteria/references/design-template.md

@@ -60,6 +60,11 @@ Lists each external resource this feature depends on with its feature-specific i
 - [ ] [Standard/convention] `[explicit]` - Source: [config / rule file / documentation path]
 - [ ] [Observed pattern] `[implicit]` - Evidence: [file paths] - Confirmed: [Yes/No]
 
+#### Assumed Behaviors
+Behavioral or factual claims the design relies on (framework/library defaults, capabilities assumed already provided, features assumed already implemented). Each claim carries evidence with Confirmed: Yes, or Confirmed: No with a matching Risks and Mitigation row — one that restates the claim as its Risk (the shared lookup key) and names how it will be verified or guarded. Mark the subsection N/A when the design relies on no such claims.
+
+- [ ] [Claim — e.g., "framework X defaults to Y", "service already returns Z"] - Evidence: [file:line / command output / doc URL] - Confirmed: [Yes/No]
+
 #### Quality Assurance Mechanisms
 How quality is enforced in the change area. Each item is either adopted (will be enforced during implementation) or noted (observed but not adopted, with reason).
 

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.22.2",
+  "version": "0.22.3",
   "author": {
     "name": "Shinsuke Kagawa",
     "url": "https://github.com/shinpr"

dev-workflows-frontend/agents/document-reviewer.md

@@ -88,6 +88,7 @@ For WorkPlan, additionally verify:
 - Failure scenario review: Identify failure scenarios across normal usage, high load, and external failures; specify which design element becomes the bottleneck
 - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing
 - Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using Grep/Glob. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but definition signature (method names, parameter types, return types) diverges from Design Doc description → `important` issue (category: `consistency`)
+- **Behavioral claim evidence check**: Scan the Design Doc for behavioral or factual claims it relies on — framework/library default behavior, a capability assumed already provided, or a feature assumed already implemented; declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely scan starting points (a hint set, not exhaustive). For each such claim, verify the Agreement Checklist "Assumed Behaviors" slot records it with either attached evidence (codebase file:line, command result, or authoritative doc) and Confirmed: Yes, or Confirmed: No plus a matching Risks and Mitigation row (matched by the restated claim) naming how it will be verified or guarded. A relied-upon behavioral claim absent from the slot, Confirmed: Yes without attached evidence, or Confirmed: No with no matching Risks and Mitigation row → `important` issue (category: `feasibility`)
 - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue
 - **Data design completeness check**: When document contains data-storage keywords (database, persistence, storage, migration) or data-access keywords (repository, query, ORM, SQL) or data-schema keywords (table, schema, column) but lacks data design content (no schema references, no "Test Boundaries" section with data layer strategy, no data model documentation) → `important` issue (category: `completeness`). Note: generic terms like "model", "field", "record", "entity" alone are insufficient to trigger this check — require co-occurrence with at least one data-storage or data-access keyword
 - **Code verification integration**: When `code_verification` input is provided, each item in `undocumentedDataOperations` absent from the document → `important` issue (category: `completeness`). Each discrepancy from code verification with severity `critical` or `major` → incorporate as pre-verified evidence in the corresponding review check

dev-workflows-frontend/agents/technical-designer-frontend.md

@@ -109,7 +109,12 @@ Fill the Design Doc's "External Resources Used" subsection (under Background and
    - If found outside codebase (external API, separate repository, generated artifact): record the authoritative source and mark as "external dependency"
    - If not found anywhere: mark as "requires new creation" in the Design Doc and reflect in implementation order dependencies
 
-5. **Include in Design Doc**
+5. **Behavioral Claim Verification**
+   - For each factual claim the design relies on about behavior or current state — framework/library default behavior ("the router preserves scroll by default", "the form library resets on unmount"), a capability assumed already provided ("the hook already debounces", "the context already exposes Z"), or a feature assumed already implemented ("already handled by the parent") — attach one evidence source at design time: a codebase reference (file:line from Grep/Read), an executed command result, or an authoritative doc/spec URL.
+   - Claim supported by evidence → record it in the Design Doc's Agreement Checklist "Assumed Behaviors" slot with the evidence and Confirmed: Yes.
+   - Claim without locatable evidence → record it in the same slot with Confirmed: No, and add a matching Risks and Mitigation row that restates the claim (the shared lookup key) and states how it will be resolved: verified during implementation by a named method (command, test, or code-inspection point), or guarded by a fallback. This binds the unverified assumption to a follow-up rather than letting it pass silently.
+
+6. **Include in Design Doc**
    - Always include investigation results in "## Existing Codebase Analysis" section
    - Clearly document similar component search results (found components or "none")
    - Include dependency existence verification results (verified existing / requires new creation)

dev-workflows-frontend/skills/documentation-criteria/references/design-template.md

@@ -60,6 +60,11 @@ Lists each external resource this feature depends on with its feature-specific i
 - [ ] [Standard/convention] `[explicit]` - Source: [config / rule file / documentation path]
 - [ ] [Observed pattern] `[implicit]` - Evidence: [file paths] - Confirmed: [Yes/No]
 
+#### Assumed Behaviors
+Behavioral or factual claims the design relies on (framework/library defaults, capabilities assumed already provided, features assumed already implemented). Each claim carries evidence with Confirmed: Yes, or Confirmed: No with a matching Risks and Mitigation row — one that restates the claim as its Risk (the shared lookup key) and names how it will be verified or guarded. Mark the subsection N/A when the design relies on no such claims.
+
+- [ ] [Claim — e.g., "framework X defaults to Y", "service already returns Z"] - Evidence: [file:line / command output / doc URL] - Confirmed: [Yes/No]
+
 #### Quality Assurance Mechanisms
 How quality is enforced in the change area. Each item is either adopted (will be enforced during implementation) or noted (observed but not adopted, with reason).
 

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.22.2",
+  "version": "0.22.3",
   "author": {
     "name": "Shinsuke Kagawa",
     "url": "https://github.com/shinpr"

dev-workflows-fullstack/agents/document-reviewer.md

@@ -88,6 +88,7 @@ For WorkPlan, additionally verify:
 - Failure scenario review: Identify failure scenarios across normal usage, high load, and external failures; specify which design element becomes the bottleneck
 - Code inspection evidence review: Verify inspected files are relevant to design scope; flag if key related files are missing
 - Dependency realizability check: For each dependency the Design Doc's Existing Codebase Analysis section describes as "existing", verify its definition exists in the codebase using Grep/Glob. Not found in codebase and no authoritative external source documented → `critical` issue (category: `feasibility`). Found but definition signature (method names, parameter types, return types) diverges from Design Doc description → `important` issue (category: `consistency`)
+- **Behavioral claim evidence check**: Scan the Design Doc for behavioral or factual claims it relies on — framework/library default behavior, a capability assumed already provided, or a feature assumed already implemented; declarative phrasing such as "already", "by default", "defaults to", or "handled by" marks likely scan starting points (a hint set, not exhaustive). For each such claim, verify the Agreement Checklist "Assumed Behaviors" slot records it with either attached evidence (codebase file:line, command result, or authoritative doc) and Confirmed: Yes, or Confirmed: No plus a matching Risks and Mitigation row (matched by the restated claim) naming how it will be verified or guarded. A relied-upon behavioral claim absent from the slot, Confirmed: Yes without attached evidence, or Confirmed: No with no matching Risks and Mitigation row → `important` issue (category: `feasibility`)
 - **As-is implementation document review**: When code verification results are provided and the document describes existing implementation (not future requirements), verify that code-observable behaviors are stated as facts; speculative language about deterministic behavior → `important` issue
 - **Data design completeness check**: When document contains data-storage keywords (database, persistence, storage, migration) or data-access keywords (repository, query, ORM, SQL) or data-schema keywords (table, schema, column) but lacks data design content (no schema references, no "Test Boundaries" section with data layer strategy, no data model documentation) → `important` issue (category: `completeness`). Note: generic terms like "model", "field", "record", "entity" alone are insufficient to trigger this check — require co-occurrence with at least one data-storage or data-access keyword
 - **Code verification integration**: When `code_verification` input is provided, each item in `undocumentedDataOperations` absent from the document → `important` issue (category: `completeness`). Each discrepancy from code verification with severity `critical` or `major` → incorporate as pre-verified evidence in the corresponding review check