Merge pull request #90 from jwm4/bugfix/comprehensive-workflow-improvements

fix(bugfix): comprehensive workflow improvements addressing 9 open issues

Author: jwm4

workflows/bugfix/.claude/skills/assess/SKILL.md

@@ -68,7 +68,49 @@ gh repo clone OWNER/REPO /workspace/repos/REPO
 
 This is read-only exploration — understand the code, don't change it.
 
-### Step 3: Summarize Your Understanding
+### Step 3: Check for Existing Work
+
+Before investing effort, check whether this bug is already being addressed:
+
+- **Check for linked PRs on the issue:**
+
+```bash
+gh issue view NUMBER --repo OWNER/REPO --json body,comments --jq '[.body, .comments[].body] | join("\n")' | grep -i "pull\|PR\|#"
+```
+
+- **Scan recent PR titles for overlap:**
+
+```bash
+gh pr list --repo OWNER/REPO --state open --limit 30 --json number,title,headRefName --jq '.[] | "\(.number)\t\(.title)"'
+```
+
+  Skim the titles for anything related to the bug's component, error, or
+  symptoms. If a PR looks relevant, read its description before proceeding.
+
+- **Check for duplicate or related issues:**
+
+```bash
+gh issue list --repo OWNER/REPO --state open --limit 30 --json number,title --jq '.[] | "\(.number)\t\(.title)"'
+```
+
+If you find an open PR that appears to directly address this bug, **stop here
+and use `AskUserQuestion`** before continuing the assessment. Present the
+options:
+
+- "PR #N appears to address this bug — review it instead of starting fresh"
+- "PR #N is related but doesn't fully cover it — continue with assessment"
+- "Not sure if PR #N is relevant — continue with assessment"
+
+This gate applies in both normal and speedrun mode. Do not continue to Step 4
+until the user responds. The `AskUserQuestion` tool triggers platform
+notifications so the user knows you need their input.
+
+If duplicate or related issues are found (but no PR), note them in the
+assessment and continue — these inform the assessment but don't block it.
+
+If no existing work is found, note that and continue.
+
+### Step 4: Summarize Your Understanding
 
 Present a clear, concise summary to the user covering:
 
@@ -81,7 +123,7 @@ Present a clear, concise summary to the user covering:
 - **Severity/impact:** Your assessment of how serious this is, based on the
   information available
 
-### Step 4: Identify What You Know vs. What's Missing
+### Step 5: Identify What You Know vs. What's Missing
 
 Be explicit about gaps:
 
@@ -93,7 +135,7 @@ Be explicit about gaps:
 - **Assumptions:** Any assumptions you're making — call them out so the user
   can confirm or correct them
 
-### Step 5: Propose a Reproduction Plan
+### Step 6: Propose a Reproduction Plan
 
 Based on your understanding, outline how you would approach reproduction:
 
@@ -105,7 +147,7 @@ Based on your understanding, outline how you would approach reproduction:
 If the bug seems straightforward, the plan can be brief. If it's complex or
 ambiguous, be thorough.
 
-### Step 6: Present to the User
+### Step 7: Present to the User
 
 Deliver your assessment in this structure:
 
@@ -115,6 +157,9 @@ Deliver your assessment in this structure:
 **Issue:** [title or one-line summary]
 **Source:** [issue URL, conversation, etc.]
 
+### Existing Work
+[Any related PRs, duplicate issues, or prior attempts — or "None found"]
+
 ### Understanding
 [Your 2-3 sentence summary of the bug]
 
@@ -139,12 +184,22 @@ Deliver your assessment in this structure:
 Be direct. If the bug report is clear and complete, say so. If it's vague or
 missing critical details, say that too.
 
-### Step 7: Write the Assessment Artifact
+**If the bug doesn't actually apply**, say so clearly and present options:
+
+- "This issue doesn't affect your project — here's why. Want to close it?"
+- "The reported issue doesn't apply directly, but here's a related improvement
+  we could make (with trade-offs): ..."
+- "This appears to be a duplicate of #N — should we close this one?"
+
+Do not proceed to fix something you've concluded isn't broken. Present your
+finding and let the user decide.
+
+### Step 8: Write the Assessment Artifact
 
 Save your assessment to `artifacts/bugfix/reports/assessment.md` so that
 subsequent phases (and speedrun resumption) can detect that this phase is
 complete. The file should contain the same content you presented to the user
-in Step 6.
+in Step 7.
 
 ## Output
 

workflows/bugfix/.claude/skills/controller/SKILL.md

@@ -34,6 +34,10 @@ executing phases and handling transitions between them.
 8. **PR** (`/pr`) — `.claude/skills/pr/SKILL.md`
    Push the branch to a fork and create a draft pull request.
 
+9. **Summary** (`/summary`) — `.claude/skills/summary/SKILL.md`
+   Scan all artifacts and present a synthesized summary of findings, decisions,
+   and status. Can also be invoked at any point mid-workflow.
+
 Phases can be skipped or reordered at the user's discretion.
 
 ## How to Execute a Phase
