From 92b51000885670f45de29046cc1f658d97342f38 Mon Sep 17 00:00:00 2001 From: Shinsuke Kagawa Date: Sun, 18 Oct 2026 06:15:44 +0900 Subject: [PATCH] fix: preserve symptom corrections through diagnosis Bump package and plugin versions to 0.29.1. --- .claude-plugin/marketplace.json | 8 +++---- agents/investigator.md | 6 +++--- agents/solver.md | 12 +++-------- agents/verifier.md | 11 ++++------ dev-skills/.claude-plugin/plugin.json | 2 +- .../.claude-plugin/plugin.json | 2 +- dev-workflows-frontend/agents/investigator.md | 6 +++--- dev-workflows-frontend/agents/solver.md | 12 +++-------- dev-workflows-frontend/agents/verifier.md | 11 ++++------ .../skills/recipe-diagnose/SKILL.md | 21 ++++++++++++------- .../.claude-plugin/plugin.json | 2 +- .../agents/investigator.md | 6 +++--- dev-workflows-fullstack/agents/solver.md | 12 +++-------- dev-workflows-fullstack/agents/verifier.md | 11 ++++------ .../skills/recipe-diagnose/SKILL.md | 21 ++++++++++++------- dev-workflows/.claude-plugin/plugin.json | 2 +- dev-workflows/agents/investigator.md | 6 +++--- dev-workflows/agents/solver.md | 12 +++-------- dev-workflows/agents/verifier.md | 11 ++++------ dev-workflows/skills/recipe-diagnose/SKILL.md | 21 ++++++++++++------- package.json | 2 +- skills/recipe-diagnose/SKILL.md | 21 ++++++++++++------- 22 files changed, 105 insertions(+), 113 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index db01d6d1..9375647a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "dev-workflows", "source": "./dev-workflows", "strict": true, - "version": "0.29.0", + "version": "0.29.1", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -80,7 +80,7 @@ "name": "dev-workflows-frontend", "source": "./dev-workflows-frontend", "strict": true, - "version": "0.29.0", + "version": "0.29.1", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -149,7 +149,7 @@ "name": "dev-workflows-fullstack", "source": "./dev-workflows-fullstack", "strict": true, - "version": "0.29.0", + "version": "0.29.1", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", "author": { "name": "Shinsuke Kagawa", @@ -235,7 +235,7 @@ "name": "dev-skills", "source": "./dev-skills", "strict": true, - "version": "0.29.0", + "version": "0.29.1", "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/investigator.md b/agents/investigator.md index 5817f8c8..c1260fbe 100644 --- a/agents/investigator.md +++ b/agents/investigator.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` -- **Unclear input**: Adopt the most reasonable interpretation and include "Investigation target: interpreted as ~" in output +- **Unclear input**: Distinguish reported facts from interpretations in `problemSummary`. Resolve target-changing uncertainty from available evidence; if unavailable, name the missing fact and its effect in `investigationLimitations` and continue unaffected investigation - **With investigationFocus input**: Collect evidence for each focus point and include in failurePoints or factualObservations - **With diagnosisScopeEnvelope input**: Investigate broadly within it and account for every item; include a newly discovered area only when it satisfies the supplied envelope's relationships and evidence shows it can change the supported cause set, coverage judgment, or counter-evidence - **Without investigationFocus input**: Execute standard investigation flow @@ -37,7 +37,7 @@ Solution derivation is out of scope for this agent. - Determine if the change is a "correct fix" or "new bug" (based on official documentation compliance, consistency with existing working code) - Select comparison baseline based on determination - Identify shared API/components between cause change and affected area -- Decompose the phenomenon and organize "since when", "under what conditions", "what scope" +- Use the current report and corrections to identify observed and expected behavior, location, trigger, conditions, and onset. Preserve unresolved facts in `problemSummary`; select investigation paths from evidence rather than an assumed screen or entrypoint - Search for comparison targets (working implementations using the same class/interface) ### Step 2: Information Collection @@ -102,7 +102,7 @@ For each failure point: Disclose unexplored areas and investigation limitations. -Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. For unavailable evidence, state whether it could change the supported cause set. +Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. In `scopeAccounting`, reference mapped node IDs and the evidence for their fault checks, including checks that found no fault; reference `failurePoints` for faults already recorded. Nodes may share an entry when the same evidence establishes their result. For unavailable evidence, state whether it could change the supported cause set. ## Evidence Strength Classification diff --git a/agents/solver.md b/agents/solver.md index 344d1c6d..432d3676 100644 --- a/agents/solver.md +++ b/agents/solver.md @@ -23,7 +23,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Output Scope -This agent outputs **solution derivation and recommendation presentation**. Proceed to solution derivation based on the given conclusion after verifying consistency with the user report. When the conclusion conflicts with user-reported symptoms or lacks supporting evidence, report the specific inconsistency and request additional verification. +This agent outputs **solution derivation and recommendation presentation**. Use the verified cause set to derive remedies for the current symptom and expected behavior in the supplied diagnosis scope envelope, or the available report for direct callers. Cause verification belongs to verifier; return `verification_required` if the supplied evidence exposes a material contradiction or missing prerequisite. ## Core Responsibilities @@ -52,11 +52,6 @@ This agent outputs **solution derivation and recommendation presentation**. Proc - Look for explicit semantic closure - Look for uncertainty-related descriptions -**User Report Consistency Check**: -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Do the failure points include design-level issues? -- If inconsistent, return `verification_required` with the exact mismatch and the verification needed to resolve it - **Approach Selection Based on impactAnalysis**: - Impact confined to one responsibility → Direct fix is sufficient unless another verified cause requires a broader mechanism - The same defect affects adjacent cases under one existing owner or contract → Compare direct correction with the smallest coordinated affected-area correction @@ -99,7 +94,7 @@ Select from the materially distinct approaches only after the verified `closed` ### Step 5: Implementation Steps Creation - Each step independently verifiable - Explicitly state dependencies between steps -- Define completion conditions for each step +- Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior - Include rollback procedures ## Output Format @@ -169,12 +164,11 @@ The first criterion applies to both statuses. All later criteria and Self-Valida - [ ] Created concrete implementation steps - [ ] Documented residual risks - [ ] Verified solutions align with project rules or best practices -- [ ] Verified input consistency with user report +- [ ] Proposed remedy and its verification address the current symptom and expected behavior ## Self-Validation [BLOCKING — before output] Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output. - [ ] Solution addresses the user's reported symptoms (not just the technical conclusion) -- [ ] Input failure points consistency with user report was verified before solution derivation - [ ] Each confirmed failure point has a corresponding fix in the implementation plan diff --git a/agents/verifier.md b/agents/verifier.md index a11c3636..c483651d 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results -- **Diagnosis scope envelope**: When supplied, use its recorded relationships as the semantic coverage boundary and verify every item within it is accounted for +- **Diagnosis scope envelope**: When supplied, use its current report and corrections as the symptom source independently of the investigator's interpretation, and its relationships as the semantic coverage boundary - **Text format**: Extract failure points and evidence for internal structuring. Verify within extractable scope - **No investigation results**: Mark as "No prior investigation" and attempt verification within input information scope - **Out of scope**: From-scratch information collection and solution proposals @@ -61,7 +61,7 @@ Record each supplementary finding with its impact on existing failure points. Check the upstream investigation's pathMap for completeness: 1. **Missing paths**: Are there code paths the symptom could traverse that the upstream investigation did not trace? (e.g., error handling branches, async forks, fallback paths) -2. **Unchecked nodes**: Are there nodes on traced paths that were not checked for faults? +2. **Unchecked nodes**: Do `scopeAccounting` and `failurePoints` provide evidence for the mapped nodes' fault checks, including no-fault judgments? Identify checks whose evidence is absent or invalid for the current symptom 3. **Adjacent cases**: When the investigation concerns a `bug-fix`, `regression`, `state-change`, or `boundary-change` (the debugging flow carries no Change Category field, so judge these from the investigation itself), are there cases sharing the same path, contract, persisted state, or external boundary that could carry the same fault? Trace all plausible adjacent cases, or explicitly justify any left untraced 4. **Additional failure points**: If missing paths, unchecked nodes, or adjacent cases reveal new faults, record them @@ -90,10 +90,7 @@ Evaluate every failure point independently and allow multiple confirmed failure | blocked | Cannot verify due to missing information (e.g., no runtime access) | | not_reached | Node exists on the path but could not be investigated | -**User Report Consistency**: Verify that the confirmed failure points are consistent with the user's report -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Was design_gap considered? -- If inconsistent, explicitly note "Investigation focus may be misaligned with user report" +**User Report Consistency**: Verify that the supported failure points together explain the current reported symptom, including its location, expected behavior, trigger, and conditions. Compare against the scope envelope's report and corrections when supplied; otherwise use the available report and identify material missing context. Record unexplained symptoms in `unresolvedSymptoms` and target mismatches in `identifiedGaps`. A material mismatch requires `gaps_remaining` with the exact re-investigation target, or `evidence_unavailable` when no available action can resolve it. **Conclusion**: Evaluate each failure point individually and retain every supported cause. For each pair of confirmed failure points, determine their relationship (independent / dependent / same_chain) and record it in `failurePointRelationships` @@ -107,7 +104,7 @@ Evaluate every failure point independently and allow multiple confirmed failure Set `coverageDisposition` independently: -- `closed`: the sufficient criteria hold. +- `closed`: the sufficient criteria hold and the supported cause set explains the current reported symptom without a material unresolved mismatch. - `gaps_remaining`: an accessible named gap could materially change the cause set; identify the precise next investigation target. - `evidence_unavailable`: unavailable evidence could materially change the cause set and no available investigation action can close it; identify the unavailable evidence and attempted recovery. diff --git a/dev-skills/.claude-plugin/plugin.json b/dev-skills/.claude-plugin/plugin.json index be1dd8fe..789e45d1 100644 --- a/dev-skills/.claude-plugin/plugin.json +++ b/dev-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-skills", "description": "Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents", - "version": "0.29.0", + "version": "0.29.1", "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 78258979..50e187c0 100644 --- a/dev-workflows-frontend/.claude-plugin/plugin.json +++ b/dev-workflows-frontend/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-frontend", "description": "Skills + Subagents for React/TypeScript - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.0", + "version": "0.29.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-frontend/agents/investigator.md b/dev-workflows-frontend/agents/investigator.md index 5817f8c8..c1260fbe 100644 --- a/dev-workflows-frontend/agents/investigator.md +++ b/dev-workflows-frontend/agents/investigator.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` -- **Unclear input**: Adopt the most reasonable interpretation and include "Investigation target: interpreted as ~" in output +- **Unclear input**: Distinguish reported facts from interpretations in `problemSummary`. Resolve target-changing uncertainty from available evidence; if unavailable, name the missing fact and its effect in `investigationLimitations` and continue unaffected investigation - **With investigationFocus input**: Collect evidence for each focus point and include in failurePoints or factualObservations - **With diagnosisScopeEnvelope input**: Investigate broadly within it and account for every item; include a newly discovered area only when it satisfies the supplied envelope's relationships and evidence shows it can change the supported cause set, coverage judgment, or counter-evidence - **Without investigationFocus input**: Execute standard investigation flow @@ -37,7 +37,7 @@ Solution derivation is out of scope for this agent. - Determine if the change is a "correct fix" or "new bug" (based on official documentation compliance, consistency with existing working code) - Select comparison baseline based on determination - Identify shared API/components between cause change and affected area -- Decompose the phenomenon and organize "since when", "under what conditions", "what scope" +- Use the current report and corrections to identify observed and expected behavior, location, trigger, conditions, and onset. Preserve unresolved facts in `problemSummary`; select investigation paths from evidence rather than an assumed screen or entrypoint - Search for comparison targets (working implementations using the same class/interface) ### Step 2: Information Collection @@ -102,7 +102,7 @@ For each failure point: Disclose unexplored areas and investigation limitations. -Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. For unavailable evidence, state whether it could change the supported cause set. +Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. In `scopeAccounting`, reference mapped node IDs and the evidence for their fault checks, including checks that found no fault; reference `failurePoints` for faults already recorded. Nodes may share an entry when the same evidence establishes their result. For unavailable evidence, state whether it could change the supported cause set. ## Evidence Strength Classification diff --git a/dev-workflows-frontend/agents/solver.md b/dev-workflows-frontend/agents/solver.md index 344d1c6d..432d3676 100644 --- a/dev-workflows-frontend/agents/solver.md +++ b/dev-workflows-frontend/agents/solver.md @@ -23,7 +23,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Output Scope -This agent outputs **solution derivation and recommendation presentation**. Proceed to solution derivation based on the given conclusion after verifying consistency with the user report. When the conclusion conflicts with user-reported symptoms or lacks supporting evidence, report the specific inconsistency and request additional verification. +This agent outputs **solution derivation and recommendation presentation**. Use the verified cause set to derive remedies for the current symptom and expected behavior in the supplied diagnosis scope envelope, or the available report for direct callers. Cause verification belongs to verifier; return `verification_required` if the supplied evidence exposes a material contradiction or missing prerequisite. ## Core Responsibilities @@ -52,11 +52,6 @@ This agent outputs **solution derivation and recommendation presentation**. Proc - Look for explicit semantic closure - Look for uncertainty-related descriptions -**User Report Consistency Check**: -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Do the failure points include design-level issues? -- If inconsistent, return `verification_required` with the exact mismatch and the verification needed to resolve it - **Approach Selection Based on impactAnalysis**: - Impact confined to one responsibility → Direct fix is sufficient unless another verified cause requires a broader mechanism - The same defect affects adjacent cases under one existing owner or contract → Compare direct correction with the smallest coordinated affected-area correction @@ -99,7 +94,7 @@ Select from the materially distinct approaches only after the verified `closed` ### Step 5: Implementation Steps Creation - Each step independently verifiable - Explicitly state dependencies between steps -- Define completion conditions for each step +- Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior - Include rollback procedures ## Output Format @@ -169,12 +164,11 @@ The first criterion applies to both statuses. All later criteria and Self-Valida - [ ] Created concrete implementation steps - [ ] Documented residual risks - [ ] Verified solutions align with project rules or best practices -- [ ] Verified input consistency with user report +- [ ] Proposed remedy and its verification address the current symptom and expected behavior ## Self-Validation [BLOCKING — before output] Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output. - [ ] Solution addresses the user's reported symptoms (not just the technical conclusion) -- [ ] Input failure points consistency with user report was verified before solution derivation - [ ] Each confirmed failure point has a corresponding fix in the implementation plan diff --git a/dev-workflows-frontend/agents/verifier.md b/dev-workflows-frontend/agents/verifier.md index a11c3636..c483651d 100644 --- a/dev-workflows-frontend/agents/verifier.md +++ b/dev-workflows-frontend/agents/verifier.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results -- **Diagnosis scope envelope**: When supplied, use its recorded relationships as the semantic coverage boundary and verify every item within it is accounted for +- **Diagnosis scope envelope**: When supplied, use its current report and corrections as the symptom source independently of the investigator's interpretation, and its relationships as the semantic coverage boundary - **Text format**: Extract failure points and evidence for internal structuring. Verify within extractable scope - **No investigation results**: Mark as "No prior investigation" and attempt verification within input information scope - **Out of scope**: From-scratch information collection and solution proposals @@ -61,7 +61,7 @@ Record each supplementary finding with its impact on existing failure points. Check the upstream investigation's pathMap for completeness: 1. **Missing paths**: Are there code paths the symptom could traverse that the upstream investigation did not trace? (e.g., error handling branches, async forks, fallback paths) -2. **Unchecked nodes**: Are there nodes on traced paths that were not checked for faults? +2. **Unchecked nodes**: Do `scopeAccounting` and `failurePoints` provide evidence for the mapped nodes' fault checks, including no-fault judgments? Identify checks whose evidence is absent or invalid for the current symptom 3. **Adjacent cases**: When the investigation concerns a `bug-fix`, `regression`, `state-change`, or `boundary-change` (the debugging flow carries no Change Category field, so judge these from the investigation itself), are there cases sharing the same path, contract, persisted state, or external boundary that could carry the same fault? Trace all plausible adjacent cases, or explicitly justify any left untraced 4. **Additional failure points**: If missing paths, unchecked nodes, or adjacent cases reveal new faults, record them @@ -90,10 +90,7 @@ Evaluate every failure point independently and allow multiple confirmed failure | blocked | Cannot verify due to missing information (e.g., no runtime access) | | not_reached | Node exists on the path but could not be investigated | -**User Report Consistency**: Verify that the confirmed failure points are consistent with the user's report -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Was design_gap considered? -- If inconsistent, explicitly note "Investigation focus may be misaligned with user report" +**User Report Consistency**: Verify that the supported failure points together explain the current reported symptom, including its location, expected behavior, trigger, and conditions. Compare against the scope envelope's report and corrections when supplied; otherwise use the available report and identify material missing context. Record unexplained symptoms in `unresolvedSymptoms` and target mismatches in `identifiedGaps`. A material mismatch requires `gaps_remaining` with the exact re-investigation target, or `evidence_unavailable` when no available action can resolve it. **Conclusion**: Evaluate each failure point individually and retain every supported cause. For each pair of confirmed failure points, determine their relationship (independent / dependent / same_chain) and record it in `failurePointRelationships` @@ -107,7 +104,7 @@ Evaluate every failure point independently and allow multiple confirmed failure Set `coverageDisposition` independently: -- `closed`: the sufficient criteria hold. +- `closed`: the sufficient criteria hold and the supported cause set explains the current reported symptom without a material unresolved mismatch. - `gaps_remaining`: an accessible named gap could materially change the cause set; identify the precise next investigation target. - `evidence_unavailable`: unavailable evidence could materially change the cause set and no available investigation action can close it; identify the unavailable evidence and attempted recovery. diff --git a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md index 5d20b895..25c5da5e 100644 --- a/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-frontend/skills/recipe-diagnose/SKILL.md @@ -34,7 +34,8 @@ At each Agent invocation below, build the prompt as a mechanical extraction: cop Define a semantic scope envelope from the reported problem and repository evidence by recording: -- phenomenon and occurrence conditions to explain +- the user's symptom report and corrections verbatim, with linked evidence; distinguish these from investigation interpretations +- observed and expected behavior, observed location, trigger, occurrence conditions, and onset when known; mark unresolved facts rather than selecting a location or condition by plausibility - symptom-reachable execution paths and adjacent cases that share the same path, contract, persisted state, or external boundary - applicable evidence axes: code, history, dependencies, configuration, governing documents, and external specifications - explicit exclusions from the user or governing artifacts @@ -42,6 +43,10 @@ Define a semantic scope envelope from the reported problem and repository eviden The envelope bounds relevance. Keep every relationship above active throughout investigation, including after a plausible cause appears. +Resolve facts that change the investigation target from available evidence. Ask the user only for a target-changing fact that the investigation cannot obtain; continue unaffected investigation. + +When the user corrects the symptom's location, expected behavior, timing, or conditions, update this envelope and return to path mapping for the corrected symptom. Re-evaluate affected exclusions and failure points through investigator and verifier before invoking solver. Retain evidence that remains valid; prior coverage closure applies only to the symptom and evidence it verified. When new information only adds evidence for the same symptom, reopen only the judgments it affects. + ## Diagnosis Flow Overview ``` @@ -53,7 +58,7 @@ coverage closed → design decision gate when applicable → solver → Report material evidence unavailable → limitation/block report ``` -**Context Separation**: Pass only structured JSON output to each step. Each step starts fresh with the JSON data only. +**Context Separation**: Each specialist starts fresh with the current diagnosis scope envelope and the structured results named in its invocation. The envelope supplies the user's report independently of upstream interpretations. ## Execution Steps @@ -66,8 +71,7 @@ description: "Investigate problem" prompt: | Comprehensively collect information related to the following phenomenon. - Phenomenon: [Problem reported by user verbatim] - diagnosisScopeEnvelope: [Step 0 semantic scope envelope] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] ``` **Expected output**: scopeAccounting, pathMap (execution paths per symptom), failurePoints (faults found at each node), impactAnalysis per failure point, unexplored areas, investigation limitations @@ -91,6 +95,8 @@ prompt: | Re-investigate with focus on the following gaps: - Missing: [unsatisfied Step 2 Quality Check items, copied as written] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] + Use these previous investigation results as context and investigate only the gaps listed above. Return one updated complete investigation JSON, retaining prior evidence that remains valid: [Previous investigation JSON] ``` @@ -105,7 +111,7 @@ subagent_type: verifier description: "Verify investigation results" prompt: Verify the following investigation results against the semantic diagnosis scope envelope. -diagnosisScopeEnvelope: [Step 0 semantic scope envelope] +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Investigation results: [Investigation JSON output] ``` @@ -121,8 +127,8 @@ Investigation results: [Investigation JSON output] Branch on verifier output before invoking solver: -- `coverageDisposition: closed`: freeze the complete verified cause set and continue to the applicable design decision gate. -- `coverageDisposition: gaps_remaining`: return to Step 1 with only verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Keep `scopeAccounting` monotonic by preserving every accounted item. Add a gap only when new evidence identifies a distinct previously unaccounted gap within the semantic scope envelope that can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. +- `coverageDisposition: closed`: carry the complete verified cause set forward to the solution boundary, subject to Step 0's symptom and evidence updates. +- `coverageDisposition: gaps_remaining`: return to Step 1 with the current scope envelope, verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Preserve accounted items whose evidence remains valid. Investigate gaps or reopen judgments only when the current symptom or new evidence can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. - `coverageDisposition: evidence_unavailable`: finish with the unavailable-evidence report, including the evidence, attempted recovery, and why it can change the cause set. Continue investigation while an available action can advance a material gap. Completion is determined by verifier-established semantic closure or by confirmation that no available action can advance the gap. @@ -139,6 +145,7 @@ subagent_type: solver description: "Derive solutions" prompt: Derive solutions based on the following verified failure points. +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Confirmed failure points: [verifier's conclusion.confirmedFailurePoints] Refuted failure points: [verifier's conclusion.refutedFailurePoints] Failure point relationships: [verifier's conclusion.failurePointRelationships] diff --git a/dev-workflows-fullstack/.claude-plugin/plugin.json b/dev-workflows-fullstack/.claude-plugin/plugin.json index e075150f..955c6a34 100644 --- a/dev-workflows-fullstack/.claude-plugin/plugin.json +++ b/dev-workflows-fullstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows-fullstack", "description": "Skills + Subagents for fullstack development (backend + React/TypeScript) - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.0", + "version": "0.29.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows-fullstack/agents/investigator.md b/dev-workflows-fullstack/agents/investigator.md index 5817f8c8..c1260fbe 100644 --- a/dev-workflows-fullstack/agents/investigator.md +++ b/dev-workflows-fullstack/agents/investigator.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` -- **Unclear input**: Adopt the most reasonable interpretation and include "Investigation target: interpreted as ~" in output +- **Unclear input**: Distinguish reported facts from interpretations in `problemSummary`. Resolve target-changing uncertainty from available evidence; if unavailable, name the missing fact and its effect in `investigationLimitations` and continue unaffected investigation - **With investigationFocus input**: Collect evidence for each focus point and include in failurePoints or factualObservations - **With diagnosisScopeEnvelope input**: Investigate broadly within it and account for every item; include a newly discovered area only when it satisfies the supplied envelope's relationships and evidence shows it can change the supported cause set, coverage judgment, or counter-evidence - **Without investigationFocus input**: Execute standard investigation flow @@ -37,7 +37,7 @@ Solution derivation is out of scope for this agent. - Determine if the change is a "correct fix" or "new bug" (based on official documentation compliance, consistency with existing working code) - Select comparison baseline based on determination - Identify shared API/components between cause change and affected area -- Decompose the phenomenon and organize "since when", "under what conditions", "what scope" +- Use the current report and corrections to identify observed and expected behavior, location, trigger, conditions, and onset. Preserve unresolved facts in `problemSummary`; select investigation paths from evidence rather than an assumed screen or entrypoint - Search for comparison targets (working implementations using the same class/interface) ### Step 2: Information Collection @@ -102,7 +102,7 @@ For each failure point: Disclose unexplored areas and investigation limitations. -Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. For unavailable evidence, state whether it could change the supported cause set. +Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. In `scopeAccounting`, reference mapped node IDs and the evidence for their fault checks, including checks that found no fault; reference `failurePoints` for faults already recorded. Nodes may share an entry when the same evidence establishes their result. For unavailable evidence, state whether it could change the supported cause set. ## Evidence Strength Classification diff --git a/dev-workflows-fullstack/agents/solver.md b/dev-workflows-fullstack/agents/solver.md index 344d1c6d..432d3676 100644 --- a/dev-workflows-fullstack/agents/solver.md +++ b/dev-workflows-fullstack/agents/solver.md @@ -23,7 +23,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Output Scope -This agent outputs **solution derivation and recommendation presentation**. Proceed to solution derivation based on the given conclusion after verifying consistency with the user report. When the conclusion conflicts with user-reported symptoms or lacks supporting evidence, report the specific inconsistency and request additional verification. +This agent outputs **solution derivation and recommendation presentation**. Use the verified cause set to derive remedies for the current symptom and expected behavior in the supplied diagnosis scope envelope, or the available report for direct callers. Cause verification belongs to verifier; return `verification_required` if the supplied evidence exposes a material contradiction or missing prerequisite. ## Core Responsibilities @@ -52,11 +52,6 @@ This agent outputs **solution derivation and recommendation presentation**. Proc - Look for explicit semantic closure - Look for uncertainty-related descriptions -**User Report Consistency Check**: -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Do the failure points include design-level issues? -- If inconsistent, return `verification_required` with the exact mismatch and the verification needed to resolve it - **Approach Selection Based on impactAnalysis**: - Impact confined to one responsibility → Direct fix is sufficient unless another verified cause requires a broader mechanism - The same defect affects adjacent cases under one existing owner or contract → Compare direct correction with the smallest coordinated affected-area correction @@ -99,7 +94,7 @@ Select from the materially distinct approaches only after the verified `closed` ### Step 5: Implementation Steps Creation - Each step independently verifiable - Explicitly state dependencies between steps -- Define completion conditions for each step +- Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior - Include rollback procedures ## Output Format @@ -169,12 +164,11 @@ The first criterion applies to both statuses. All later criteria and Self-Valida - [ ] Created concrete implementation steps - [ ] Documented residual risks - [ ] Verified solutions align with project rules or best practices -- [ ] Verified input consistency with user report +- [ ] Proposed remedy and its verification address the current symptom and expected behavior ## Self-Validation [BLOCKING — before output] Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output. - [ ] Solution addresses the user's reported symptoms (not just the technical conclusion) -- [ ] Input failure points consistency with user report was verified before solution derivation - [ ] Each confirmed failure point has a corresponding fix in the implementation plan diff --git a/dev-workflows-fullstack/agents/verifier.md b/dev-workflows-fullstack/agents/verifier.md index a11c3636..c483651d 100644 --- a/dev-workflows-fullstack/agents/verifier.md +++ b/dev-workflows-fullstack/agents/verifier.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results -- **Diagnosis scope envelope**: When supplied, use its recorded relationships as the semantic coverage boundary and verify every item within it is accounted for +- **Diagnosis scope envelope**: When supplied, use its current report and corrections as the symptom source independently of the investigator's interpretation, and its relationships as the semantic coverage boundary - **Text format**: Extract failure points and evidence for internal structuring. Verify within extractable scope - **No investigation results**: Mark as "No prior investigation" and attempt verification within input information scope - **Out of scope**: From-scratch information collection and solution proposals @@ -61,7 +61,7 @@ Record each supplementary finding with its impact on existing failure points. Check the upstream investigation's pathMap for completeness: 1. **Missing paths**: Are there code paths the symptom could traverse that the upstream investigation did not trace? (e.g., error handling branches, async forks, fallback paths) -2. **Unchecked nodes**: Are there nodes on traced paths that were not checked for faults? +2. **Unchecked nodes**: Do `scopeAccounting` and `failurePoints` provide evidence for the mapped nodes' fault checks, including no-fault judgments? Identify checks whose evidence is absent or invalid for the current symptom 3. **Adjacent cases**: When the investigation concerns a `bug-fix`, `regression`, `state-change`, or `boundary-change` (the debugging flow carries no Change Category field, so judge these from the investigation itself), are there cases sharing the same path, contract, persisted state, or external boundary that could carry the same fault? Trace all plausible adjacent cases, or explicitly justify any left untraced 4. **Additional failure points**: If missing paths, unchecked nodes, or adjacent cases reveal new faults, record them @@ -90,10 +90,7 @@ Evaluate every failure point independently and allow multiple confirmed failure | blocked | Cannot verify due to missing information (e.g., no runtime access) | | not_reached | Node exists on the path but could not be investigated | -**User Report Consistency**: Verify that the confirmed failure points are consistent with the user's report -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Was design_gap considered? -- If inconsistent, explicitly note "Investigation focus may be misaligned with user report" +**User Report Consistency**: Verify that the supported failure points together explain the current reported symptom, including its location, expected behavior, trigger, and conditions. Compare against the scope envelope's report and corrections when supplied; otherwise use the available report and identify material missing context. Record unexplained symptoms in `unresolvedSymptoms` and target mismatches in `identifiedGaps`. A material mismatch requires `gaps_remaining` with the exact re-investigation target, or `evidence_unavailable` when no available action can resolve it. **Conclusion**: Evaluate each failure point individually and retain every supported cause. For each pair of confirmed failure points, determine their relationship (independent / dependent / same_chain) and record it in `failurePointRelationships` @@ -107,7 +104,7 @@ Evaluate every failure point independently and allow multiple confirmed failure Set `coverageDisposition` independently: -- `closed`: the sufficient criteria hold. +- `closed`: the sufficient criteria hold and the supported cause set explains the current reported symptom without a material unresolved mismatch. - `gaps_remaining`: an accessible named gap could materially change the cause set; identify the precise next investigation target. - `evidence_unavailable`: unavailable evidence could materially change the cause set and no available investigation action can close it; identify the unavailable evidence and attempted recovery. diff --git a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md index 5d20b895..25c5da5e 100644 --- a/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows-fullstack/skills/recipe-diagnose/SKILL.md @@ -34,7 +34,8 @@ At each Agent invocation below, build the prompt as a mechanical extraction: cop Define a semantic scope envelope from the reported problem and repository evidence by recording: -- phenomenon and occurrence conditions to explain +- the user's symptom report and corrections verbatim, with linked evidence; distinguish these from investigation interpretations +- observed and expected behavior, observed location, trigger, occurrence conditions, and onset when known; mark unresolved facts rather than selecting a location or condition by plausibility - symptom-reachable execution paths and adjacent cases that share the same path, contract, persisted state, or external boundary - applicable evidence axes: code, history, dependencies, configuration, governing documents, and external specifications - explicit exclusions from the user or governing artifacts @@ -42,6 +43,10 @@ Define a semantic scope envelope from the reported problem and repository eviden The envelope bounds relevance. Keep every relationship above active throughout investigation, including after a plausible cause appears. +Resolve facts that change the investigation target from available evidence. Ask the user only for a target-changing fact that the investigation cannot obtain; continue unaffected investigation. + +When the user corrects the symptom's location, expected behavior, timing, or conditions, update this envelope and return to path mapping for the corrected symptom. Re-evaluate affected exclusions and failure points through investigator and verifier before invoking solver. Retain evidence that remains valid; prior coverage closure applies only to the symptom and evidence it verified. When new information only adds evidence for the same symptom, reopen only the judgments it affects. + ## Diagnosis Flow Overview ``` @@ -53,7 +58,7 @@ coverage closed → design decision gate when applicable → solver → Report material evidence unavailable → limitation/block report ``` -**Context Separation**: Pass only structured JSON output to each step. Each step starts fresh with the JSON data only. +**Context Separation**: Each specialist starts fresh with the current diagnosis scope envelope and the structured results named in its invocation. The envelope supplies the user's report independently of upstream interpretations. ## Execution Steps @@ -66,8 +71,7 @@ description: "Investigate problem" prompt: | Comprehensively collect information related to the following phenomenon. - Phenomenon: [Problem reported by user verbatim] - diagnosisScopeEnvelope: [Step 0 semantic scope envelope] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] ``` **Expected output**: scopeAccounting, pathMap (execution paths per symptom), failurePoints (faults found at each node), impactAnalysis per failure point, unexplored areas, investigation limitations @@ -91,6 +95,8 @@ prompt: | Re-investigate with focus on the following gaps: - Missing: [unsatisfied Step 2 Quality Check items, copied as written] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] + Use these previous investigation results as context and investigate only the gaps listed above. Return one updated complete investigation JSON, retaining prior evidence that remains valid: [Previous investigation JSON] ``` @@ -105,7 +111,7 @@ subagent_type: verifier description: "Verify investigation results" prompt: Verify the following investigation results against the semantic diagnosis scope envelope. -diagnosisScopeEnvelope: [Step 0 semantic scope envelope] +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Investigation results: [Investigation JSON output] ``` @@ -121,8 +127,8 @@ Investigation results: [Investigation JSON output] Branch on verifier output before invoking solver: -- `coverageDisposition: closed`: freeze the complete verified cause set and continue to the applicable design decision gate. -- `coverageDisposition: gaps_remaining`: return to Step 1 with only verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Keep `scopeAccounting` monotonic by preserving every accounted item. Add a gap only when new evidence identifies a distinct previously unaccounted gap within the semantic scope envelope that can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. +- `coverageDisposition: closed`: carry the complete verified cause set forward to the solution boundary, subject to Step 0's symptom and evidence updates. +- `coverageDisposition: gaps_remaining`: return to Step 1 with the current scope envelope, verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Preserve accounted items whose evidence remains valid. Investigate gaps or reopen judgments only when the current symptom or new evidence can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. - `coverageDisposition: evidence_unavailable`: finish with the unavailable-evidence report, including the evidence, attempted recovery, and why it can change the cause set. Continue investigation while an available action can advance a material gap. Completion is determined by verifier-established semantic closure or by confirmation that no available action can advance the gap. @@ -139,6 +145,7 @@ subagent_type: solver description: "Derive solutions" prompt: Derive solutions based on the following verified failure points. +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Confirmed failure points: [verifier's conclusion.confirmedFailurePoints] Refuted failure points: [verifier's conclusion.refutedFailurePoints] Failure point relationships: [verifier's conclusion.failurePointRelationships] diff --git a/dev-workflows/.claude-plugin/plugin.json b/dev-workflows/.claude-plugin/plugin.json index 3f1c4060..4ead3b9a 100644 --- a/dev-workflows/.claude-plugin/plugin.json +++ b/dev-workflows/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflows", "description": "Skills + Subagents for backend development - Use skills for coding guidance, or run recipe workflows for full orchestrated agentic coding with specialized agents", - "version": "0.29.0", + "version": "0.29.1", "author": { "name": "Shinsuke Kagawa", "url": "https://github.com/shinpr" diff --git a/dev-workflows/agents/investigator.md b/dev-workflows/agents/investigator.md index 5817f8c8..c1260fbe 100644 --- a/dev-workflows/agents/investigator.md +++ b/dev-workflows/agents/investigator.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Accepts both text and JSON formats. For JSON, use `problemSummary` -- **Unclear input**: Adopt the most reasonable interpretation and include "Investigation target: interpreted as ~" in output +- **Unclear input**: Distinguish reported facts from interpretations in `problemSummary`. Resolve target-changing uncertainty from available evidence; if unavailable, name the missing fact and its effect in `investigationLimitations` and continue unaffected investigation - **With investigationFocus input**: Collect evidence for each focus point and include in failurePoints or factualObservations - **With diagnosisScopeEnvelope input**: Investigate broadly within it and account for every item; include a newly discovered area only when it satisfies the supplied envelope's relationships and evidence shows it can change the supported cause set, coverage judgment, or counter-evidence - **Without investigationFocus input**: Execute standard investigation flow @@ -37,7 +37,7 @@ Solution derivation is out of scope for this agent. - Determine if the change is a "correct fix" or "new bug" (based on official documentation compliance, consistency with existing working code) - Select comparison baseline based on determination - Identify shared API/components between cause change and affected area -- Decompose the phenomenon and organize "since when", "under what conditions", "what scope" +- Use the current report and corrections to identify observed and expected behavior, location, trigger, conditions, and onset. Preserve unresolved facts in `problemSummary`; select investigation paths from evidence rather than an assumed screen or entrypoint - Search for comparison targets (working implementations using the same class/interface) ### Step 2: Information Collection @@ -102,7 +102,7 @@ For each failure point: Disclose unexplored areas and investigation limitations. -Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. For unavailable evidence, state whether it could change the supported cause set. +Before output, account for every diagnosis-scope item as investigated, excluded by an explicit governing boundary, or unavailable. In `scopeAccounting`, reference mapped node IDs and the evidence for their fault checks, including checks that found no fault; reference `failurePoints` for faults already recorded. Nodes may share an entry when the same evidence establishes their result. For unavailable evidence, state whether it could change the supported cause set. ## Evidence Strength Classification diff --git a/dev-workflows/agents/solver.md b/dev-workflows/agents/solver.md index 344d1c6d..432d3676 100644 --- a/dev-workflows/agents/solver.md +++ b/dev-workflows/agents/solver.md @@ -23,7 +23,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Output Scope -This agent outputs **solution derivation and recommendation presentation**. Proceed to solution derivation based on the given conclusion after verifying consistency with the user report. When the conclusion conflicts with user-reported symptoms or lacks supporting evidence, report the specific inconsistency and request additional verification. +This agent outputs **solution derivation and recommendation presentation**. Use the verified cause set to derive remedies for the current symptom and expected behavior in the supplied diagnosis scope envelope, or the available report for direct callers. Cause verification belongs to verifier; return `verification_required` if the supplied evidence exposes a material contradiction or missing prerequisite. ## Core Responsibilities @@ -52,11 +52,6 @@ This agent outputs **solution derivation and recommendation presentation**. Proc - Look for explicit semantic closure - Look for uncertainty-related descriptions -**User Report Consistency Check**: -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Do the failure points include design-level issues? -- If inconsistent, return `verification_required` with the exact mismatch and the verification needed to resolve it - **Approach Selection Based on impactAnalysis**: - Impact confined to one responsibility → Direct fix is sufficient unless another verified cause requires a broader mechanism - The same defect affects adjacent cases under one existing owner or contract → Compare direct correction with the smallest coordinated affected-area correction @@ -99,7 +94,7 @@ Select from the materially distinct approaches only after the verified `closed` ### Step 5: Implementation Steps Creation - Each step independently verifiable - Explicitly state dependencies between steps -- Define completion conditions for each step +- Define completion conditions for each step and the observable check that the original symptom is resolved under its reported trigger and conditions, preserving the expected behavior - Include rollback procedures ## Output Format @@ -169,12 +164,11 @@ The first criterion applies to both statuses. All later criteria and Self-Valida - [ ] Created concrete implementation steps - [ ] Documented residual risks - [ ] Verified solutions align with project rules or best practices -- [ ] Verified input consistency with user report +- [ ] Proposed remedy and its verification address the current symptom and expected behavior ## Self-Validation [BLOCKING — before output] Run each item below before producing the final JSON. When any item is unsatisfied, return to the relevant Step and complete it before producing the JSON output. - [ ] Solution addresses the user's reported symptoms (not just the technical conclusion) -- [ ] Input failure points consistency with user report was verified before solution derivation - [ ] Each confirmed failure point has a corresponding fix in the implementation plan diff --git a/dev-workflows/agents/verifier.md b/dev-workflows/agents/verifier.md index a11c3636..c483651d 100644 --- a/dev-workflows/agents/verifier.md +++ b/dev-workflows/agents/verifier.md @@ -16,7 +16,7 @@ Before acting, map the preloaded skills to concrete rules for this task. Follow ## Input and Responsibility Boundaries - **Input**: Structured investigation results (JSON) or text format investigation results -- **Diagnosis scope envelope**: When supplied, use its recorded relationships as the semantic coverage boundary and verify every item within it is accounted for +- **Diagnosis scope envelope**: When supplied, use its current report and corrections as the symptom source independently of the investigator's interpretation, and its relationships as the semantic coverage boundary - **Text format**: Extract failure points and evidence for internal structuring. Verify within extractable scope - **No investigation results**: Mark as "No prior investigation" and attempt verification within input information scope - **Out of scope**: From-scratch information collection and solution proposals @@ -61,7 +61,7 @@ Record each supplementary finding with its impact on existing failure points. Check the upstream investigation's pathMap for completeness: 1. **Missing paths**: Are there code paths the symptom could traverse that the upstream investigation did not trace? (e.g., error handling branches, async forks, fallback paths) -2. **Unchecked nodes**: Are there nodes on traced paths that were not checked for faults? +2. **Unchecked nodes**: Do `scopeAccounting` and `failurePoints` provide evidence for the mapped nodes' fault checks, including no-fault judgments? Identify checks whose evidence is absent or invalid for the current symptom 3. **Adjacent cases**: When the investigation concerns a `bug-fix`, `regression`, `state-change`, or `boundary-change` (the debugging flow carries no Change Category field, so judge these from the investigation itself), are there cases sharing the same path, contract, persisted state, or external boundary that could carry the same fault? Trace all plausible adjacent cases, or explicitly justify any left untraced 4. **Additional failure points**: If missing paths, unchecked nodes, or adjacent cases reveal new faults, record them @@ -90,10 +90,7 @@ Evaluate every failure point independently and allow multiple confirmed failure | blocked | Cannot verify due to missing information (e.g., no runtime access) | | not_reached | Node exists on the path but could not be investigated | -**User Report Consistency**: Verify that the confirmed failure points are consistent with the user's report -- Example: "I changed A and B broke" → Do the failure points explain that causal relationship? -- Example: "The implementation is wrong" → Was design_gap considered? -- If inconsistent, explicitly note "Investigation focus may be misaligned with user report" +**User Report Consistency**: Verify that the supported failure points together explain the current reported symptom, including its location, expected behavior, trigger, and conditions. Compare against the scope envelope's report and corrections when supplied; otherwise use the available report and identify material missing context. Record unexplained symptoms in `unresolvedSymptoms` and target mismatches in `identifiedGaps`. A material mismatch requires `gaps_remaining` with the exact re-investigation target, or `evidence_unavailable` when no available action can resolve it. **Conclusion**: Evaluate each failure point individually and retain every supported cause. For each pair of confirmed failure points, determine their relationship (independent / dependent / same_chain) and record it in `failurePointRelationships` @@ -107,7 +104,7 @@ Evaluate every failure point independently and allow multiple confirmed failure Set `coverageDisposition` independently: -- `closed`: the sufficient criteria hold. +- `closed`: the sufficient criteria hold and the supported cause set explains the current reported symptom without a material unresolved mismatch. - `gaps_remaining`: an accessible named gap could materially change the cause set; identify the precise next investigation target. - `evidence_unavailable`: unavailable evidence could materially change the cause set and no available investigation action can close it; identify the unavailable evidence and attempted recovery. diff --git a/dev-workflows/skills/recipe-diagnose/SKILL.md b/dev-workflows/skills/recipe-diagnose/SKILL.md index 5d20b895..25c5da5e 100644 --- a/dev-workflows/skills/recipe-diagnose/SKILL.md +++ b/dev-workflows/skills/recipe-diagnose/SKILL.md @@ -34,7 +34,8 @@ At each Agent invocation below, build the prompt as a mechanical extraction: cop Define a semantic scope envelope from the reported problem and repository evidence by recording: -- phenomenon and occurrence conditions to explain +- the user's symptom report and corrections verbatim, with linked evidence; distinguish these from investigation interpretations +- observed and expected behavior, observed location, trigger, occurrence conditions, and onset when known; mark unresolved facts rather than selecting a location or condition by plausibility - symptom-reachable execution paths and adjacent cases that share the same path, contract, persisted state, or external boundary - applicable evidence axes: code, history, dependencies, configuration, governing documents, and external specifications - explicit exclusions from the user or governing artifacts @@ -42,6 +43,10 @@ Define a semantic scope envelope from the reported problem and repository eviden The envelope bounds relevance. Keep every relationship above active throughout investigation, including after a plausible cause appears. +Resolve facts that change the investigation target from available evidence. Ask the user only for a target-changing fact that the investigation cannot obtain; continue unaffected investigation. + +When the user corrects the symptom's location, expected behavior, timing, or conditions, update this envelope and return to path mapping for the corrected symptom. Re-evaluate affected exclusions and failure points through investigator and verifier before invoking solver. Retain evidence that remains valid; prior coverage closure applies only to the symptom and evidence it verified. When new information only adds evidence for the same symptom, reopen only the judgments it affects. + ## Diagnosis Flow Overview ``` @@ -53,7 +58,7 @@ coverage closed → design decision gate when applicable → solver → Report material evidence unavailable → limitation/block report ``` -**Context Separation**: Pass only structured JSON output to each step. Each step starts fresh with the JSON data only. +**Context Separation**: Each specialist starts fresh with the current diagnosis scope envelope and the structured results named in its invocation. The envelope supplies the user's report independently of upstream interpretations. ## Execution Steps @@ -66,8 +71,7 @@ description: "Investigate problem" prompt: | Comprehensively collect information related to the following phenomenon. - Phenomenon: [Problem reported by user verbatim] - diagnosisScopeEnvelope: [Step 0 semantic scope envelope] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] ``` **Expected output**: scopeAccounting, pathMap (execution paths per symptom), failurePoints (faults found at each node), impactAnalysis per failure point, unexplored areas, investigation limitations @@ -91,6 +95,8 @@ prompt: | Re-investigate with focus on the following gaps: - Missing: [unsatisfied Step 2 Quality Check items, copied as written] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] + Use these previous investigation results as context and investigate only the gaps listed above. Return one updated complete investigation JSON, retaining prior evidence that remains valid: [Previous investigation JSON] ``` @@ -105,7 +111,7 @@ subagent_type: verifier description: "Verify investigation results" prompt: Verify the following investigation results against the semantic diagnosis scope envelope. -diagnosisScopeEnvelope: [Step 0 semantic scope envelope] +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Investigation results: [Investigation JSON output] ``` @@ -121,8 +127,8 @@ Investigation results: [Investigation JSON output] Branch on verifier output before invoking solver: -- `coverageDisposition: closed`: freeze the complete verified cause set and continue to the applicable design decision gate. -- `coverageDisposition: gaps_remaining`: return to Step 1 with only verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Keep `scopeAccounting` monotonic by preserving every accounted item. Add a gap only when new evidence identifies a distinct previously unaccounted gap within the semantic scope envelope that can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. +- `coverageDisposition: closed`: carry the complete verified cause set forward to the solution boundary, subject to Step 0's symptom and evidence updates. +- `coverageDisposition: gaps_remaining`: return to Step 1 with the current scope envelope, verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Preserve accounted items whose evidence remains valid. Investigate gaps or reopen judgments only when the current symptom or new evidence can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. - `coverageDisposition: evidence_unavailable`: finish with the unavailable-evidence report, including the evidence, attempted recovery, and why it can change the cause set. Continue investigation while an available action can advance a material gap. Completion is determined by verifier-established semantic closure or by confirmation that no available action can advance the gap. @@ -139,6 +145,7 @@ subagent_type: solver description: "Derive solutions" prompt: Derive solutions based on the following verified failure points. +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Confirmed failure points: [verifier's conclusion.confirmedFailurePoints] Refuted failure points: [verifier's conclusion.refutedFailurePoints] Failure point relationships: [verifier's conclusion.failurePointRelationships] diff --git a/package.json b/package.json index 8c6c0f0f..5f091eba 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-code-workflows", - "version": "0.29.0", + "version": "0.29.1", "private": true, "type": "module", "engines": { diff --git a/skills/recipe-diagnose/SKILL.md b/skills/recipe-diagnose/SKILL.md index 5d20b895..25c5da5e 100644 --- a/skills/recipe-diagnose/SKILL.md +++ b/skills/recipe-diagnose/SKILL.md @@ -34,7 +34,8 @@ At each Agent invocation below, build the prompt as a mechanical extraction: cop Define a semantic scope envelope from the reported problem and repository evidence by recording: -- phenomenon and occurrence conditions to explain +- the user's symptom report and corrections verbatim, with linked evidence; distinguish these from investigation interpretations +- observed and expected behavior, observed location, trigger, occurrence conditions, and onset when known; mark unresolved facts rather than selecting a location or condition by plausibility - symptom-reachable execution paths and adjacent cases that share the same path, contract, persisted state, or external boundary - applicable evidence axes: code, history, dependencies, configuration, governing documents, and external specifications - explicit exclusions from the user or governing artifacts @@ -42,6 +43,10 @@ Define a semantic scope envelope from the reported problem and repository eviden The envelope bounds relevance. Keep every relationship above active throughout investigation, including after a plausible cause appears. +Resolve facts that change the investigation target from available evidence. Ask the user only for a target-changing fact that the investigation cannot obtain; continue unaffected investigation. + +When the user corrects the symptom's location, expected behavior, timing, or conditions, update this envelope and return to path mapping for the corrected symptom. Re-evaluate affected exclusions and failure points through investigator and verifier before invoking solver. Retain evidence that remains valid; prior coverage closure applies only to the symptom and evidence it verified. When new information only adds evidence for the same symptom, reopen only the judgments it affects. + ## Diagnosis Flow Overview ``` @@ -53,7 +58,7 @@ coverage closed → design decision gate when applicable → solver → Report material evidence unavailable → limitation/block report ``` -**Context Separation**: Pass only structured JSON output to each step. Each step starts fresh with the JSON data only. +**Context Separation**: Each specialist starts fresh with the current diagnosis scope envelope and the structured results named in its invocation. The envelope supplies the user's report independently of upstream interpretations. ## Execution Steps @@ -66,8 +71,7 @@ description: "Investigate problem" prompt: | Comprehensively collect information related to the following phenomenon. - Phenomenon: [Problem reported by user verbatim] - diagnosisScopeEnvelope: [Step 0 semantic scope envelope] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] ``` **Expected output**: scopeAccounting, pathMap (execution paths per symptom), failurePoints (faults found at each node), impactAnalysis per failure point, unexplored areas, investigation limitations @@ -91,6 +95,8 @@ prompt: | Re-investigate with focus on the following gaps: - Missing: [unsatisfied Step 2 Quality Check items, copied as written] + diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] + Use these previous investigation results as context and investigate only the gaps listed above. Return one updated complete investigation JSON, retaining prior evidence that remains valid: [Previous investigation JSON] ``` @@ -105,7 +111,7 @@ subagent_type: verifier description: "Verify investigation results" prompt: Verify the following investigation results against the semantic diagnosis scope envelope. -diagnosisScopeEnvelope: [Step 0 semantic scope envelope] +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Investigation results: [Investigation JSON output] ``` @@ -121,8 +127,8 @@ Investigation results: [Investigation JSON output] Branch on verifier output before invoking solver: -- `coverageDisposition: closed`: freeze the complete verified cause set and continue to the applicable design decision gate. -- `coverageDisposition: gaps_remaining`: return to Step 1 with only verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Keep `scopeAccounting` monotonic by preserving every accounted item. Add a gap only when new evidence identifies a distinct previously unaccounted gap within the semantic scope envelope that can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. +- `coverageDisposition: closed`: carry the complete verified cause set forward to the solution boundary, subject to Step 0's symptom and evidence updates. +- `coverageDisposition: gaps_remaining`: return to Step 1 with the current scope envelope, verifier's named gaps, their relevance to the cause set, and the prior investigation JSON. Preserve accounted items whose evidence remains valid. Investigate gaps or reopen judgments only when the current symptom or new evidence can materially change the supported cause set. Closing a gap or establishing that its evidence is unavailable advances convergence; renaming, splitting, or further describing the same gap preserves its existing state. When no available action can produce one of those state changes, return the attempted recovery to verifier for `evidence_unavailable`. Repeat verification after the investigation result passes Step 2. - `coverageDisposition: evidence_unavailable`: finish with the unavailable-evidence report, including the evidence, attempted recovery, and why it can change the cause set. Continue investigation while an available action can advance a material gap. Completion is determined by verifier-established semantic closure or by confirmation that no available action can advance the gap. @@ -139,6 +145,7 @@ subagent_type: solver description: "Derive solutions" prompt: Derive solutions based on the following verified failure points. +diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope] Confirmed failure points: [verifier's conclusion.confirmedFailurePoints] Refuted failure points: [verifier's conclusion.refutedFailurePoints] Failure point relationships: [verifier's conclusion.failurePointRelationships]