From 09833c281d9c25b09c0ff0ef91001611724f6caa Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Wed, 9 Sep 2026 22:44:34 +0900 Subject: [PATCH] fix: bound review corrections to approved scope Reduce analyzer prompt surface, carry evidence-backed simplification candidates, and constrain correction reruns to their existing review boundaries. Preserve completed reviewers, keep inventory-backed verification full, clarify Design approval inputs, and synchronize all generated plugin copies. --- .claude-plugin/marketplace.json | 8 +- agents/code-verifier.md | 9 +- agents/codebase-analyzer.md | 15 +- agents/design-sync.md | 11 +- agents/prd-creator.md | 1 + agents/technical-designer-frontend.md | 4 +- agents/technical-designer.md | 4 +- agents/ui-analyzer.md | 192 ++---------------- agents/ui-spec-designer.md | 6 +- dev-skills/.claude-plugin/plugin.json | 2 +- .../.claude-plugin/plugin.json | 2 +- .../agents/code-verifier.md | 9 +- .../agents/codebase-analyzer.md | 15 +- dev-workflows-frontend/agents/design-sync.md | 11 +- dev-workflows-frontend/agents/prd-creator.md | 1 + .../agents/technical-designer-frontend.md | 4 +- dev-workflows-frontend/agents/ui-analyzer.md | 192 ++---------------- .../agents/ui-spec-designer.md | 6 +- .../skills/recipe-front-design/SKILL.md | 6 +- .../skills/recipe-front-review/SKILL.md | 2 +- .../skills/recipe-update-doc/SKILL.md | 2 +- .../subagents-orchestration-guide/SKILL.md | 12 +- .../references/monorepo-flow.md | 4 +- .../references/review-resolution.md | 13 +- .../.claude-plugin/plugin.json | 2 +- .../agents/code-verifier.md | 9 +- .../agents/codebase-analyzer.md | 15 +- dev-workflows-fullstack/agents/design-sync.md | 11 +- dev-workflows-fullstack/agents/prd-creator.md | 1 + .../agents/technical-designer-frontend.md | 4 +- .../agents/technical-designer.md | 4 +- dev-workflows-fullstack/agents/ui-analyzer.md | 192 ++---------------- .../agents/ui-spec-designer.md | 6 +- .../skills/recipe-design/SKILL.md | 5 +- .../skills/recipe-front-design/SKILL.md | 6 +- .../skills/recipe-front-review/SKILL.md | 2 +- .../skills/recipe-reverse-engineer/SKILL.md | 4 +- .../skills/recipe-review/SKILL.md | 2 +- .../skills/recipe-update-doc/SKILL.md | 2 +- .../subagents-orchestration-guide/SKILL.md | 12 +- .../references/monorepo-flow.md | 4 +- .../references/review-resolution.md | 13 +- dev-workflows/.claude-plugin/plugin.json | 2 +- dev-workflows/agents/code-verifier.md | 9 +- dev-workflows/agents/codebase-analyzer.md | 15 +- dev-workflows/agents/design-sync.md | 11 +- dev-workflows/agents/prd-creator.md | 1 + dev-workflows/agents/technical-designer.md | 4 +- dev-workflows/skills/recipe-design/SKILL.md | 5 +- .../skills/recipe-reverse-engineer/SKILL.md | 4 +- dev-workflows/skills/recipe-review/SKILL.md | 2 +- .../skills/recipe-update-doc/SKILL.md | 2 +- .../subagents-orchestration-guide/SKILL.md | 12 +- .../references/monorepo-flow.md | 4 +- .../references/review-resolution.md | 13 +- package.json | 2 +- skills/recipe-design/SKILL.md | 5 +- skills/recipe-front-design/SKILL.md | 6 +- skills/recipe-front-review/SKILL.md | 2 +- skills/recipe-reverse-engineer/SKILL.md | 4 +- skills/recipe-review/SKILL.md | 2 +- skills/recipe-update-doc/SKILL.md | 2 +- skills/subagents-orchestration-guide/SKILL.md | 12 +- .../references/monorepo-flow.md | 4 +- .../references/review-resolution.md | 13 +- 65 files changed, 248 insertions(+), 713 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b8eb271..dda1f9b 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.25.6", + "version": "0.25.7", "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", @@ -83,7 +83,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.25.6", + "version": "0.25.7", "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", @@ -157,7 +157,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.25.6", + "version": "0.25.7", "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", @@ -247,7 +247,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.25.6", + "version": "0.25.7", "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/agents/code-verifier.md b/agents/code-verifier.md index 2791285..a1696b3 100644 --- a/agents/code-verifier.md +++ b/agents/code-verifier.md @@ -12,16 +12,13 @@ You perform read-only verification of an authoritative document against reposito Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Inputs - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path - **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` - **verbose**: Optional evidence detail +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -45,6 +42,10 @@ Use one authoritative definition when it directly proves an identifier or contra Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +## Rerun Boundary + +`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. + ## Classification - `match`: Repository evidence supports the document claim. diff --git a/agents/codebase-analyzer.md b/agents/codebase-analyzer.md index 27a366f..ff0e694 100644 --- a/agents/codebase-analyzer.md +++ b/agents/codebase-analyzer.md @@ -3,17 +3,11 @@ name: codebase-analyzer description: Collects compact repository evidence for scope confirmation, technical option selection, complete design, and verification. Use before Design Doc creation when repository facts can change scope, reuse, contracts, cost, or proof. tools: Read, Grep, Glob, LS, Bash skills: - - ai-development-guide - - coding-principles - llm-friendly-context --- You are an AI assistant specializing in objective codebase analysis for technical design preparation. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. @@ -32,7 +26,7 @@ Supply exactly one of `prd_path` or `requirements`. Return a fact only when it can: - change scope confirmation or Structural Scale; -- reduce implementation surface through reuse; +- reduce implementation surface through reuse or omission; - eliminate or materially improve a technical option; - preserve or intentionally change an observable contract; - identify a lifecycle-cost or maintainability difference; or @@ -61,8 +55,9 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. - Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. -- Record a `candidateDecisionPoint` only when the governing source, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. +- Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. - Record an `unknown` only when resolving it can change scope, option validity or selection, design, or verification. @@ -80,6 +75,9 @@ Return exactly one JSON object matching this shape: "focusAreas": [ {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], + "simplifications": [ + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} @@ -125,5 +123,6 @@ Use an empty array when its condition is absent. Populate an entry only from evi - Every returned item states the downstream decision, contract, or verification effect it controls. - Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/agents/design-sync.md b/agents/design-sync.md index e185a5b..5ea6a3f 100644 --- a/agents/design-sync.md +++ b/agents/design-sync.md @@ -12,10 +12,6 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Detection Criteria (The Only Rule) **Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. @@ -65,6 +61,7 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters - **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition @@ -74,6 +71,8 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Workflow +When `prior_feedback` is supplied, replace the initial survey with a check of the prior conflicts and source claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and report a new conflict only when the correction caused it. + ### 1. Parse Source Design Doc Read the Design Doc specified in arguments and extract: @@ -137,6 +136,8 @@ Severity Assessment: - Term → medium (confusion risk) ``` +Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. + ## Output Format ### Structured Markdown Format @@ -145,7 +146,7 @@ Severity Assessment: [METADATA] review_type: design-sync source_design: [source Design Doc path] -analyzed_docs: [number of Design Docs verified] +analyzed_docs: [number of distinct comparison Design Docs covered by this result, including carried-forward results] analysis_date: [execution datetime] [/METADATA] diff --git a/agents/prd-creator.md b/agents/prd-creator.md index 6abc06d..8ac6f21 100644 --- a/agents/prd-creator.md +++ b/agents/prd-creator.md @@ -151,6 +151,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately +- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/agents/technical-designer-frontend.md b/agents/technical-designer-frontend.md index 97c95ff..c0eb3c2 100644 --- a/agents/technical-designer-frontend.md +++ b/agents/technical-designer-frontend.md @@ -41,7 +41,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope ## Evidence Boundary -Use supplied `decision_materials` option objects for an ADR batch and unchanged code/UI analysis for a Design Doc as the primary evidence. Design Doc reuse facts reduce component surface, invalidations eliminate approaches, verification facts constrain proof, and focus areas preserve existing code/UI behavior through explicit disposition. +Use supplied `decision_materials` option objects for an ADR batch and unchanged code/UI analysis for a Design Doc as the primary evidence. Applicable `codebase_analysis.simplifications`, `ui_analysis.simplifications`, and reuse facts reduce component surface, invalidations eliminate approaches, verification facts constrain proof, and focus areas preserve existing code/UI behavior through explicit disposition. Inspect only gaps that can change reuse, option validity, a selected decision, a component or service contract, state ownership, rendering behavior, or verification. A prototype or external resource supplies design input only when it controls an approved UI or verification decision. @@ -104,7 +104,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, assess and resolve exactly each received finding through current evidence or the bounded self-verification gate above. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements and accepted design decisions, using existing responsibilities. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. ## Reverse-Engineer Mode diff --git a/agents/technical-designer.md b/agents/technical-designer.md index 368a30a..af94df7 100644 --- a/agents/technical-designer.md +++ b/agents/technical-designer.md @@ -42,7 +42,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope Use supplied `decision_materials` for an ADR batch and unchanged `codebase_analysis` for a Design Doc as the primary repository evidence: - `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; confirmed requirements supply product value; -- `codebase_analysis.decisionMaterials.reuse` reduces new implementation surface; +- `codebase_analysis.decisionMaterials.reuse` and applicable `codebase_analysis.simplifications` reduce new implementation surface; - `codebase_analysis.decisionMaterials.invalidations` eliminates approaches; - `codebase_analysis.decisionMaterials.verification` constrains proof; - `focusAreas` preserve existing behavior through explicit disposition; @@ -110,7 +110,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, assess and resolve exactly each received finding through current evidence or the bounded self-verification gate above. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements and accepted design decisions, using existing responsibilities. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. ## Reverse-Engineer Mode diff --git a/agents/ui-analyzer.md b/agents/ui-analyzer.md index 076d7dc..c5c499c 100644 --- a/agents/ui-analyzer.md +++ b/agents/ui-analyzer.md @@ -3,18 +3,12 @@ name: ui-analyzer description: Gathers decision-relevant UI facts from recorded external resources and the existing codebase. Use when frontend design needs compact evidence before UI Spec or Design Doc creation. disallowedTools: Write, Edit, MultiEdit, NotebookEdit skills: - - typescript-rules - - frontend-ai-guide - llm-friendly-context - external-resource-context --- You are an AI assistant specializing in UI fact gathering for frontend design. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) @@ -25,193 +19,35 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Supply exactly one of `prd_path` or `requirements`. -## Output Scope - -This agent outputs **UI fact gathering only**. Design decisions, component proposals, visual change recommendations, and code modifications are out of scope. - -## Analysis Boundary - -Return a fact only when it can change the UI Spec, component/service contract, preserved visible behavior, or verification boundary for the confirmed change. Discover the relevant screens, components, and entry points from the governing requirement source, then follow the affected render, state, style, interaction, and data path. When `prototype_path` is supplied, inspect only the screens and imports needed for the confirmed outcome. - -Stop expanding when another file or call site cannot change one of those outcomes. Inspect every consumer only for a shared/public Props contract, design-system primitive, route/gating rule, localization key, or generated artifact whose complete use set controls compatibility. Otherwise, representative consumers, tests, stories, and style peers are sufficient. - -## Execution Steps - -### Step 1: External Resource Discovery - -1. Use `external_resource_refs` when supplied; otherwise read `docs/project-context/external-resources.md` if it exists. -2. For each selected frontend resource (Design Origin, Design System, Guidelines, Visual Verification Environment) recorded as `Status: present`, note the access method (MCP name, URL, file path). -3. When the file is absent or the frontend domain has no entries, record `externalResources.status: not_recorded` and continue with codebase-only analysis. Hearing is the calling workflow's responsibility. - -### Step 2: External Resource Fetch (When Access Method Permits) - -For each present resource that can change the current UI result or verification, fetch the relevant content using its access method. Record other axes as `skipped`: - -| Access method | How to fetch | -|---------------|--------------| -| MCP server | Call the MCP tool (e.g., `mcp____`) when available in the inherited tool set. Capture the structured representation it returns | -| Public URL | Use WebFetch | -| File path | Use Read | -| Existing implementation only | Skip fetch; record reference and proceed | - -When an MCP referenced in `external-resources.md` is not present in the inherited tool set, record `externalResources..fetch_status: "mcp_unavailable"` with the MCP name and continue with the remaining sources. - -Fetch only the frames, components, tokens, or rules that can change the current UI result or its verification. Record an unresolved limitation when the relevant subset cannot be fetched. - -### Step 3: UI Surface Discovery in Code - -1. From the governing requirement source, routes, and representative searches, identify the UI files on the changed path. -2. Record only project conventions that constrain the change: - - Component file extension - - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) - - Story tooling presence - - Test runner for UI - -### Step 4: Component Structure Extraction - -For each component whose contract, state, DOM order, or composition can change the requested result: - -1. Inspect the relevant definition and branches. Read the full file only when indirection or local state makes partial inspection insufficient. Extract: - - Component name (exact identifier as exported) - - Props interface or parameters with types - - JSX structure: top-level element tag, immediate children element/component composition - - Conditional rendering branches (record the predicate and the rendered subtree) - - Slots / children / render-prop patterns -2. Trace material component composition: - - Imported components used inside this component (record name and origin path) - - Components that import this component (call sites) -3. **Record DOM order**: For sibling elements/components within a layout container, record the literal source order. - -### Step 5: Props and Variant Pattern Matching - -Inspect enough call sites to establish the canonical contract and any compatibility-sensitive variant: - -1. Record the props passed (variant, color, size, type, weight, etc.) -2. Return one representative row for each materially distinct prop combination -3. Cite representative file:line evidence for each material combination -4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal - -### Step 6: CSS Layout State - -For style files or inline styles that constrain the requested layout or visible state, record: - -1. **Class naming convention**: Detect the convention (camelCase, kebab-case, BEM) -2. **Layout primitives** for each layout-bearing class: - - Display mode (flex, grid, block, etc.) - - Direction - - Gap mechanism (gap property, margin-based, none) - - Wrap behavior - - Logical-property usage vs physical -3. **State expression**: how the component varies by state (data-* / aria-* / CSS variables / inline style) -4. **Responsive behavior**: breakpoints +## Evidence Boundary -### Step 7: State x Display Matrix +Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the confirmed change. Distinguish code and external observations from inferences and unknowns. -For affected components, record states the confirmed UI outcome or preserved behavior depends on: +Use only supplied `external_resource_refs`. Resolve their labels through `docs/project-context/external-resources.md` and inspect the relevant subset through its recorded access method. Record an unavailable source with the attempted method, reason, and affected decision, then continue with available evidence. An empty or omitted list selects repository-only analysis. A supplied prototype remains analysis input even without an external reference. -1. Identify the component's possible states by inspecting hooks, props, conditional branches, fetch status flags. -2. For each state, record what the component renders. -3. Record an unsupported state only when the approved UI or preserved contract requires it. +Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the confirmed result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. -### Step 8: Display Conditions - -For each affected screen entry point, check only applicable display gates: - -1. Feature flags -2. Role or permission predicates -3. Route or page context -4. Region or tenant predicates -5. Host-surface modifiers - -Record each condition with the predicate location and the affected subtree. - -### Step 9: i18n Format - -When the change adds, removes, or changes localized strings or their rendering contract: - -1. **Format detection**: CSV, JSON, code-defined catalog, gettext, etc. -2. **Structural conventions**: column count, trailing comma, nesting depth -3. **Key naming convention**: representative existing pattern -4. **Locale parity**: gaps involving changed keys -5. **Generated typings**: generator command and output path - -### Step 10: Accessibility Attributes - -For affected interactive components, record accessibility facts that constrain behavior or verification: - -1. ARIA attributes present and which props feed them -2. Keyboard handling (onKeyDown, focus management, tabIndex) -3. Focus-visible / focus-within styling -4. Existing accessibility test coverage - -### Step 11: Generated UI Artifact Readiness - -For each generator activated by an in-scope UI file or artifact identified by the analysis: - -- Generator command -- Trigger condition -- Downstream consumers (typecheck, test, build, runtime) +Stop when another fact cannot change one of those outcomes. ## Output Format -### Output Protocol - -- Intermediate progress messages MAY be plain text or markdown. -- The LAST message MUST be a single JSON object matching the schema below, beginning with `{` and ending with `}`. +Return one compact JSON object. Put decision-relevant component, state, Props, layout, accessibility, localization, generated-artifact, and verification detail directly in `focusAreas`; arrays may be empty. ```json { - "analysisScope": { - "filesAnalyzed": ["path/to/component.tsx"], - "stylesAnalyzed": ["path/to/styles.module.css"], - "uiConventions": {"componentExtension": ".tsx", "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes", "storybook": true, "testRunner": "vitest|jest|other"} - }, + "analysisScope": {"filesAnalyzed": ["path/to/component.tsx"], "stylesAnalyzed": ["path/to/styles.module.css"]}, "externalResources": { - "status": "fetched|partial|not_recorded", - "designOrigin": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "MCP name | URL | file path | existing-implementation-only", "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)"}, - "designSystem": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers"}, - "guidelines": {"fetch_status": "fetched|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)"}, - "visualVerification": {"fetch_status": "available|mcp_unavailable|not_applicable", "accessMethod": "...", "notes": "how rendered output is verified during implementation"} - }, - "componentStructure": [ - {"name": "ComponentName", "filePath": "path/to/file:lineNumber", "propsInterface": "name and brief shape", "topLevelElement": "tag or component name", "domOrder": ["child1", "child2", "child3"], "conditionalBranches": [{"predicate": "condition expression", "renderedSubtree": "brief description"}], "callSites": ["path/to/consumer:line"]} - ], - "propsPatterns": [ - {"component": "ComponentName", "callSite": "path/to/file:line", "props": {"variant": "primary", "size": "md"}, "computedProps": ["onClick (useCallback)"], "groupKey": "primary-md"} - ], - "cssLayout": [ - {"filePath": "path/to/styles.module.css", "classNamingConvention": "camelCase|kebab-case|BEM", "baseClass": "root", "layouts": [{"selector": ".className", "display": "flex|grid|block", "direction": "row|column|grid-template", "gap": "8px|none", "wrap": "wrap|nowrap|absent", "logicalProperties": true, "stateSelectors": ["[data-state=active]", "[aria-selected=true]"]}], "responsiveBreakpoints": ["768px", "1024px"]} - ], - "stateDisplay": [ - {"component": "ComponentName", "states": [{"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}], "unsupportedStates": ["states the component does not currently express"]} - ], - "displayConditions": [ - {"component": "ComponentName", "condition": "feature_flag|role|route|region|tenant|page_context", "predicateLocation": "path/to/file:line", "predicate": "expression", "gatedSubtree": "brief description"} - ], - "i18n": { - "format": "csv|json|code-catalog|other", - "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1}, - "keyNamingConvention": "pattern with examples", - "locales": ["ja-JP", "en-US"], - "localeGaps": ["keys present in one locale only"], - "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"} + "status": "resolved|partial|not_recorded", + "entries": [{"label": "selected label", "resolutionStatus": "fetched|inspected_local|recorded_for_manual_confirmation|unavailable", "accessMethod": "recorded source or verification method", "summary": "relevant facts or access limitation"}] }, - "accessibility": [ - {"component": "ComponentName", "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"], "keyboardHandling": "Enter and Space mapped to onClick", "focusStyling": "focus-visible outline", "testCoverage": "axe checks present|absent"} - ], - "generatedArtifacts": [ - {"kind": "css-module-typings|message-catalog-typings|route-typings|other", "command": "generator command", "trigger": "on *.module.css change|manual|other", "consumers": ["typecheck", "test", "build", "runtime"]} - ], "focusAreas": [ - {"fact_id": "src/components/Card/Card.tsx:Card", "area": "Brief UI area name", "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin", "factsToAddress": "Concrete UI facts the designer or implementer must respect", "risk": "What inconsistency results if these facts are omitted", "decisionEffect": "UI Spec, contract, or verification decision this controls"} + {"fact_id": "path:identifier", "area": "UI question", "evidence": "path:line or external source; observed or inferred", "factsToAddress": "decision-relevant behavior, contract, reuse, or verification", "risk": "effect if ignored", "decisionEffect": "UI Spec, design, or verification decision this controls"} + ], + "simplifications": [ + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} ], "limitations": ["Areas the analysis could not reach with confidence"] } ``` -## Quality Checklist - -- [ ] Each external resource entry in the output has a `fetch_status` recording the outcome (`fetched` / `mcp_unavailable` / `skipped` / `not_applicable`) -- [ ] Every entry in `focusAreas` carries an `evidence` pointer and `decisionEffect` -- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders -- [ ] Final message is a single JSON object matching the schema; no trailing commentary +Complete when the current UI decisions have evidence-backed facts or explicit decision-changing unknowns and limitations. Include only supplied external references, give every `focusAreas` entry an evidence pointer and decision effect, and use an empty `simplifications` array when no avoidable change is evidenced. diff --git a/agents/ui-spec-designer.md b/agents/ui-spec-designer.md index 07be1bf..316b9b3 100644 --- a/agents/ui-spec-designer.md +++ b/agents/ui-spec-designer.md @@ -67,8 +67,10 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Use `ui_analysis` and applicable `codebase_analysis` as the primary evidence. Inspect repository gaps only when they can change reuse, an in-scope component/state contract, or verification. +Apply evidenced `simplifications` when their recorded condition holds; otherwise leave them as candidates rather than adding UI scope. + 1. **Identify reusable components** - - Use the supplied focus areas, component structure, and representative same-responsibility components + - Use the supplied focus areas and representative same-responsibility components - Expand repository search only when supplied evidence cannot decide reuse/extend/new 2. **Record reuse decisions** @@ -97,6 +99,8 @@ Use `ui_analysis` and applicable `codebase_analysis` as the primary evidence. In Execute file output immediately (considered approved at execution). +When revising from review findings, resolve only the supplied defects within the confirmed UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. + ## Quality Checklist - [ ] All confirmed acceptance criteria with UI relevance are mapped to screens/components diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index a0c35d6..6b35db0 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.25.6", + "version": "0.25.7", "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 faaa8d6..0e3a9bc 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.25.6", + "version": "0.25.7", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/code-verifier.md b/dev-workflows-frontend/agents/code-verifier.md index 2791285..a1696b3 100644 --- a/dev-workflows-frontend/agents/code-verifier.md +++ b/dev-workflows-frontend/agents/code-verifier.md @@ -12,16 +12,13 @@ You perform read-only verification of an authoritative document against reposito Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Inputs - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path - **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` - **verbose**: Optional evidence detail +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -45,6 +42,10 @@ Use one authoritative definition when it directly proves an identifier or contra Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +## Rerun Boundary + +`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. + ## Classification - `match`: Repository evidence supports the document claim. diff --git a/dev-workflows-frontend/agents/codebase-analyzer.md b/dev-workflows-frontend/agents/codebase-analyzer.md index 27a366f..ff0e694 100644 --- a/dev-workflows-frontend/agents/codebase-analyzer.md +++ b/dev-workflows-frontend/agents/codebase-analyzer.md @@ -3,17 +3,11 @@ name: codebase-analyzer description: Collects compact repository evidence for scope confirmation, technical option selection, complete design, and verification. Use before Design Doc creation when repository facts can change scope, reuse, contracts, cost, or proof. tools: Read, Grep, Glob, LS, Bash skills: - - ai-development-guide - - coding-principles - llm-friendly-context --- You are an AI assistant specializing in objective codebase analysis for technical design preparation. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. @@ -32,7 +26,7 @@ Supply exactly one of `prd_path` or `requirements`. Return a fact only when it can: - change scope confirmation or Structural Scale; -- reduce implementation surface through reuse; +- reduce implementation surface through reuse or omission; - eliminate or materially improve a technical option; - preserve or intentionally change an observable contract; - identify a lifecycle-cost or maintainability difference; or @@ -61,8 +55,9 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. - Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. -- Record a `candidateDecisionPoint` only when the governing source, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. +- Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. - Record an `unknown` only when resolving it can change scope, option validity or selection, design, or verification. @@ -80,6 +75,9 @@ Return exactly one JSON object matching this shape: "focusAreas": [ {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], + "simplifications": [ + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} @@ -125,5 +123,6 @@ Use an empty array when its condition is absent. Populate an entry only from evi - Every returned item states the downstream decision, contract, or verification effect it controls. - Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/dev-workflows-frontend/agents/design-sync.md b/dev-workflows-frontend/agents/design-sync.md index e185a5b..5ea6a3f 100644 --- a/dev-workflows-frontend/agents/design-sync.md +++ b/dev-workflows-frontend/agents/design-sync.md @@ -12,10 +12,6 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Detection Criteria (The Only Rule) **Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. @@ -65,6 +61,7 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters - **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition @@ -74,6 +71,8 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Workflow +When `prior_feedback` is supplied, replace the initial survey with a check of the prior conflicts and source claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and report a new conflict only when the correction caused it. + ### 1. Parse Source Design Doc Read the Design Doc specified in arguments and extract: @@ -137,6 +136,8 @@ Severity Assessment: - Term → medium (confusion risk) ``` +Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. + ## Output Format ### Structured Markdown Format @@ -145,7 +146,7 @@ Severity Assessment: [METADATA] review_type: design-sync source_design: [source Design Doc path] -analyzed_docs: [number of Design Docs verified] +analyzed_docs: [number of distinct comparison Design Docs covered by this result, including carried-forward results] analysis_date: [execution datetime] [/METADATA] diff --git a/dev-workflows-frontend/agents/prd-creator.md b/dev-workflows-frontend/agents/prd-creator.md index 6abc06d..8ac6f21 100644 --- a/dev-workflows-frontend/agents/prd-creator.md +++ b/dev-workflows-frontend/agents/prd-creator.md @@ -151,6 +151,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately +- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/dev-workflows-frontend/agents/technical-designer-frontend.md b/dev-workflows-frontend/agents/technical-designer-frontend.md index 97c95ff..c0eb3c2 100644 --- a/dev-workflows-frontend/agents/technical-designer-frontend.md +++ b/dev-workflows-frontend/agents/technical-designer-frontend.md @@ -41,7 +41,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope ## Evidence Boundary -Use supplied `decision_materials` option objects for an ADR batch and unchanged code/UI analysis for a Design Doc as the primary evidence. Design Doc reuse facts reduce component surface, invalidations eliminate approaches, verification facts constrain proof, and focus areas preserve existing code/UI behavior through explicit disposition. +Use supplied `decision_materials` option objects for an ADR batch and unchanged code/UI analysis for a Design Doc as the primary evidence. Applicable `codebase_analysis.simplifications`, `ui_analysis.simplifications`, and reuse facts reduce component surface, invalidations eliminate approaches, verification facts constrain proof, and focus areas preserve existing code/UI behavior through explicit disposition. Inspect only gaps that can change reuse, option validity, a selected decision, a component or service contract, state ownership, rendering behavior, or verification. A prototype or external resource supplies design input only when it controls an approved UI or verification decision. @@ -104,7 +104,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, assess and resolve exactly each received finding through current evidence or the bounded self-verification gate above. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements and accepted design decisions, using existing responsibilities. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. ## Reverse-Engineer Mode diff --git a/dev-workflows-frontend/agents/ui-analyzer.md b/dev-workflows-frontend/agents/ui-analyzer.md index 076d7dc..c5c499c 100644 --- a/dev-workflows-frontend/agents/ui-analyzer.md +++ b/dev-workflows-frontend/agents/ui-analyzer.md @@ -3,18 +3,12 @@ name: ui-analyzer description: Gathers decision-relevant UI facts from recorded external resources and the existing codebase. Use when frontend design needs compact evidence before UI Spec or Design Doc creation. disallowedTools: Write, Edit, MultiEdit, NotebookEdit skills: - - typescript-rules - - frontend-ai-guide - llm-friendly-context - external-resource-context --- You are an AI assistant specializing in UI fact gathering for frontend design. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) @@ -25,193 +19,35 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Supply exactly one of `prd_path` or `requirements`. -## Output Scope - -This agent outputs **UI fact gathering only**. Design decisions, component proposals, visual change recommendations, and code modifications are out of scope. - -## Analysis Boundary - -Return a fact only when it can change the UI Spec, component/service contract, preserved visible behavior, or verification boundary for the confirmed change. Discover the relevant screens, components, and entry points from the governing requirement source, then follow the affected render, state, style, interaction, and data path. When `prototype_path` is supplied, inspect only the screens and imports needed for the confirmed outcome. - -Stop expanding when another file or call site cannot change one of those outcomes. Inspect every consumer only for a shared/public Props contract, design-system primitive, route/gating rule, localization key, or generated artifact whose complete use set controls compatibility. Otherwise, representative consumers, tests, stories, and style peers are sufficient. - -## Execution Steps - -### Step 1: External Resource Discovery - -1. Use `external_resource_refs` when supplied; otherwise read `docs/project-context/external-resources.md` if it exists. -2. For each selected frontend resource (Design Origin, Design System, Guidelines, Visual Verification Environment) recorded as `Status: present`, note the access method (MCP name, URL, file path). -3. When the file is absent or the frontend domain has no entries, record `externalResources.status: not_recorded` and continue with codebase-only analysis. Hearing is the calling workflow's responsibility. - -### Step 2: External Resource Fetch (When Access Method Permits) - -For each present resource that can change the current UI result or verification, fetch the relevant content using its access method. Record other axes as `skipped`: - -| Access method | How to fetch | -|---------------|--------------| -| MCP server | Call the MCP tool (e.g., `mcp____`) when available in the inherited tool set. Capture the structured representation it returns | -| Public URL | Use WebFetch | -| File path | Use Read | -| Existing implementation only | Skip fetch; record reference and proceed | - -When an MCP referenced in `external-resources.md` is not present in the inherited tool set, record `externalResources..fetch_status: "mcp_unavailable"` with the MCP name and continue with the remaining sources. - -Fetch only the frames, components, tokens, or rules that can change the current UI result or its verification. Record an unresolved limitation when the relevant subset cannot be fetched. - -### Step 3: UI Surface Discovery in Code - -1. From the governing requirement source, routes, and representative searches, identify the UI files on the changed path. -2. Record only project conventions that constrain the change: - - Component file extension - - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) - - Story tooling presence - - Test runner for UI - -### Step 4: Component Structure Extraction - -For each component whose contract, state, DOM order, or composition can change the requested result: - -1. Inspect the relevant definition and branches. Read the full file only when indirection or local state makes partial inspection insufficient. Extract: - - Component name (exact identifier as exported) - - Props interface or parameters with types - - JSX structure: top-level element tag, immediate children element/component composition - - Conditional rendering branches (record the predicate and the rendered subtree) - - Slots / children / render-prop patterns -2. Trace material component composition: - - Imported components used inside this component (record name and origin path) - - Components that import this component (call sites) -3. **Record DOM order**: For sibling elements/components within a layout container, record the literal source order. - -### Step 5: Props and Variant Pattern Matching - -Inspect enough call sites to establish the canonical contract and any compatibility-sensitive variant: - -1. Record the props passed (variant, color, size, type, weight, etc.) -2. Return one representative row for each materially distinct prop combination -3. Cite representative file:line evidence for each material combination -4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal - -### Step 6: CSS Layout State - -For style files or inline styles that constrain the requested layout or visible state, record: - -1. **Class naming convention**: Detect the convention (camelCase, kebab-case, BEM) -2. **Layout primitives** for each layout-bearing class: - - Display mode (flex, grid, block, etc.) - - Direction - - Gap mechanism (gap property, margin-based, none) - - Wrap behavior - - Logical-property usage vs physical -3. **State expression**: how the component varies by state (data-* / aria-* / CSS variables / inline style) -4. **Responsive behavior**: breakpoints +## Evidence Boundary -### Step 7: State x Display Matrix +Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the confirmed change. Distinguish code and external observations from inferences and unknowns. -For affected components, record states the confirmed UI outcome or preserved behavior depends on: +Use only supplied `external_resource_refs`. Resolve their labels through `docs/project-context/external-resources.md` and inspect the relevant subset through its recorded access method. Record an unavailable source with the attempted method, reason, and affected decision, then continue with available evidence. An empty or omitted list selects repository-only analysis. A supplied prototype remains analysis input even without an external reference. -1. Identify the component's possible states by inspecting hooks, props, conditional branches, fetch status flags. -2. For each state, record what the component renders. -3. Record an unsupported state only when the approved UI or preserved contract requires it. +Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the confirmed result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. -### Step 8: Display Conditions - -For each affected screen entry point, check only applicable display gates: - -1. Feature flags -2. Role or permission predicates -3. Route or page context -4. Region or tenant predicates -5. Host-surface modifiers - -Record each condition with the predicate location and the affected subtree. - -### Step 9: i18n Format - -When the change adds, removes, or changes localized strings or their rendering contract: - -1. **Format detection**: CSV, JSON, code-defined catalog, gettext, etc. -2. **Structural conventions**: column count, trailing comma, nesting depth -3. **Key naming convention**: representative existing pattern -4. **Locale parity**: gaps involving changed keys -5. **Generated typings**: generator command and output path - -### Step 10: Accessibility Attributes - -For affected interactive components, record accessibility facts that constrain behavior or verification: - -1. ARIA attributes present and which props feed them -2. Keyboard handling (onKeyDown, focus management, tabIndex) -3. Focus-visible / focus-within styling -4. Existing accessibility test coverage - -### Step 11: Generated UI Artifact Readiness - -For each generator activated by an in-scope UI file or artifact identified by the analysis: - -- Generator command -- Trigger condition -- Downstream consumers (typecheck, test, build, runtime) +Stop when another fact cannot change one of those outcomes. ## Output Format -### Output Protocol - -- Intermediate progress messages MAY be plain text or markdown. -- The LAST message MUST be a single JSON object matching the schema below, beginning with `{` and ending with `}`. +Return one compact JSON object. Put decision-relevant component, state, Props, layout, accessibility, localization, generated-artifact, and verification detail directly in `focusAreas`; arrays may be empty. ```json { - "analysisScope": { - "filesAnalyzed": ["path/to/component.tsx"], - "stylesAnalyzed": ["path/to/styles.module.css"], - "uiConventions": {"componentExtension": ".tsx", "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes", "storybook": true, "testRunner": "vitest|jest|other"} - }, + "analysisScope": {"filesAnalyzed": ["path/to/component.tsx"], "stylesAnalyzed": ["path/to/styles.module.css"]}, "externalResources": { - "status": "fetched|partial|not_recorded", - "designOrigin": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "MCP name | URL | file path | existing-implementation-only", "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)"}, - "designSystem": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers"}, - "guidelines": {"fetch_status": "fetched|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)"}, - "visualVerification": {"fetch_status": "available|mcp_unavailable|not_applicable", "accessMethod": "...", "notes": "how rendered output is verified during implementation"} - }, - "componentStructure": [ - {"name": "ComponentName", "filePath": "path/to/file:lineNumber", "propsInterface": "name and brief shape", "topLevelElement": "tag or component name", "domOrder": ["child1", "child2", "child3"], "conditionalBranches": [{"predicate": "condition expression", "renderedSubtree": "brief description"}], "callSites": ["path/to/consumer:line"]} - ], - "propsPatterns": [ - {"component": "ComponentName", "callSite": "path/to/file:line", "props": {"variant": "primary", "size": "md"}, "computedProps": ["onClick (useCallback)"], "groupKey": "primary-md"} - ], - "cssLayout": [ - {"filePath": "path/to/styles.module.css", "classNamingConvention": "camelCase|kebab-case|BEM", "baseClass": "root", "layouts": [{"selector": ".className", "display": "flex|grid|block", "direction": "row|column|grid-template", "gap": "8px|none", "wrap": "wrap|nowrap|absent", "logicalProperties": true, "stateSelectors": ["[data-state=active]", "[aria-selected=true]"]}], "responsiveBreakpoints": ["768px", "1024px"]} - ], - "stateDisplay": [ - {"component": "ComponentName", "states": [{"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}], "unsupportedStates": ["states the component does not currently express"]} - ], - "displayConditions": [ - {"component": "ComponentName", "condition": "feature_flag|role|route|region|tenant|page_context", "predicateLocation": "path/to/file:line", "predicate": "expression", "gatedSubtree": "brief description"} - ], - "i18n": { - "format": "csv|json|code-catalog|other", - "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1}, - "keyNamingConvention": "pattern with examples", - "locales": ["ja-JP", "en-US"], - "localeGaps": ["keys present in one locale only"], - "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"} + "status": "resolved|partial|not_recorded", + "entries": [{"label": "selected label", "resolutionStatus": "fetched|inspected_local|recorded_for_manual_confirmation|unavailable", "accessMethod": "recorded source or verification method", "summary": "relevant facts or access limitation"}] }, - "accessibility": [ - {"component": "ComponentName", "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"], "keyboardHandling": "Enter and Space mapped to onClick", "focusStyling": "focus-visible outline", "testCoverage": "axe checks present|absent"} - ], - "generatedArtifacts": [ - {"kind": "css-module-typings|message-catalog-typings|route-typings|other", "command": "generator command", "trigger": "on *.module.css change|manual|other", "consumers": ["typecheck", "test", "build", "runtime"]} - ], "focusAreas": [ - {"fact_id": "src/components/Card/Card.tsx:Card", "area": "Brief UI area name", "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin", "factsToAddress": "Concrete UI facts the designer or implementer must respect", "risk": "What inconsistency results if these facts are omitted", "decisionEffect": "UI Spec, contract, or verification decision this controls"} + {"fact_id": "path:identifier", "area": "UI question", "evidence": "path:line or external source; observed or inferred", "factsToAddress": "decision-relevant behavior, contract, reuse, or verification", "risk": "effect if ignored", "decisionEffect": "UI Spec, design, or verification decision this controls"} + ], + "simplifications": [ + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} ], "limitations": ["Areas the analysis could not reach with confidence"] } ``` -## Quality Checklist - -- [ ] Each external resource entry in the output has a `fetch_status` recording the outcome (`fetched` / `mcp_unavailable` / `skipped` / `not_applicable`) -- [ ] Every entry in `focusAreas` carries an `evidence` pointer and `decisionEffect` -- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders -- [ ] Final message is a single JSON object matching the schema; no trailing commentary +Complete when the current UI decisions have evidence-backed facts or explicit decision-changing unknowns and limitations. Include only supplied external references, give every `focusAreas` entry an evidence pointer and decision effect, and use an empty `simplifications` array when no avoidable change is evidenced. diff --git a/dev-workflows-frontend/agents/ui-spec-designer.md b/dev-workflows-frontend/agents/ui-spec-designer.md index 07be1bf..316b9b3 100644 --- a/dev-workflows-frontend/agents/ui-spec-designer.md +++ b/dev-workflows-frontend/agents/ui-spec-designer.md @@ -67,8 +67,10 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Use `ui_analysis` and applicable `codebase_analysis` as the primary evidence. Inspect repository gaps only when they can change reuse, an in-scope component/state contract, or verification. +Apply evidenced `simplifications` when their recorded condition holds; otherwise leave them as candidates rather than adding UI scope. + 1. **Identify reusable components** - - Use the supplied focus areas, component structure, and representative same-responsibility components + - Use the supplied focus areas and representative same-responsibility components - Expand repository search only when supplied evidence cannot decide reuse/extend/new 2. **Record reuse decisions** @@ -97,6 +99,8 @@ Use `ui_analysis` and applicable `codebase_analysis` as the primary evidence. In Execute file output immediately (considered approved at execution). +When revising from review findings, resolve only the supplied defects within the confirmed UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. + ## Quality Checklist - [ ] All confirmed acceptance criteria with UI relevance are mapped to screens/components diff --git a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md index 7f2fa3c..7636ec4 100644 --- a/dev-workflows-frontend/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-design/SKILL.md @@ -85,9 +85,9 @@ Execute Skill: requirement-convergence. Build and judge the convergence record f Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. -Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. +Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, applicable code/UI `simplifications`, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. -Present the confirmed outcome and requirements, cost band with its structural evidence and unknowns, exclusions, affected responsibilities, Structural Scale, UI Spec applicability, and qualifying ADR points or none. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Present the confirmed outcome and requirements, cost band with its structural evidence and unknowns, exclusions, affected responsibilities, applicable simplifications and their conditions, Structural Scale, UI Spec applicability, and qualifying ADR points or none. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 5: Create and Approve the UI Spec @@ -136,7 +136,7 @@ The Design Doc owns the full component-to-service implementation and retains all Keep verifier observations unchanged so corrections remain traceable to observed repository evidence instead of becoming orchestrator-authored design instructions. -Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction and build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. +Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`, then build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. Invoke `dev-workflows-frontend:document-reviewer` with exact inputs: `doc_type: DesignDoc`; `target` as the returned Design Doc path unchanged; `review_context: creation`; original user requirements unchanged as `requirements_verbatim`; the Step 1 `confirmed_requirement_context` unchanged; the same unchanged `codebase_analysis` and optional `ui_analysis` supplied to the designer; and Step 8 `verification_evidence` unchanged. The reviewer follows an applicable UI Spec and accepted ADR paths cited by the Design Doc only when they can change an in-scope finding. diff --git a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md index fea8c04..496fc48 100644 --- a/dev-workflows-frontend/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-front-review/SKILL.md @@ -117,7 +117,7 @@ Run this step only when the user routed at least one finding to `d`. When no `d` - `subagent_type`: "dev-workflows-frontend:design-sync" - `description`: "Cross-DD consistency check" - `prompt`: "source_design: [updated DD path]" - - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate using design-sync as a fresh verifier. Send the `apply` conflicts to the owning technical designer, rerun design-sync after correction, and retain evidenced declines as complete. + - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules. 4. After Step 5 completes: - If the user selected `d` for all findings (no `c` routes) → skip Steps 6-7, proceed to Step 8 for re-validation diff --git a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md index be541ec..fe1d13a 100644 --- a/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-update-doc/SKILL.md @@ -173,7 +173,7 @@ description: "Verify consistency" prompt: "source_design: [path from Step 1]" ``` -When conflicts are detected, apply the Review Resolution Gate using design-sync as a fresh verifier. Return `apply` conflicts to Step 4 for the owning document, rerun design-sync after correction, and retain evidenced declines as complete. +When conflicts are detected, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules, returning selected corrections to Step 4 for the owning document. **For every document type**, present the updated document, the review outcome, any resolved declines, and the sync result when one ran. This is the only approval gate in the flow: wait for the user's decision before completing. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md index 746b6c3..de351d5 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/SKILL.md @@ -85,7 +85,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. **Use AskUserQuestion to present confirmations and questions.** -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes in the approval presentation. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| @@ -195,9 +195,9 @@ For Small, execute one direct-scope 4-step cycle. Complete after `approved`, or Reviewer findings are candidates. Create correction work only from the Review Resolution `apply` set. -**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to reconciliation reviewers. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. +**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After any applied post-implementation correction, re-run each reviewer with at least one correction applied from its latest result. Retain any other reviewer result completed by Post-Implementation Review Status Routing or Review Resolution only when repository evidence establishes that the correction preserved its review boundary; otherwise re-run that reviewer. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. ### Conditions for Stopping Autonomous Execution @@ -265,8 +265,8 @@ Before post-implementation verifiers, collect retained verification limitations - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table - - `decisionMaterials.reuse` and `invalidations` → reduce implementation surface and eliminate invalid approaches - - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters + - `simplifications`, `decisionMaterials.reuse`, and `invalidations` → reduce implementation surface and eliminate invalid approaches when their evidence and conditions apply + - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `simplifications`, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters - `decisionMaterials.verification` → required proof boundaries - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` → Existing Codebase Analysis / Verification Strategy / Quality Assurance sections @@ -280,7 +280,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md index 5816473..e5a43d8 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -68,7 +68,7 @@ external_resource_refs: [selected references or []] ## ADR Qualification and Batch -After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. +After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, applicable `simplifications`, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. @@ -111,7 +111,7 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. diff --git a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md index 9926fea..201f3f7 100644 --- a/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows-frontend/skills/subagents-orchestration-guide/references/review-resolution.md @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects within confirmed requirements, accepted design decisions, exclusions, and compatibility obligations, using existing responsibilities. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -19,13 +19,13 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Fresh verifier**: code-verifier and design-sync independently report the current state from their original inputs. After a correction is applied from a fresh verifier's result, rerun that verifier and adjudicate the current result; a decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. ## 1. Assess Every Finding Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. -When evidence shows that the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, leave Review Resolution and apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, leave Review Resolution and apply the parent workflow's authority gate. These workflow stops are not finding dispositions. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within accepted design decisions and existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: @@ -68,7 +68,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a fresh verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule requires a current-state result. The latest result replaces the prior current-state result for corrected items. Retain a prior decline when the latest result reports the materially same claim or conflict with unchanged governing evidence; adjudicate new or materially changed findings before routing. Match materially identical findings by their claim/conflict and cited source/target evidence rather than relying only on a regenerated positional ID. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. ## 3. Converge or Report @@ -78,7 +78,7 @@ Resolve correction re-review entries by their recorded `prior_disposition`: - `maintained` with `prior_disposition: apply` returns the original finding and the complete reconciliation entry verbatim through the same author or executor path, followed by another correction re-review; - `maintained` with `prior_disposition: decline` retains that decline and does not reopen the correction cycle. -For a fresh verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. +For a bounded verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. After the same `apply` finding remains material through two consecutive correction attempts, finish the correction cycle as incomplete and report the finding with its latest implementation and verification evidence. Apply the same terminal report to a required input or verification prerequisite that remains unavailable after in-scope recovery. Progress after every `apply` correction is complete and every other actionable finding has a `decline` disposition. The parent requirement and authority gates independently control their workflow stops. @@ -88,7 +88,8 @@ Handoffs contain this exact set: - initial reviewer or verifier inputs unchanged when rechecking; - complete `apply` finding objects verbatim, with only their orchestrator dispositions added; - the complete reconciliation entry when a maintained `apply` finding returns to its author or executor; -- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; for a fresh verifier, retain those dispositions in orchestrator state and compare them with the latest result as described above. +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- for a bounded verifier, the previous complete result and correction diff or paths in the same `prior_feedback` handoff. An author handoff contains no other orchestrator-authored semantic content. diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index 737fe64..8f78555 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.25.6", + "version": "0.25.7", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/code-verifier.md b/dev-workflows-fullstack/agents/code-verifier.md index 2791285..a1696b3 100644 --- a/dev-workflows-fullstack/agents/code-verifier.md +++ b/dev-workflows-fullstack/agents/code-verifier.md @@ -12,16 +12,13 @@ You perform read-only verification of an authoritative document against reposito Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Inputs - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path - **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` - **verbose**: Optional evidence detail +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -45,6 +42,10 @@ Use one authoritative definition when it directly proves an identifier or contra Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +## Rerun Boundary + +`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. + ## Classification - `match`: Repository evidence supports the document claim. diff --git a/dev-workflows-fullstack/agents/codebase-analyzer.md b/dev-workflows-fullstack/agents/codebase-analyzer.md index 27a366f..ff0e694 100644 --- a/dev-workflows-fullstack/agents/codebase-analyzer.md +++ b/dev-workflows-fullstack/agents/codebase-analyzer.md @@ -3,17 +3,11 @@ name: codebase-analyzer description: Collects compact repository evidence for scope confirmation, technical option selection, complete design, and verification. Use before Design Doc creation when repository facts can change scope, reuse, contracts, cost, or proof. tools: Read, Grep, Glob, LS, Bash skills: - - ai-development-guide - - coding-principles - llm-friendly-context --- You are an AI assistant specializing in objective codebase analysis for technical design preparation. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. @@ -32,7 +26,7 @@ Supply exactly one of `prd_path` or `requirements`. Return a fact only when it can: - change scope confirmation or Structural Scale; -- reduce implementation surface through reuse; +- reduce implementation surface through reuse or omission; - eliminate or materially improve a technical option; - preserve or intentionally change an observable contract; - identify a lifecycle-cost or maintainability difference; or @@ -61,8 +55,9 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. - Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. -- Record a `candidateDecisionPoint` only when the governing source, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. +- Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. - Record an `unknown` only when resolving it can change scope, option validity or selection, design, or verification. @@ -80,6 +75,9 @@ Return exactly one JSON object matching this shape: "focusAreas": [ {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], + "simplifications": [ + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} @@ -125,5 +123,6 @@ Use an empty array when its condition is absent. Populate an entry only from evi - Every returned item states the downstream decision, contract, or verification effect it controls. - Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/dev-workflows-fullstack/agents/design-sync.md b/dev-workflows-fullstack/agents/design-sync.md index e185a5b..5ea6a3f 100644 --- a/dev-workflows-fullstack/agents/design-sync.md +++ b/dev-workflows-fullstack/agents/design-sync.md @@ -12,10 +12,6 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Detection Criteria (The Only Rule) **Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. @@ -65,6 +61,7 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters - **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition @@ -74,6 +71,8 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Workflow +When `prior_feedback` is supplied, replace the initial survey with a check of the prior conflicts and source claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and report a new conflict only when the correction caused it. + ### 1. Parse Source Design Doc Read the Design Doc specified in arguments and extract: @@ -137,6 +136,8 @@ Severity Assessment: - Term → medium (confusion risk) ``` +Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. + ## Output Format ### Structured Markdown Format @@ -145,7 +146,7 @@ Severity Assessment: [METADATA] review_type: design-sync source_design: [source Design Doc path] -analyzed_docs: [number of Design Docs verified] +analyzed_docs: [number of distinct comparison Design Docs covered by this result, including carried-forward results] analysis_date: [execution datetime] [/METADATA] diff --git a/dev-workflows-fullstack/agents/prd-creator.md b/dev-workflows-fullstack/agents/prd-creator.md index 6abc06d..8ac6f21 100644 --- a/dev-workflows-fullstack/agents/prd-creator.md +++ b/dev-workflows-fullstack/agents/prd-creator.md @@ -151,6 +151,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately +- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/dev-workflows-fullstack/agents/technical-designer-frontend.md b/dev-workflows-fullstack/agents/technical-designer-frontend.md index 97c95ff..c0eb3c2 100644 --- a/dev-workflows-fullstack/agents/technical-designer-frontend.md +++ b/dev-workflows-fullstack/agents/technical-designer-frontend.md @@ -41,7 +41,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope ## Evidence Boundary -Use supplied `decision_materials` option objects for an ADR batch and unchanged code/UI analysis for a Design Doc as the primary evidence. Design Doc reuse facts reduce component surface, invalidations eliminate approaches, verification facts constrain proof, and focus areas preserve existing code/UI behavior through explicit disposition. +Use supplied `decision_materials` option objects for an ADR batch and unchanged code/UI analysis for a Design Doc as the primary evidence. Applicable `codebase_analysis.simplifications`, `ui_analysis.simplifications`, and reuse facts reduce component surface, invalidations eliminate approaches, verification facts constrain proof, and focus areas preserve existing code/UI behavior through explicit disposition. Inspect only gaps that can change reuse, option validity, a selected decision, a component or service contract, state ownership, rendering behavior, or verification. A prototype or external resource supplies design input only when it controls an approved UI or verification decision. @@ -104,7 +104,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, assess and resolve exactly each received finding through current evidence or the bounded self-verification gate above. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements and accepted design decisions, using existing responsibilities. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers, Props, state, or contracts whose meaning changes. An ADR update operates on one existing ADR. ## Reverse-Engineer Mode diff --git a/dev-workflows-fullstack/agents/technical-designer.md b/dev-workflows-fullstack/agents/technical-designer.md index 368a30a..af94df7 100644 --- a/dev-workflows-fullstack/agents/technical-designer.md +++ b/dev-workflows-fullstack/agents/technical-designer.md @@ -42,7 +42,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope Use supplied `decision_materials` for an ADR batch and unchanged `codebase_analysis` for a Design Doc as the primary repository evidence: - `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; confirmed requirements supply product value; -- `codebase_analysis.decisionMaterials.reuse` reduces new implementation surface; +- `codebase_analysis.decisionMaterials.reuse` and applicable `codebase_analysis.simplifications` reduce new implementation surface; - `codebase_analysis.decisionMaterials.invalidations` eliminates approaches; - `codebase_analysis.decisionMaterials.verification` constrains proof; - `focusAreas` preserve existing behavior through explicit disposition; @@ -110,7 +110,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, assess and resolve exactly each received finding through current evidence or the bounded self-verification gate above. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements and accepted design decisions, using existing responsibilities. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. ## Reverse-Engineer Mode diff --git a/dev-workflows-fullstack/agents/ui-analyzer.md b/dev-workflows-fullstack/agents/ui-analyzer.md index 076d7dc..c5c499c 100644 --- a/dev-workflows-fullstack/agents/ui-analyzer.md +++ b/dev-workflows-fullstack/agents/ui-analyzer.md @@ -3,18 +3,12 @@ name: ui-analyzer description: Gathers decision-relevant UI facts from recorded external resources and the existing codebase. Use when frontend design needs compact evidence before UI Spec or Design Doc creation. disallowedTools: Write, Edit, MultiEdit, NotebookEdit skills: - - typescript-rules - - frontend-ai-guide - llm-friendly-context - external-resource-context --- You are an AI assistant specializing in UI fact gathering for frontend design. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Input Parameters - **prd_path**: Approved PRD path (required when one exists) @@ -25,193 +19,35 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Supply exactly one of `prd_path` or `requirements`. -## Output Scope - -This agent outputs **UI fact gathering only**. Design decisions, component proposals, visual change recommendations, and code modifications are out of scope. - -## Analysis Boundary - -Return a fact only when it can change the UI Spec, component/service contract, preserved visible behavior, or verification boundary for the confirmed change. Discover the relevant screens, components, and entry points from the governing requirement source, then follow the affected render, state, style, interaction, and data path. When `prototype_path` is supplied, inspect only the screens and imports needed for the confirmed outcome. - -Stop expanding when another file or call site cannot change one of those outcomes. Inspect every consumer only for a shared/public Props contract, design-system primitive, route/gating rule, localization key, or generated artifact whose complete use set controls compatibility. Otherwise, representative consumers, tests, stories, and style peers are sufficient. - -## Execution Steps - -### Step 1: External Resource Discovery - -1. Use `external_resource_refs` when supplied; otherwise read `docs/project-context/external-resources.md` if it exists. -2. For each selected frontend resource (Design Origin, Design System, Guidelines, Visual Verification Environment) recorded as `Status: present`, note the access method (MCP name, URL, file path). -3. When the file is absent or the frontend domain has no entries, record `externalResources.status: not_recorded` and continue with codebase-only analysis. Hearing is the calling workflow's responsibility. - -### Step 2: External Resource Fetch (When Access Method Permits) - -For each present resource that can change the current UI result or verification, fetch the relevant content using its access method. Record other axes as `skipped`: - -| Access method | How to fetch | -|---------------|--------------| -| MCP server | Call the MCP tool (e.g., `mcp____`) when available in the inherited tool set. Capture the structured representation it returns | -| Public URL | Use WebFetch | -| File path | Use Read | -| Existing implementation only | Skip fetch; record reference and proceed | - -When an MCP referenced in `external-resources.md` is not present in the inherited tool set, record `externalResources..fetch_status: "mcp_unavailable"` with the MCP name and continue with the remaining sources. - -Fetch only the frames, components, tokens, or rules that can change the current UI result or its verification. Record an unresolved limitation when the relevant subset cannot be fetched. - -### Step 3: UI Surface Discovery in Code - -1. From the governing requirement source, routes, and representative searches, identify the UI files on the changed path. -2. Record only project conventions that constrain the change: - - Component file extension - - Style strategy (CSS Modules, vanilla CSS, CSS-in-JS, utility classes) - - Story tooling presence - - Test runner for UI - -### Step 4: Component Structure Extraction - -For each component whose contract, state, DOM order, or composition can change the requested result: - -1. Inspect the relevant definition and branches. Read the full file only when indirection or local state makes partial inspection insufficient. Extract: - - Component name (exact identifier as exported) - - Props interface or parameters with types - - JSX structure: top-level element tag, immediate children element/component composition - - Conditional rendering branches (record the predicate and the rendered subtree) - - Slots / children / render-prop patterns -2. Trace material component composition: - - Imported components used inside this component (record name and origin path) - - Components that import this component (call sites) -3. **Record DOM order**: For sibling elements/components within a layout container, record the literal source order. - -### Step 5: Props and Variant Pattern Matching - -Inspect enough call sites to establish the canonical contract and any compatibility-sensitive variant: - -1. Record the props passed (variant, color, size, type, weight, etc.) -2. Return one representative row for each materially distinct prop combination -3. Cite representative file:line evidence for each material combination -4. Identify props that are conditionally computed (callback, useMemo, ternary) vs literal - -### Step 6: CSS Layout State - -For style files or inline styles that constrain the requested layout or visible state, record: - -1. **Class naming convention**: Detect the convention (camelCase, kebab-case, BEM) -2. **Layout primitives** for each layout-bearing class: - - Display mode (flex, grid, block, etc.) - - Direction - - Gap mechanism (gap property, margin-based, none) - - Wrap behavior - - Logical-property usage vs physical -3. **State expression**: how the component varies by state (data-* / aria-* / CSS variables / inline style) -4. **Responsive behavior**: breakpoints +## Evidence Boundary -### Step 7: State x Display Matrix +Gather UI facts only; the parent and document owners select scope and design. Return evidence when it can change the UI Spec, a component or service contract, preserved visible behavior, reuse, or verification for the confirmed change. Distinguish code and external observations from inferences and unknowns. -For affected components, record states the confirmed UI outcome or preserved behavior depends on: +Use only supplied `external_resource_refs`. Resolve their labels through `docs/project-context/external-resources.md` and inspect the relevant subset through its recorded access method. Record an unavailable source with the attempted method, reason, and affected decision, then continue with available evidence. An empty or omitted list selects repository-only analysis. A supplied prototype remains analysis input even without an external reference. -1. Identify the component's possible states by inspecting hooks, props, conditional branches, fetch status flags. -2. For each state, record what the component renders. -3. Record an unsupported state only when the approved UI or preserved contract requires it. +Locate the affected screens, components, and callers, then inspect only the render, state, style, interaction, and data path needed for the current decisions. Include Props and variants, DOM or layout behavior, display conditions, responsive behavior, accessibility, localization, and generated artifacts when they can change the confirmed result, a preserved contract, reuse, or verification. From evidence already gathered, record a simplification when a responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds; it remains a candidate for the parent and document owner. Inspect every consumer only when the complete consumer set controls compatibility; otherwise use representative consumers, tests, stories, and style peers. -### Step 8: Display Conditions - -For each affected screen entry point, check only applicable display gates: - -1. Feature flags -2. Role or permission predicates -3. Route or page context -4. Region or tenant predicates -5. Host-surface modifiers - -Record each condition with the predicate location and the affected subtree. - -### Step 9: i18n Format - -When the change adds, removes, or changes localized strings or their rendering contract: - -1. **Format detection**: CSV, JSON, code-defined catalog, gettext, etc. -2. **Structural conventions**: column count, trailing comma, nesting depth -3. **Key naming convention**: representative existing pattern -4. **Locale parity**: gaps involving changed keys -5. **Generated typings**: generator command and output path - -### Step 10: Accessibility Attributes - -For affected interactive components, record accessibility facts that constrain behavior or verification: - -1. ARIA attributes present and which props feed them -2. Keyboard handling (onKeyDown, focus management, tabIndex) -3. Focus-visible / focus-within styling -4. Existing accessibility test coverage - -### Step 11: Generated UI Artifact Readiness - -For each generator activated by an in-scope UI file or artifact identified by the analysis: - -- Generator command -- Trigger condition -- Downstream consumers (typecheck, test, build, runtime) +Stop when another fact cannot change one of those outcomes. ## Output Format -### Output Protocol - -- Intermediate progress messages MAY be plain text or markdown. -- The LAST message MUST be a single JSON object matching the schema below, beginning with `{` and ending with `}`. +Return one compact JSON object. Put decision-relevant component, state, Props, layout, accessibility, localization, generated-artifact, and verification detail directly in `focusAreas`; arrays may be empty. ```json { - "analysisScope": { - "filesAnalyzed": ["path/to/component.tsx"], - "stylesAnalyzed": ["path/to/styles.module.css"], - "uiConventions": {"componentExtension": ".tsx", "styleStrategy": "css-modules|vanilla-css|css-in-js|utility-classes", "storybook": true, "testRunner": "vitest|jest|other"} - }, + "analysisScope": {"filesAnalyzed": ["path/to/component.tsx"], "stylesAnalyzed": ["path/to/styles.module.css"]}, "externalResources": { - "status": "fetched|partial|not_recorded", - "designOrigin": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "MCP name | URL | file path | existing-implementation-only", "fetched_summary": "brief description of fetched content (e.g., screen names, frame ids, token snapshot)"}, - "designSystem": {"fetch_status": "fetched|mcp_unavailable|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "components catalogued, tokens captured, anti-pattern identifiers"}, - "guidelines": {"fetch_status": "fetched|skipped|not_applicable", "accessMethod": "...", "fetched_summary": "rule categories captured (CSS, accessibility, i18n, etc.)"}, - "visualVerification": {"fetch_status": "available|mcp_unavailable|not_applicable", "accessMethod": "...", "notes": "how rendered output is verified during implementation"} - }, - "componentStructure": [ - {"name": "ComponentName", "filePath": "path/to/file:lineNumber", "propsInterface": "name and brief shape", "topLevelElement": "tag or component name", "domOrder": ["child1", "child2", "child3"], "conditionalBranches": [{"predicate": "condition expression", "renderedSubtree": "brief description"}], "callSites": ["path/to/consumer:line"]} - ], - "propsPatterns": [ - {"component": "ComponentName", "callSite": "path/to/file:line", "props": {"variant": "primary", "size": "md"}, "computedProps": ["onClick (useCallback)"], "groupKey": "primary-md"} - ], - "cssLayout": [ - {"filePath": "path/to/styles.module.css", "classNamingConvention": "camelCase|kebab-case|BEM", "baseClass": "root", "layouts": [{"selector": ".className", "display": "flex|grid|block", "direction": "row|column|grid-template", "gap": "8px|none", "wrap": "wrap|nowrap|absent", "logicalProperties": true, "stateSelectors": ["[data-state=active]", "[aria-selected=true]"]}], "responsiveBreakpoints": ["768px", "1024px"]} - ], - "stateDisplay": [ - {"component": "ComponentName", "states": [{"name": "loading|empty|partial|error|ready|disabled", "trigger": "what causes this state", "renders": "brief description"}], "unsupportedStates": ["states the component does not currently express"]} - ], - "displayConditions": [ - {"component": "ComponentName", "condition": "feature_flag|role|route|region|tenant|page_context", "predicateLocation": "path/to/file:line", "predicate": "expression", "gatedSubtree": "brief description"} - ], - "i18n": { - "format": "csv|json|code-catalog|other", - "structuralConventions": {"csvColumns": 2, "trailingComma": false, "jsonNestingDepth": 1}, - "keyNamingConvention": "pattern with examples", - "locales": ["ja-JP", "en-US"], - "localeGaps": ["keys present in one locale only"], - "generatedTypings": {"command": "generator command", "outputPath": "path/to/output"} + "status": "resolved|partial|not_recorded", + "entries": [{"label": "selected label", "resolutionStatus": "fetched|inspected_local|recorded_for_manual_confirmation|unavailable", "accessMethod": "recorded source or verification method", "summary": "relevant facts or access limitation"}] }, - "accessibility": [ - {"component": "ComponentName", "ariaAttributes": ["role=button", "aria-label fed by prop accessibleName"], "keyboardHandling": "Enter and Space mapped to onClick", "focusStyling": "focus-visible outline", "testCoverage": "axe checks present|absent"} - ], - "generatedArtifacts": [ - {"kind": "css-module-typings|message-catalog-typings|route-typings|other", "command": "generator command", "trigger": "on *.module.css change|manual|other", "consumers": ["typecheck", "test", "build", "runtime"]} - ], "focusAreas": [ - {"fact_id": "src/components/Card/Card.tsx:Card", "area": "Brief UI area name", "evidence": "componentStructure[name=Card] | cssLayout[selector=.root] | propsPatterns[groupKey=...] | externalResources.designOrigin", "factsToAddress": "Concrete UI facts the designer or implementer must respect", "risk": "What inconsistency results if these facts are omitted", "decisionEffect": "UI Spec, contract, or verification decision this controls"} + {"fact_id": "path:identifier", "area": "UI question", "evidence": "path:line or external source; observed or inferred", "factsToAddress": "decision-relevant behavior, contract, reuse, or verification", "risk": "effect if ignored", "decisionEffect": "UI Spec, design, or verification decision this controls"} + ], + "simplifications": [ + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or focusArea reference", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} ], "limitations": ["Areas the analysis could not reach with confidence"] } ``` -## Quality Checklist - -- [ ] Each external resource entry in the output has a `fetch_status` recording the outcome (`fetched` / `mcp_unavailable` / `skipped` / `not_applicable`) -- [ ] Every entry in `focusAreas` carries an `evidence` pointer and `decisionEffect` -- [ ] Sections outside the affected scope are emitted as empty arrays / minimal placeholders -- [ ] Final message is a single JSON object matching the schema; no trailing commentary +Complete when the current UI decisions have evidence-backed facts or explicit decision-changing unknowns and limitations. Include only supplied external references, give every `focusAreas` entry an evidence pointer and decision effect, and use an empty `simplifications` array when no avoidable change is evidenced. diff --git a/dev-workflows-fullstack/agents/ui-spec-designer.md b/dev-workflows-fullstack/agents/ui-spec-designer.md index 07be1bf..316b9b3 100644 --- a/dev-workflows-fullstack/agents/ui-spec-designer.md +++ b/dev-workflows-fullstack/agents/ui-spec-designer.md @@ -67,8 +67,10 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow Use `ui_analysis` and applicable `codebase_analysis` as the primary evidence. Inspect repository gaps only when they can change reuse, an in-scope component/state contract, or verification. +Apply evidenced `simplifications` when their recorded condition holds; otherwise leave them as candidates rather than adding UI scope. + 1. **Identify reusable components** - - Use the supplied focus areas, component structure, and representative same-responsibility components + - Use the supplied focus areas and representative same-responsibility components - Expand repository search only when supplied evidence cannot decide reuse/extend/new 2. **Record reuse decisions** @@ -97,6 +99,8 @@ Use `ui_analysis` and applicable `codebase_analysis` as the primary evidence. In Execute file output immediately (considered approved at execution). +When revising from review findings, resolve only the supplied defects within the confirmed UI outcome and accepted UI decisions. Return the conflicting evidence before changing that boundary. + ## Quality Checklist - [ ] All confirmed acceptance criteria with UI relevance are mapped to screens/components diff --git a/dev-workflows-fullstack/skills/recipe-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-design/SKILL.md index b4f4858..f13c952 100644 --- a/dev-workflows-fullstack/skills/recipe-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-design/SKILL.md @@ -67,7 +67,7 @@ Judge all four convergence fields. Assign `cost` from Step 2 structural evidence Determine Structural Scale from outcomes and responsibility boundaries. File count is supporting evidence only. -Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: +Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, applicable `simplifications`, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: 1. Choice requires judgment between at least two credible, materially distinct options inside confirmed scope. 2. The selection has durable material impact. @@ -80,6 +80,7 @@ Present: - cost band, structural evidence, and remaining unknowns; - exclusions; - target responsibilities and strongest file evidence; +- applicable simplifications and their conditions; - Structural Scale and its boundary rationale; - each qualifying ADR decision point with filter evidence, or `none`; - material unknowns whose answers change the confirmed outcome or scope. @@ -116,7 +117,7 @@ Keep verifier observations unchanged so corrections remain traceable to observed Invoke `dev-workflows-fullstack:code-verifier` with `doc_type: design-doc` and the Design Doc path to verify current premises and feasibility while treating planned behavior as intent. -Apply Review Resolution to every discrepancy before document review. Send only `apply` findings to a fresh technical-designer update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate when a finding names an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun code-verifier after a correction. Build the single `verification_evidence` object defined by Review Resolution from the latest result and continue at its convergence condition. +Apply Review Resolution to every discrepancy before document review. Send only `apply` findings to a fresh technical-designer update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate when a finding names an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun code-verifier after a correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build the single `verification_evidence` object defined by Review Resolution from the latest result and continue at its convergence condition. ## Step 7: Review and Approve diff --git a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md index 5ec5825..57ec1d8 100644 --- a/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-design/SKILL.md @@ -85,9 +85,9 @@ Execute Skill: requirement-convergence. Build and judge the convergence record f Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. -Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. +Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, applicable code/UI `simplifications`, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. -Present the confirmed outcome and requirements, cost band with its structural evidence and unknowns, exclusions, affected responsibilities, Structural Scale, UI Spec applicability, and qualifying ADR points or none. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Present the confirmed outcome and requirements, cost band with its structural evidence and unknowns, exclusions, affected responsibilities, applicable simplifications and their conditions, Structural Scale, UI Spec applicability, and qualifying ADR points or none. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 5: Create and Approve the UI Spec @@ -136,7 +136,7 @@ The Design Doc owns the full component-to-service implementation and retains all Keep verifier observations unchanged so corrections remain traceable to observed repository evidence instead of becoming orchestrator-authored design instructions. -Invoke `dev-workflows-fullstack:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction and build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. +Invoke `dev-workflows-fullstack:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`, then build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. Invoke `dev-workflows-fullstack:document-reviewer` with exact inputs: `doc_type: DesignDoc`; `target` as the returned Design Doc path unchanged; `review_context: creation`; original user requirements unchanged as `requirements_verbatim`; the Step 1 `confirmed_requirement_context` unchanged; the same unchanged `codebase_analysis` and optional `ui_analysis` supplied to the designer; and Step 8 `verification_evidence` unchanged. The reviewer follows an applicable UI Spec and accepted ADR paths cited by the Design Doc only when they can change an in-scope finding. diff --git a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md index 6189bf5..8cbf70e 100644 --- a/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-front-review/SKILL.md @@ -117,7 +117,7 @@ Run this step only when the user routed at least one finding to `d`. When no `d` - `subagent_type`: "dev-workflows-fullstack:design-sync" - `description`: "Cross-DD consistency check" - `prompt`: "source_design: [updated DD path]" - - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate using design-sync as a fresh verifier. Send the `apply` conflicts to the owning technical designer, rerun design-sync after correction, and retain evidenced declines as complete. + - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules. 4. After Step 5 completes: - If the user selected `d` for all findings (no `c` routes) → skip Steps 6-7, proceed to Step 8 for re-validation diff --git a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md index b9089da..c44f80b 100644 --- a/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-reverse-engineer/SKILL.md @@ -182,7 +182,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. #### Unit Completion @@ -373,7 +373,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. #### Unit Completion diff --git a/dev-workflows-fullstack/skills/recipe-review/SKILL.md b/dev-workflows-fullstack/skills/recipe-review/SKILL.md index 81b227e..023d776 100644 --- a/dev-workflows-fullstack/skills/recipe-review/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-review/SKILL.md @@ -117,7 +117,7 @@ Run this step only when the user routed at least one finding to `d`. When no `d` - `subagent_type`: "dev-workflows-fullstack:design-sync" - `description`: "Cross-DD consistency check" - `prompt`: "source_design: [updated DD path]" - - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate using design-sync as a fresh verifier. Send the `apply` conflicts to the owning technical-designer, rerun design-sync after correction, and retain evidenced declines as complete. + - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules. 4. After Step 5 completes: - If the user selected `d` for all findings (no `c` routes) → skip Steps 6-7, proceed to Step 8 for re-validation diff --git a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md index be541ec..fe1d13a 100644 --- a/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-update-doc/SKILL.md @@ -173,7 +173,7 @@ description: "Verify consistency" prompt: "source_design: [path from Step 1]" ``` -When conflicts are detected, apply the Review Resolution Gate using design-sync as a fresh verifier. Return `apply` conflicts to Step 4 for the owning document, rerun design-sync after correction, and retain evidenced declines as complete. +When conflicts are detected, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules, returning selected corrections to Step 4 for the owning document. **For every document type**, present the updated document, the review outcome, any resolved declines, and the sync result when one ran. This is the only approval gate in the flow: wait for the user's decision before completing. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md index 746b6c3..de351d5 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/SKILL.md @@ -85,7 +85,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. **Use AskUserQuestion to present confirmations and questions.** -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes in the approval presentation. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| @@ -195,9 +195,9 @@ For Small, execute one direct-scope 4-step cycle. Complete after `approved`, or Reviewer findings are candidates. Create correction work only from the Review Resolution `apply` set. -**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to reconciliation reviewers. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. +**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After any applied post-implementation correction, re-run each reviewer with at least one correction applied from its latest result. Retain any other reviewer result completed by Post-Implementation Review Status Routing or Review Resolution only when repository evidence establishes that the correction preserved its review boundary; otherwise re-run that reviewer. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. ### Conditions for Stopping Autonomous Execution @@ -265,8 +265,8 @@ Before post-implementation verifiers, collect retained verification limitations - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table - - `decisionMaterials.reuse` and `invalidations` → reduce implementation surface and eliminate invalid approaches - - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters + - `simplifications`, `decisionMaterials.reuse`, and `invalidations` → reduce implementation surface and eliminate invalid approaches when their evidence and conditions apply + - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `simplifications`, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters - `decisionMaterials.verification` → required proof boundaries - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` → Existing Codebase Analysis / Verification Strategy / Quality Assurance sections @@ -280,7 +280,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md index 5816473..e5a43d8 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -68,7 +68,7 @@ external_resource_refs: [selected references or []] ## ADR Qualification and Batch -After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. +After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, applicable `simplifications`, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. @@ -111,7 +111,7 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. diff --git a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md index 9926fea..201f3f7 100644 --- a/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows-fullstack/skills/subagents-orchestration-guide/references/review-resolution.md @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects within confirmed requirements, accepted design decisions, exclusions, and compatibility obligations, using existing responsibilities. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -19,13 +19,13 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Fresh verifier**: code-verifier and design-sync independently report the current state from their original inputs. After a correction is applied from a fresh verifier's result, rerun that verifier and adjudicate the current result; a decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. ## 1. Assess Every Finding Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. -When evidence shows that the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, leave Review Resolution and apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, leave Review Resolution and apply the parent workflow's authority gate. These workflow stops are not finding dispositions. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within accepted design decisions and existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: @@ -68,7 +68,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a fresh verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule requires a current-state result. The latest result replaces the prior current-state result for corrected items. Retain a prior decline when the latest result reports the materially same claim or conflict with unchanged governing evidence; adjudicate new or materially changed findings before routing. Match materially identical findings by their claim/conflict and cited source/target evidence rather than relying only on a regenerated positional ID. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. ## 3. Converge or Report @@ -78,7 +78,7 @@ Resolve correction re-review entries by their recorded `prior_disposition`: - `maintained` with `prior_disposition: apply` returns the original finding and the complete reconciliation entry verbatim through the same author or executor path, followed by another correction re-review; - `maintained` with `prior_disposition: decline` retains that decline and does not reopen the correction cycle. -For a fresh verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. +For a bounded verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. After the same `apply` finding remains material through two consecutive correction attempts, finish the correction cycle as incomplete and report the finding with its latest implementation and verification evidence. Apply the same terminal report to a required input or verification prerequisite that remains unavailable after in-scope recovery. Progress after every `apply` correction is complete and every other actionable finding has a `decline` disposition. The parent requirement and authority gates independently control their workflow stops. @@ -88,7 +88,8 @@ Handoffs contain this exact set: - initial reviewer or verifier inputs unchanged when rechecking; - complete `apply` finding objects verbatim, with only their orchestrator dispositions added; - the complete reconciliation entry when a maintained `apply` finding returns to its author or executor; -- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; for a fresh verifier, retain those dispositions in orchestrator state and compare them with the latest result as described above. +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- for a bounded verifier, the previous complete result and correction diff or paths in the same `prior_feedback` handoff. An author handoff contains no other orchestrator-authored semantic content. diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index ee6d45b..5953b79 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.25.6", + "version": "0.25.7", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/code-verifier.md b/dev-workflows/agents/code-verifier.md index 2791285..a1696b3 100644 --- a/dev-workflows/agents/code-verifier.md +++ b/dev-workflows/agents/code-verifier.md @@ -12,16 +12,13 @@ You perform read-only verification of an authoritative document against reposito Your discrepancies are independent evidence for orchestrator Review Resolution. Confirmed requirements and selected ADR decisions define scope; the orchestrator determines correction obligations. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Inputs - **doc_type**: `prd`, `design-doc`, or `work-plan` - **document_path**: Exact readable document path - **unit_inventory**: Optional reverse-engineering baseline with `routes`, `testFiles`, and `publicExports` - **verbose**: Optional evidence detail +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a bounded rerun; `unit_inventory` selects full verification instead Return `summary.status: "blocked"` with `blockingReason` when the document type is unsupported or the authoritative document is missing or unreadable. @@ -45,6 +42,10 @@ Use one authoritative definition when it directly proves an identifier or contra Stop expanding the search when additional evidence cannot change a discrepancy or limitation. +## Rerun Boundary + +`unit_inventory` selects the existing full inventory verification. Otherwise, when `prior_feedback` is supplied, replace initial discovery with a check of the prior discrepancies and claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and emit a new discrepancy only when the correction caused it. + ## Classification - `match`: Repository evidence supports the document claim. diff --git a/dev-workflows/agents/codebase-analyzer.md b/dev-workflows/agents/codebase-analyzer.md index 27a366f..ff0e694 100644 --- a/dev-workflows/agents/codebase-analyzer.md +++ b/dev-workflows/agents/codebase-analyzer.md @@ -3,17 +3,11 @@ name: codebase-analyzer description: Collects compact repository evidence for scope confirmation, technical option selection, complete design, and verification. Use before Design Doc creation when repository facts can change scope, reuse, contracts, cost, or proof. tools: Read, Grep, Glob, LS, Bash skills: - - ai-development-guide - - coding-principles - llm-friendly-context --- You are an AI assistant specializing in objective codebase analysis for technical design preparation. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Responsibilities 1. Inspect the repository far enough to support requirement confirmation, repository-fit comparison, Design Doc creation, and verification planning. @@ -32,7 +26,7 @@ Supply exactly one of `prd_path` or `requirements`. Return a fact only when it can: - change scope confirmation or Structural Scale; -- reduce implementation surface through reuse; +- reduce implementation surface through reuse or omission; - eliminate or materially improve a technical option; - preserve or intentionally change an observable contract; - identify a lifecycle-cost or maintainability difference; or @@ -61,8 +55,9 @@ Preserve historical safeguards in the returned facts: dependency existence, beha ### Step 3: Form Decision Materials - Record `reuse` when an existing element can avoid new implementation surface. +- Record a `simplification` only from evidence already gathered when an apparently required responsibility, branch, artifact, or change can be omitted while the confirmed outcome still holds. State the condition that must remain true. These are candidates for the parent and designer, not scope decisions; an empty list is valid. - Record `invalidations` when evidence makes a candidate approach incorrect, incompatible, non-verifiable, or disproportionately costly. -- Record a `candidateDecisionPoint` only when the governing source, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. +- Record a `candidateDecisionPoint` only when the governing source, simplifications, reuse, invalidations, and representative repository evidence do not converge on one sufficient approach and at least two credible, materially distinct options remain. Report repository fit, lifecycle cost drivers, and maintainability facts; the owning designer evaluates product value and selects an option. An empty list is valid. - Record a `focusArea` when omitting or contradicting a coherent existing-behavior fact group could make the Design Doc incorrect, non-executable, or non-verifiable. Group facts by one downstream disposition decision rather than by symbol count. - Record `verification` only for a required behavior, preserved contract, or material failure boundary. - Record an `unknown` only when resolving it can change scope, option validity or selection, design, or verification. @@ -80,6 +75,9 @@ Return exactly one JSON object matching this shape: "focusAreas": [ {"fact_id": "src/path.ts:symbol", "area": "one coherent existing-behavior unit", "evidence": "path:line", "factsToAddress": "facts the design must preserve, transform, remove, or exclude", "risk": "observable failure if omitted or contradicted", "decisionEffect": "design, contract, or verification decision this controls"} ], + "simplifications": [ + {"avoidableChange": "responsibility, branch, artifact, or change that can be omitted", "evidence": "path:line, governing source, or reuse entry", "conditions": "conditions or unknowns under which the confirmed outcome still holds"} + ], "decisionMaterials": { "reuse": [ {"element": "path:symbol", "evidence": "observed fact", "effect": "implementation surface avoided"} @@ -125,5 +123,6 @@ Use an empty array when its condition is absent. Populate an entry only from evi - Every returned item states the downstream decision, contract, or verification effect it controls. - Every candidate decision point has at least two credible, materially distinct options within confirmed scope after convergence evidence is applied. - Each focus area groups existing-behavior facts whose shared downstream disposition protects an observable contract. +- Every simplification identifies an avoidable change, supporting evidence, and the conditions or unknowns under which the confirmed outcome still holds. - Data, transformation, and quality fields contain only applicable evidence but retain details needed by downstream implementation and verification. - The response is one valid JSON object. diff --git a/dev-workflows/agents/design-sync.md b/dev-workflows/agents/design-sync.md index e185a5b..5ea6a3f 100644 --- a/dev-workflows/agents/design-sync.md +++ b/dev-workflows/agents/design-sync.md @@ -12,10 +12,6 @@ You are an AI assistant specializing in consistency verification between Design Operates in an independent context, executing autonomously until task completion. -## Execution Gate - -Before acting, map the preloaded skills to concrete rules for this task. Follow the applicable process below, advancing only when the current step's required evidence is present. Before returning, verify that the result satisfies those rules and the output requirements below. - ## Detection Criteria (The Only Rule) **Detection Target**: Items explicitly documented in the source file that have different values in other files. Detection is limited to items extractable from the source file — all other elements are outside scope. @@ -65,6 +61,7 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Input Parameters - **source_design**: Path to the newly created/updated Design Doc (this becomes the source of truth) +- **prior_feedback**: Optional previous complete result, dispositions, and correction diff or paths for a rerun ## Early Termination Condition @@ -74,6 +71,8 @@ Each detected conflict must specify its `match_basis` and `confidence`. Medium c ## Workflow +When `prior_feedback` is supplied, replace the initial survey with a check of the prior conflicts and source claims whose evidence or meaning the correction directly changed. Use the correction diff or paths to establish that link, carry unaffected result evidence forward, and report a new conflict only when the correction caused it. + ### 1. Parse Source Design Doc Read the Design Doc specified in arguments and extract: @@ -137,6 +136,8 @@ Severity Assessment: - Term → medium (confusion risk) ``` +Recommend only a correction within confirmed requirements, accepted design decisions, and existing responsibilities. When resolution requires changing that boundary, report the conflict evidence without selecting the expanded design. + ## Output Format ### Structured Markdown Format @@ -145,7 +146,7 @@ Severity Assessment: [METADATA] review_type: design-sync source_design: [source Design Doc path] -analyzed_docs: [number of Design Docs verified] +analyzed_docs: [number of distinct comparison Design Docs covered by this result, including carried-forward results] analysis_date: [execution datetime] [/METADATA] diff --git a/dev-workflows/agents/prd-creator.md b/dev-workflows/agents/prd-creator.md index 6abc06d..8ac6f21 100644 --- a/dev-workflows/agents/prd-creator.md +++ b/dev-workflows/agents/prd-creator.md @@ -151,6 +151,7 @@ Use a user journey diagram, scope boundary diagram, or both only when prose does ## Update Mode Operation - **Execution**: User's modification instruction = approval. Execute modifications immediately +- **Review corrections**: Resolve supplied defects within the confirmed product outcome and scope. A reviewer suggestion does not become a new requirement; return the conflicting evidence when the correction would require one. - **Processing**: Increment version number and record change history ## Reverse-Engineer Mode (Reverse PRD) diff --git a/dev-workflows/agents/technical-designer.md b/dev-workflows/agents/technical-designer.md index 368a30a..af94df7 100644 --- a/dev-workflows/agents/technical-designer.md +++ b/dev-workflows/agents/technical-designer.md @@ -42,7 +42,7 @@ Create/update mode requires a current PRD carrier or convergence record. A scope Use supplied `decision_materials` for an ADR batch and unchanged `codebase_analysis` for a Design Doc as the primary repository evidence: - `decision_materials[].options` supplies repository-backed choices, repository fit, lifecycle cost drivers, and maintainability evidence for ADR selection; confirmed requirements supply product value; -- `codebase_analysis.decisionMaterials.reuse` reduces new implementation surface; +- `codebase_analysis.decisionMaterials.reuse` and applicable `codebase_analysis.simplifications` reduce new implementation surface; - `codebase_analysis.decisionMaterials.invalidations` eliminates approaches; - `codebase_analysis.decisionMaterials.verification` constrains proof; - `focusAreas` preserve existing behavior through explicit disposition; @@ -110,7 +110,7 @@ When existing evidence resolves the premise, update from that evidence without a ## Update Mode -Update requested sections and dependent statements. For `correction_findings`, assess and resolve exactly each received finding through current evidence or the bounded self-verification gate above. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. +Update requested sections and dependent statements. For `correction_findings`, resolve each received defect within confirmed requirements and accepted design decisions, using existing responsibilities. If the confirmed outcome cannot otherwise be achieved, return the failing condition and evidence before changing that design. Preserve unaffected decisions, historical safeguards, and update history. Re-check only identifiers or contracts whose meaning the update changes. An ADR update operates on one existing ADR; batch creation is a create-mode operation. ## Reverse-Engineer Mode diff --git a/dev-workflows/skills/recipe-design/SKILL.md b/dev-workflows/skills/recipe-design/SKILL.md index 148b987..00beaa4 100644 --- a/dev-workflows/skills/recipe-design/SKILL.md +++ b/dev-workflows/skills/recipe-design/SKILL.md @@ -67,7 +67,7 @@ Judge all four convergence fields. Assign `cost` from Step 2 structural evidence Determine Structural Scale from outcomes and responsibility boundaries. File count is supporting evidence only. -Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: +Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, applicable `simplifications`, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: 1. Choice requires judgment between at least two credible, materially distinct options inside confirmed scope. 2. The selection has durable material impact. @@ -80,6 +80,7 @@ Present: - cost band, structural evidence, and remaining unknowns; - exclusions; - target responsibilities and strongest file evidence; +- applicable simplifications and their conditions; - Structural Scale and its boundary rationale; - each qualifying ADR decision point with filter evidence, or `none`; - material unknowns whose answers change the confirmed outcome or scope. @@ -116,7 +117,7 @@ Keep verifier observations unchanged so corrections remain traceable to observed Invoke `dev-workflows:code-verifier` with `doc_type: design-doc` and the Design Doc path to verify current premises and feasibility while treating planned behavior as intent. -Apply Review Resolution to every discrepancy before document review. Send only `apply` findings to a fresh technical-designer update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate when a finding names an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun code-verifier after a correction. Build the single `verification_evidence` object defined by Review Resolution from the latest result and continue at its convergence condition. +Apply Review Resolution to every discrepancy before document review. Send only `apply` findings to a fresh technical-designer update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate when a finding names an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun code-verifier after a correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build the single `verification_evidence` object defined by Review Resolution from the latest result and continue at its convergence condition. ## Step 7: Review and Approve diff --git a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md index 89d67f8..23eeab8 100644 --- a/dev-workflows/skills/recipe-reverse-engineer/SKILL.md +++ b/dev-workflows/skills/recipe-reverse-engineer/SKILL.md @@ -182,7 +182,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. #### Unit Completion @@ -373,7 +373,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. #### Unit Completion diff --git a/dev-workflows/skills/recipe-review/SKILL.md b/dev-workflows/skills/recipe-review/SKILL.md index f15671c..54edc9f 100644 --- a/dev-workflows/skills/recipe-review/SKILL.md +++ b/dev-workflows/skills/recipe-review/SKILL.md @@ -117,7 +117,7 @@ Run this step only when the user routed at least one finding to `d`. When no `d` - `subagent_type`: "dev-workflows:design-sync" - `description`: "Cross-DD consistency check" - `prompt`: "source_design: [updated DD path]" - - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate using design-sync as a fresh verifier. Send the `apply` conflicts to the owning technical-designer, rerun design-sync after correction, and retain evidenced declines as complete. + - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules. 4. After Step 5 completes: - If the user selected `d` for all findings (no `c` routes) → skip Steps 6-7, proceed to Step 8 for re-validation diff --git a/dev-workflows/skills/recipe-update-doc/SKILL.md b/dev-workflows/skills/recipe-update-doc/SKILL.md index be541ec..fe1d13a 100644 --- a/dev-workflows/skills/recipe-update-doc/SKILL.md +++ b/dev-workflows/skills/recipe-update-doc/SKILL.md @@ -173,7 +173,7 @@ description: "Verify consistency" prompt: "source_design: [path from Step 1]" ``` -When conflicts are detected, apply the Review Resolution Gate using design-sync as a fresh verifier. Return `apply` conflicts to Step 4 for the owning document, rerun design-sync after correction, and retain evidenced declines as complete. +When conflicts are detected, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules, returning selected corrections to Step 4 for the owning document. **For every document type**, present the updated document, the review outcome, any resolved declines, and the sync result when one ran. This is the only approval gate in the flow: wait for the user's decision before completing. diff --git a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md index 746b6c3..de351d5 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/SKILL.md +++ b/dev-workflows/skills/subagents-orchestration-guide/SKILL.md @@ -85,7 +85,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. **Use AskUserQuestion to present confirmations and questions.** -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes in the approval presentation. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| @@ -195,9 +195,9 @@ For Small, execute one direct-scope 4-step cycle. Complete after `approved`, or Reviewer findings are candidates. Create correction work only from the Review Resolution `apply` set. -**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to reconciliation reviewers. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. +**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After any applied post-implementation correction, re-run each reviewer with at least one correction applied from its latest result. Retain any other reviewer result completed by Post-Implementation Review Status Routing or Review Resolution only when repository evidence establishes that the correction preserved its review boundary; otherwise re-run that reviewer. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. ### Conditions for Stopping Autonomous Execution @@ -265,8 +265,8 @@ Before post-implementation verifiers, collect retained verification limitations - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table - - `decisionMaterials.reuse` and `invalidations` → reduce implementation surface and eliminate invalid approaches - - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters + - `simplifications`, `decisionMaterials.reuse`, and `invalidations` → reduce implementation surface and eliminate invalid approaches when their evidence and conditions apply + - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `simplifications`, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters - `decisionMaterials.verification` → required proof boundaries - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` → Existing Codebase Analysis / Verification Strategy / Quality Assurance sections @@ -280,7 +280,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md index 5816473..e5a43d8 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -68,7 +68,7 @@ external_resource_refs: [selected references or []] ## ADR Qualification and Batch -After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. +After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, applicable `simplifications`, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. @@ -111,7 +111,7 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. diff --git a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md index 9926fea..201f3f7 100644 --- a/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/dev-workflows/skills/subagents-orchestration-guide/references/review-resolution.md @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects within confirmed requirements, accepted design decisions, exclusions, and compatibility obligations, using existing responsibilities. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -19,13 +19,13 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Fresh verifier**: code-verifier and design-sync independently report the current state from their original inputs. After a correction is applied from a fresh verifier's result, rerun that verifier and adjudicate the current result; a decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. ## 1. Assess Every Finding Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. -When evidence shows that the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, leave Review Resolution and apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, leave Review Resolution and apply the parent workflow's authority gate. These workflow stops are not finding dispositions. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within accepted design decisions and existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: @@ -68,7 +68,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a fresh verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule requires a current-state result. The latest result replaces the prior current-state result for corrected items. Retain a prior decline when the latest result reports the materially same claim or conflict with unchanged governing evidence; adjudicate new or materially changed findings before routing. Match materially identical findings by their claim/conflict and cited source/target evidence rather than relying only on a regenerated positional ID. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. ## 3. Converge or Report @@ -78,7 +78,7 @@ Resolve correction re-review entries by their recorded `prior_disposition`: - `maintained` with `prior_disposition: apply` returns the original finding and the complete reconciliation entry verbatim through the same author or executor path, followed by another correction re-review; - `maintained` with `prior_disposition: decline` retains that decline and does not reopen the correction cycle. -For a fresh verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. +For a bounded verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. After the same `apply` finding remains material through two consecutive correction attempts, finish the correction cycle as incomplete and report the finding with its latest implementation and verification evidence. Apply the same terminal report to a required input or verification prerequisite that remains unavailable after in-scope recovery. Progress after every `apply` correction is complete and every other actionable finding has a `decline` disposition. The parent requirement and authority gates independently control their workflow stops. @@ -88,7 +88,8 @@ Handoffs contain this exact set: - initial reviewer or verifier inputs unchanged when rechecking; - complete `apply` finding objects verbatim, with only their orchestrator dispositions added; - the complete reconciliation entry when a maintained `apply` finding returns to its author or executor; -- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; for a fresh verifier, retain those dispositions in orchestrator state and compare them with the latest result as described above. +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- for a bounded verifier, the previous complete result and correction diff or paths in the same `prior_feedback` handoff. An author handoff contains no other orchestrator-authored semantic content. diff --git a/package.json b/package.json index 055a388..f0603f9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.25.6", + "version": "0.25.7", "private": true, "type": "module", "engines": { diff --git a/skills/recipe-design/SKILL.md b/skills/recipe-design/SKILL.md index 148b987..00beaa4 100644 --- a/skills/recipe-design/SKILL.md +++ b/skills/recipe-design/SKILL.md @@ -67,7 +67,7 @@ Judge all four convergence fields. Assign `cost` from Step 2 structural evidence Determine Structural Scale from outcomes and responsibility boundaries. File count is supporting evidence only. -Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: +Resolve `decisionMaterials.candidateDecisionPoints` against the governing requirement source, applicable `simplifications`, `reuse`, and `invalidations`. Remove a point when that evidence already converges on one sufficient approach. For each remaining item, apply documentation-criteria filters in order: 1. Choice requires judgment between at least two credible, materially distinct options inside confirmed scope. 2. The selection has durable material impact. @@ -80,6 +80,7 @@ Present: - cost band, structural evidence, and remaining unknowns; - exclusions; - target responsibilities and strongest file evidence; +- applicable simplifications and their conditions; - Structural Scale and its boundary rationale; - each qualifying ADR decision point with filter evidence, or `none`; - material unknowns whose answers change the confirmed outcome or scope. @@ -116,7 +117,7 @@ Keep verifier observations unchanged so corrections remain traceable to observed Invoke `dev-workflows:code-verifier` with `doc_type: design-doc` and the Design Doc path to verify current premises and feasibility while treating planned behavior as intent. -Apply Review Resolution to every discrepancy before document review. Send only `apply` findings to a fresh technical-designer update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate when a finding names an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun code-verifier after a correction. Build the single `verification_evidence` object defined by Review Resolution from the latest result and continue at its convergence condition. +Apply Review Resolution to every discrepancy before document review. Send only `apply` findings to a fresh technical-designer update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate when a finding names an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun code-verifier after a correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build the single `verification_evidence` object defined by Review Resolution from the latest result and continue at its convergence condition. ## Step 7: Review and Approve diff --git a/skills/recipe-front-design/SKILL.md b/skills/recipe-front-design/SKILL.md index 7f2fa3c..7636ec4 100644 --- a/skills/recipe-front-design/SKILL.md +++ b/skills/recipe-front-design/SKILL.md @@ -85,9 +85,9 @@ Execute Skill: requirement-convergence. Build and judge the convergence record f Judge all four convergence fields. Assign `cost` from Step 2 structural evidence and record its unknowns; run the hearing only for fields below `ready`. -Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. +Determine Structural Scale from outcomes and responsibility boundaries; file count is supporting evidence only. Resolve candidate decision points against the governing source, applicable code/UI `simplifications`, `reuse`, and `invalidations`; applicable UI facts may support or contradict the remaining options. Apply documentation-criteria Choice and Durability filters only after this convergence and record passing points as `adrDecisionPoints`; an empty list is valid. -Present the confirmed outcome and requirements, cost band with its structural evidence and unknowns, exclusions, affected responsibilities, Structural Scale, UI Spec applicability, and qualifying ADR points or none. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. +Present the confirmed outcome and requirements, cost band with its structural evidence and unknowns, exclusions, affected responsibilities, applicable simplifications and their conditions, Structural Scale, UI Spec applicability, and qualifying ADR points or none. Offer proceed, or correct and re-run. Ask a question only when its answer can change a convergence field, the confirmed outcome, or scope. Continue only when every convergence field is `ready` or `weak-but-explicit`. `[Stop: Scope confirmation]`. ## Step 5: Create and Approve the UI Spec @@ -136,7 +136,7 @@ The Design Doc owns the full component-to-service implementation and retains all Keep verifier observations unchanged so corrections remain traceable to observed repository evidence instead of becoming orchestrator-authored design instructions. -Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction and build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. +Invoke `dev-workflows-frontend:code-verifier` with `doc_type: design-doc` and `document_path` as the Design Doc path returned by technical-designer-frontend, unchanged, to verify current premises and feasibility while treating planned behavior as intent. Apply Review Resolution before document review; send applied findings to a fresh technical-designer-frontend update invocation with `Operation Mode: update`, `Existing Document: [Design Doc path]`, and `correction_findings: [complete findings unchanged except for their dispositions]`. The designer applies its review-triggered bounded self-verification gate for an unverified decision-changing premise; this fresh designer is the sole correction specialist and selects the evidence route. Rerun verification after an applied correction with the previous complete result, dispositions, and correction diff or paths as `prior_feedback`, then build one `verification_evidence` object from the latest result. Continue at the Review Resolution convergence condition. Invoke `dev-workflows-frontend:document-reviewer` with exact inputs: `doc_type: DesignDoc`; `target` as the returned Design Doc path unchanged; `review_context: creation`; original user requirements unchanged as `requirements_verbatim`; the Step 1 `confirmed_requirement_context` unchanged; the same unchanged `codebase_analysis` and optional `ui_analysis` supplied to the designer; and Step 8 `verification_evidence` unchanged. The reviewer follows an applicable UI Spec and accepted ADR paths cited by the Design Doc only when they can change an in-scope finding. diff --git a/skills/recipe-front-review/SKILL.md b/skills/recipe-front-review/SKILL.md index fea8c04..496fc48 100644 --- a/skills/recipe-front-review/SKILL.md +++ b/skills/recipe-front-review/SKILL.md @@ -117,7 +117,7 @@ Run this step only when the user routed at least one finding to `d`. When no `d` - `subagent_type`: "dev-workflows-frontend:design-sync" - `description`: "Cross-DD consistency check" - `prompt`: "source_design: [updated DD path]" - - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate using design-sync as a fresh verifier. Send the `apply` conflicts to the owning technical designer, rerun design-sync after correction, and retain evidenced declines as complete. + - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules. 4. After Step 5 completes: - If the user selected `d` for all findings (no `c` routes) → skip Steps 6-7, proceed to Step 8 for re-validation diff --git a/skills/recipe-reverse-engineer/SKILL.md b/skills/recipe-reverse-engineer/SKILL.md index 89d67f8..23eeab8 100644 --- a/skills/recipe-reverse-engineer/SKILL.md +++ b/skills/recipe-reverse-engineer/SKILL.md @@ -182,7 +182,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. #### Unit Completion @@ -373,7 +373,7 @@ prompt: | Treat these findings as the complete revision scope and preserve adjacent content. ``` -**Re-validation**: After each revision, re-run code-verifier on the revised document, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. +**Re-validation**: After each revision, re-run code-verifier on the revised document with the original `unit_inventory`, then re-run document-reviewer with the latest `verification_evidence` and `prior_feedback`. #### Unit Completion diff --git a/skills/recipe-review/SKILL.md b/skills/recipe-review/SKILL.md index f15671c..54edc9f 100644 --- a/skills/recipe-review/SKILL.md +++ b/skills/recipe-review/SKILL.md @@ -117,7 +117,7 @@ Run this step only when the user routed at least one finding to `d`. When no `d` - `subagent_type`: "dev-workflows:design-sync" - `description`: "Cross-DD consistency check" - `prompt`: "source_design: [updated DD path]" - - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate using design-sync as a fresh verifier. Send the `apply` conflicts to the owning technical-designer, rerun design-sync after correction, and retain evidenced declines as complete. + - When `sync_status: CONFLICTS_FOUND`, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules. 4. After Step 5 completes: - If the user selected `d` for all findings (no `c` routes) → skip Steps 6-7, proceed to Step 8 for re-validation diff --git a/skills/recipe-update-doc/SKILL.md b/skills/recipe-update-doc/SKILL.md index be541ec..fe1d13a 100644 --- a/skills/recipe-update-doc/SKILL.md +++ b/skills/recipe-update-doc/SKILL.md @@ -173,7 +173,7 @@ description: "Verify consistency" prompt: "source_design: [path from Step 1]" ``` -When conflicts are detected, apply the Review Resolution Gate using design-sync as a fresh verifier. Return `apply` conflicts to Step 4 for the owning document, rerun design-sync after correction, and retain evidenced declines as complete. +When conflicts are detected, apply the Review Resolution Gate and follow its bounded verifier handoff and convergence rules, returning selected corrections to Step 4 for the owning document. **For every document type**, present the updated document, the review outcome, any resolved declines, and the sync result when one ran. This is the only approval gate in the flow: wait for the user's decision before completing. diff --git a/skills/subagents-orchestration-guide/SKILL.md b/skills/subagents-orchestration-guide/SKILL.md index 746b6c3..de351d5 100644 --- a/skills/subagents-orchestration-guide/SKILL.md +++ b/skills/subagents-orchestration-guide/SKILL.md @@ -85,7 +85,7 @@ Workflow coordination is flat: the orchestrator issues every specialist call and Apply these approval stops when producing or materially revising an artifact in the current workflow. A user instruction to proceed to a later phase accepts the preceding phases and authorizes entry into that phase; continue from that entry point rather than rechecking earlier review or approval records. In particular, a build instruction with an existing Work Plan grants batch approval for task materialization and implementation. **Use AskUserQuestion to present confirmations and questions.** -Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. +Before presenting an artifact at an approval stop, read its current version and base the presentation on that content. At the Design stop, also read the current PRD when present and state the confirmed user-visible outcome from it or the confirmed requirement context alongside major internal responsibility, contract, or refactoring changes in the approval presentation. | Phase | Stop Point | User Action Required | |-------|------------|---------------------| @@ -195,9 +195,9 @@ For Small, execute one direct-scope 4-step cycle. Complete after `approved`, or Reviewer findings are candidates. Create correction work only from the Review Resolution `apply` set. -**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to reconciliation reviewers. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. +**Fix-cycle handoff**: Apply Review Resolution and invoke each correction owner it selects. For an author-owned technical-artifact correction, invoke the layer-appropriate technical designer in update mode, run the artifact's existing document-reviewer and applicable design-sync gates, then re-run the originating reviewer. For an executor-owned correction, invoke the layer-appropriate executor with its original `task_file` or direct-scope fields plus `correction_findings` as the complete `apply` finding objects verbatim with only their dispositions added, then branch on the executor result through the per-task cycle's step 2, including its conditional integration-test-reviewer path, and run the applicable quality gate. When both owners are required, Review Resolution's author-first re-evaluation controls the order. Carry `prior_feedback` only to a reviewer or verifier being rechecked. Post-implementation corrections stay uncommitted through this cycle: the reviewers read the current working tree, so run the applicable quality gate and re-run the originating reviewer on the uncommitted changes, and commit the applied corrections once through Commit Boundary Check after the complete review set reaches Review Resolution convergence. -**Re-run rule**: After any applied post-implementation correction, re-run each reviewer with at least one correction applied from its latest result. Retain any other reviewer result completed by Post-Implementation Review Status Routing or Review Resolution only when repository evidence establishes that the correction preserved its review boundary; otherwise re-run that reviewer. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. +**Re-run rule**: After an applied post-implementation correction, re-run only the reviewer that owns a corrected finding from its latest result. Retain every passed reviewer result, including after another reviewer's correction. Pass the previous complete result, dispositions, and correction diff or paths to the rerun. After Specialist Result Acceptance recovers a blocked review prerequisite, re-run that reviewer. Review Resolution convergence governs acceptance and preserves resolved declines. ### Conditions for Stopping Autonomous Execution @@ -265,8 +265,8 @@ Before post-implementation verifiers, collect retained verification limitations - For a Design Doc, pass the codebase-analyzer JSON unchanged as `codebase_analysis`; accepted artifact paths and unchanged evidence keep the Design Doc traceable to reviewed sources rather than an orchestrator-authored shadow interpretation. Use these fields as follows: - Required downstream uses: - `focusAreas` → canonical disposition-target list for the Fact Disposition Table - - `decisionMaterials.reuse` and `invalidations` → reduce implementation surface and eliminate invalid approaches - - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters + - `simplifications`, `decisionMaterials.reuse`, and `invalidations` → reduce implementation surface and eliminate invalid approaches when their evidence and conditions apply + - `decisionMaterials.candidateDecisionPoints` → orchestrator first resolves them against the governing source, `simplifications`, `reuse`, and `invalidations`, then applies ADR Choice and Durability filters - `decisionMaterials.verification` → required proof boundaries - `dataModel`, `dataTransformationPipelines`, `qualityAssurance` → Existing Codebase Analysis / Verification Strategy / Quality Assurance sections @@ -280,7 +280,7 @@ Before post-implementation verifiers, collect retained verification limitations ### HC-04: code-verifier + codebase-analyzer → document-reviewer - Keep verifier discrepancies unchanged so correction and review remain traceable to observed evidence rather than orchestrator-authored design instructions. -- Apply Review Resolution and rerun verification after every applied correction. Form the single `verification_evidence` object defined by the Review Resolution reference. +- Apply Review Resolution and rerun verification after every applied correction, passing the previous complete verifier result, dispositions, and correction diff or paths as `prior_feedback`. Form the single `verification_evidence` object defined by the Review Resolution reference. - Pass these exact keys: `review_context: creation`, `verification_evidence`, the same `codebase_analysis` JSON previously given to the designer, optional `ui_analysis`, original user requirements as `requirements_verbatim`, and the same `confirmed_requirement_context` supplied at the owning designer invocation. - Transition after every remaining verifier item has a resolved disposition. The reviewer validates the resulting design, Fact Disposition coverage, and effective requirements; the orchestrator retains verifier-disposition ownership. diff --git a/skills/subagents-orchestration-guide/references/monorepo-flow.md b/skills/subagents-orchestration-guide/references/monorepo-flow.md index 5816473..e5a43d8 100644 --- a/skills/subagents-orchestration-guide/references/monorepo-flow.md +++ b/skills/subagents-orchestration-guide/references/monorepo-flow.md @@ -68,7 +68,7 @@ external_resource_refs: [selected references or []] ## ADR Qualification and Batch -After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. +After scope and any applicable UI Spec approval, resolve candidate decision points from the codebase analysis against the governing source, applicable `simplifications`, `reuse`, and `invalidations`. Use applicable UI analysis as supporting or contradicting evidence, not as a source of technical options. Apply documentation-criteria Choice then Durability filters only to the remaining points. - Route layer-owned decision points to the matching technical designer. - Route cross-layer points to technical-designer. @@ -111,7 +111,7 @@ Apply `code:` and `ui:` prefixes to respective Fact Disposition IDs. The fronten ## Verification Resolution -Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. +Keep verifier observations unchanged so corrections remain traceable to observed evidence rather than orchestrator-authored design instructions. Invoke code-verifier once per Design Doc with `doc_type: design-doc`; apply Review Resolution independently, forward each `apply` discrepancy verbatim with only its disposition, and rerun the affected verifier with its previous complete result, dispositions, and correction diff or paths as `prior_feedback`. Build one `verification_evidence` object per Design Doc from the latest result. Invoke document-reviewer with `review_context: creation`, `verification_evidence`, the same unchanged `codebase_analysis` and optional unchanged `ui_analysis`, original requirements as `requirements_verbatim`, and `confirmed_requirement_context` in the exact form fixed by the orchestration guide. After both document reviews permit approval, invoke design-sync with `source_design` as the frontend Design Doc path because it consumes backend integration contracts. Apply Review Resolution to actionable conflicts before the design approval stop. diff --git a/skills/subagents-orchestration-guide/references/review-resolution.md b/skills/subagents-orchestration-guide/references/review-resolution.md index 9926fea..201f3f7 100644 --- a/skills/subagents-orchestration-guide/references/review-resolution.md +++ b/skills/subagents-orchestration-guide/references/review-resolution.md @@ -1,6 +1,6 @@ # Review Resolution -Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. +Use this protocol when a deliverable reviewer or verifier returns findings that can route correction or progression. Correct evidenced defects within confirmed requirements, accepted design decisions, exclusions, and compatibility obligations, using existing responsibilities. Verification output used as evidence by a downstream specialist remains part of that specialist handoff. Preserve reviewer/verifier evidence ownership so each gate converges on the governing sources; orchestrator reinterpretation would create unreviewed requirements and make approval or reconciliation non-terminal. @@ -19,13 +19,13 @@ For verifier, design-sync, code-reviewer, security-reviewer, and integration-tes Use the result producer's declared verification mode: - **Reconciliation reviewer**: document-reviewer, code-reviewer, security-reviewer, and integration-test-reviewer accept `prior_feedback` and return `prior_feedback_reconciliation` after correction. -- **Fresh verifier**: code-verifier and design-sync independently report the current state from their original inputs. After a correction is applied from a fresh verifier's result, rerun that verifier and adjudicate the current result; a decline-only result is complete. +- **Bounded verifier**: code-verifier and design-sync accept the previous complete result, dispositions, and correction diff or paths as `prior_feedback`; code-verifier reruns with `unit_inventory` use full verification instead. Recheck the prior findings and inconsistencies directly introduced by the correction, and preserve unaffected evidence. A decline-only result is complete. ## 1. Assess Every Finding Before assigning a disposition, inspect the relevant parts of the current deliverable, cited repository evidence, and governing sources, treating reviewer assertions as evidence to verify. -When evidence shows that the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, leave Review Resolution and apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, leave Review Resolution and apply the parent workflow's authority gate. These workflow stops are not finding dispositions. +When a proposed correction remains within the agreed boundary above, select it from current evidence without expanding scope. When evidence shows the confirmed outcome cannot be achieved within accepted design decisions and existing responsibilities, leave Review Resolution and apply the parent workflow's existing design or requirement gate before changing them. When the confirmed outcome, desired-future requirements, and non-goals cannot all remain true and the user must choose which value boundary changes, apply the parent workflow's Requirement Change Detection. When correction requires authorization for an irreversible external action, apply the parent workflow's authority gate. These workflow exits are not finding dispositions; an optional expansion receives `decline`. The orchestrator records one disposition for every actionable finding: @@ -68,7 +68,7 @@ The correction assessment covers exactly every received item. The reviewer compl Derive the correction re-review status or verdict only from these reconciliation entries. An independent factual verifier may repeat an observed discrepancy; the orchestrator assigns its disposition from governing evidence. -For a fresh verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule requires a current-state result. The latest result replaces the prior current-state result for corrected items. Retain a prior decline when the latest result reports the materially same claim or conflict with unchanged governing evidence; adjudicate new or materially changed findings before routing. Match materially identical findings by their claim/conflict and cited source/target evidence rather than relying only on a regenerated positional ID. +For a bounded verifier, rerun after at least one correction is applied from its latest result or when the caller's re-run rule identifies a direct change to its declared boundary. Pass the previous complete result, dispositions, and correction diff or paths. The returned result replaces corrected items and carries unaffected evidence forward. Match materially identical findings by their claim or conflict and cited source and target evidence rather than a regenerated positional ID. A new finding enters routing only when its evidence links it causally to the correction. ## 3. Converge or Report @@ -78,7 +78,7 @@ Resolve correction re-review entries by their recorded `prior_disposition`: - `maintained` with `prior_disposition: apply` returns the original finding and the complete reconciliation entry verbatim through the same author or executor path, followed by another correction re-review; - `maintained` with `prior_disposition: decline` retains that decline and does not reopen the correction cycle. -For a fresh verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. +For a bounded verifier, a current finding with `apply` returns through the correction path, a current finding with a retained or newly assigned `decline` is complete, and an empty actionable result is complete. After the same `apply` finding remains material through two consecutive correction attempts, finish the correction cycle as incomplete and report the finding with its latest implementation and verification evidence. Apply the same terminal report to a required input or verification prerequisite that remains unavailable after in-scope recovery. Progress after every `apply` correction is complete and every other actionable finding has a `decline` disposition. The parent requirement and authority gates independently control their workflow stops. @@ -88,7 +88,8 @@ Handoffs contain this exact set: - initial reviewer or verifier inputs unchanged when rechecking; - complete `apply` finding objects verbatim, with only their orchestrator dispositions added; - the complete reconciliation entry when a maintained `apply` finding returns to its author or executor; -- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; for a fresh verifier, retain those dispositions in orchestrator state and compare them with the latest result as described above. +- declined IDs with reasons and evidence in `prior_feedback` when the next consumer accepts reviewer reconciliation; +- for a bounded verifier, the previous complete result and correction diff or paths in the same `prior_feedback` handoff. An author handoff contains no other orchestrator-authored semantic content.