@@ -43,12 +47,20 @@ Phases can be skipped or reordered at the user's discretion.
    "Starting the /fix phase (dispatched by `.claude/skills/controller/SKILL.md`)."
    This is very important so the user knows the workflow is working, learns
    about the available phases, and so skills can find their way back here.
-2. **Read** the skill file from the list above
+2. **Read** the skill file from the list above. You MUST call the Read tool on
+   the skill's `SKILL.md` file before executing. If you find yourself executing
+   a phase without having read its skill file, you are doing it wrong — stop
+   and read it now.
 3. **Execute** the skill's steps directly — the user should see your progress
 4. When the skill is done, it will report its findings and re-read this
    controller. Then use "Recommending Next Steps" below to offer options.
-5. Present the skill's results and your recommendations to the user
-6. **Stop and wait** for the user to tell you what to do next
+5. Present the skill's results and your recommendations to the user.
+6. **Use `AskUserQuestion` to get the user's decision.** Present the
+   recommended next step and alternatives as options. Do NOT continue until the
+   user responds. This is a hard gate — the `AskUserQuestion` tool triggers
+   platform notifications and status indicators so the user knows you need
+   their input. Plain-text questions do not create these signals and the user
+   may not see them.
 
 ## Recommending Next Steps
 
@@ -59,7 +71,7 @@ happened.
 ### Typical Flow
 
 ```text
-assess → reproduce → diagnose → fix → test → review → document → pr
+assess → reproduce → diagnose → fix → test → review → document → pr → summary
 ```
 
 ### What to Recommend
@@ -110,6 +122,17 @@ directly — don't force them through earlier phases.
 
 ## Rules
 
-- **Never auto-advance.** Always wait for the user between phases.
+- **Never auto-advance.** Always use `AskUserQuestion` and wait for the user's
+  response between phases. This is the single most important rule in this
+  controller. If you proceed to another phase without the user's explicit
+  go-ahead, the workflow is broken.
+- **Always read skill files.** Every phase execution MUST begin with a Read
+  tool call on the skill's `SKILL.md` file. Do not execute a phase from memory
+  or general knowledge — the skill files contain specific, tested instructions
+  that differ from what you might do ad-hoc.
+- **Urgency does not bypass process.** Security advisories, critical bugs, and
+  production incidents may create pressure to act fast. The phase-gated
+  workflow exists precisely to prevent hasty action. Follow every phase gate
+  regardless of perceived urgency.
 - **Recommendations come from this file, not from skills.** Skills report
   findings; this controller decides what to recommend next.

workflows/bugfix/.claude/skills/fix/SKILL.md

@@ -59,29 +59,50 @@ Before finalizing the implementation, ensure thoroughness:
 - **Check for complete enumeration**: If implementing switch/case logic or conditional checks, verify you've handled all possible values. Search the codebase for where these values are defined or used.
 - **Example**: If implementing polling that stops on "terminal" session phases, search the codebase for all usages of session phases to build a complete list (Stopped, Completed, Failed, Error) rather than assuming you know them all.
 
-### Step 4: Address Related Code
+### Step 4: Review Error Handling UX
+
+If your fix involves error handling, validation, or user-facing messages,
+review the error paths for clarity:
+
+- **Match error context to error type.** A CLI argument error should use the
+  CLI framework's error type (e.g., `click.BadParameter`), while a
+  configuration file error should use a general exception that says which file
+  and line caused the problem. Don't report config file errors as CLI parameter
+  errors, or vice versa.
+- **Test every error path manually.** Trigger each error condition and read the
+  message from the user's perspective. Is it clear what went wrong? Does it
+  point to the right place to fix it?
+- **Consider different error contexts:**
+  - CLI errors → should reference the flag or argument
+  - Config file errors → should reference the file path and setting
+  - Runtime errors → should include enough context to reproduce
+  - API errors → should include the endpoint and status code
+- **Ensure error messages don't leak internals.** Stack traces, internal paths,
+  and raw exception types are useful for developers but confusing for users.
+
+### Step 5: Address Related Code
 
 - Fix similar patterns identified in root cause analysis
 - Update affected function signatures if necessary
 - Ensure consistency across the codebase
 - Consider adding defensive programming where appropriate
 
-### Step 5: Update Documentation
+### Step 6: Update Documentation
 
 - Update inline code documentation
 - Modify API documentation if interfaces changed
 - Update configuration documentation if settings changed
 - Note any breaking changes clearly
 
-### Step 6: Pre-commit Quality Checks
+### Step 7: Pre-commit Quality Checks
 
 - Run code formatters (e.g., `gofmt`, `black`, `prettier`)
 - Run linters and fix all warnings (e.g., `golangci-lint`, `flake8`, `eslint`)
 - Ensure code compiles/builds without errors
 - Check for any new security vulnerabilities introduced
 - Verify no secrets or sensitive data added
 
-### Step 7: Document Implementation
+### Step 8: Document Implementation
 
 Create `artifacts/bugfix/fixes/implementation-notes.md` containing: