@leeovery/claude-technical-workflows 2.1.42 → 2.2.0

package/skills/technical-investigation/references/analysis-patterns.md

@@ -0,0 +1,181 @@
+# Analysis Patterns
+
+*Reference for **[technical-investigation](../SKILL.md)***
+
+---
+
+Techniques for tracing bugs through code.
+
+## Code Tracing Techniques
+
+### 1. Entry Point Identification
+
+Start from where the user sees the problem:
+- UI component that displays the error
+- API endpoint that returns wrong data
+- Background job that fails
+- Event handler that misbehaves
+
+Work backwards from the symptom to the source.
+
+### 2. Data Flow Analysis
+
+Follow the data through the system:
+- Where does the data originate?
+- What transformations does it undergo?
+- Where is it stored/retrieved?
+- What validations exist?
+- Where does corruption or loss occur?
+
+### 3. Control Flow Analysis
+
+Trace the execution path:
+- What conditions must be true to reach the bug?
+- Are there early returns or exceptions?
+- What state affects the flow?
+- Are there race conditions?
+
+### 4. Dependency Mapping
+
+Understand what the buggy code depends on:
+- External services (APIs, databases)
+- Shared state (caches, session)
+- Configuration values
+- Other modules/components
+
+### 5. Change Analysis
+
+If the bug is recent:
+- What changed recently? (git log, PRs)
+- What was the last working version?
+- Can you bisect to find the introducing commit?
+
+## Common Bug Patterns
+
+### Race Conditions
+
+**Symptoms:**
+- Intermittent failures
+- Works in dev, fails in prod
+- Related to timing or load
+
+**Investigation:**
+- Look for shared mutable state
+- Check async operations
+- Examine lock/synchronization
+- Review concurrent access patterns
+
+### Off-by-One Errors
+
+**Symptoms:**
+- Boundary cases fail
+- Works for most inputs, fails for edge cases
+- Array index out of bounds
+
+**Investigation:**
+- Check loop boundaries
+- Examine array/string indexing
+- Review length calculations
+- Test boundary values explicitly
+
+### Null/Undefined References
+
+**Symptoms:**
+- TypeError or NullPointerException
+- Fails on specific data combinations
+- Works when optional fields are present
+
+**Investigation:**
+- Trace where null can originate
+- Check optional field handling
+- Review default value assignments
+- Examine null propagation paths
+
+### State Corruption
+
+**Symptoms:**
+- Wrong values appear unexpectedly
+- State doesn't match expectations
+- Problem persists across sessions
+
+**Investigation:**
+- Map all mutation points
+- Check for unintended side effects
+- Review state initialization
+- Examine persistence/hydration
+
+### Memory/Resource Leaks
+
+**Symptoms:**
+- Gradual degradation over time
+- OOM errors after extended use
+- Performance slowdown
+
+**Investigation:**
+- Check cleanup/disposal code
+- Review subscription/listener patterns
+- Examine caching behavior
+- Profile memory over time
+
+## Investigation Commands
+
+### Finding Related Code
+
+```bash
+# Find all references to a function
+grep -r "functionName" --include="*.ts"
+
+# Find recent changes to a file
+git log -p --follow -- path/to/file.ts
+
+# Find commits mentioning a pattern
+git log --all --grep="pattern"
+
+# Find who changed a line
+git blame path/to/file.ts
+```
+
+### Comparing States
+
+```bash
+# Diff between working and broken
+git diff good-commit bad-commit -- path/
+
+# Find introducing commit
+git bisect start
+git bisect bad HEAD
+git bisect good known-good-commit
+```
+
+## Documentation Tips
+
+### Recording Code Traces
+
+Format traces clearly:
+```
+src/auth/login.ts:45 - validateCredentials() called
+  → src/auth/validate.ts:12 - checks password hash
+  → src/db/users.ts:78 - queries user record
+  → BUG: returns null when user.status is 'pending'
+```
+
+### Capturing Dead Ends
+
+Dead ends are valuable. Document them:
+```
+### Hypothesis: Cache invalidation issue
+Investigated: src/cache/userCache.ts
+Finding: Cache is correctly invalidated on user update
+Ruled out: Caching is not the cause
+```
+
+### Noting Environmental Factors
+
+Record environment-specific findings:
+```
+### Environment Observations
+- Bug occurs in production but not staging
+- Difference: Production uses connection pooling
+- Staging: Single connection per request
+- This affects transaction isolation
+```

package/skills/technical-investigation/references/symptom-gathering.md

@@ -0,0 +1,164 @@
+# Symptom Gathering
+
+*Reference for **[technical-investigation](../SKILL.md)***
+
+---
+
+Questions to ask when gathering bug symptoms.
+
+## Core Questions
+
+### What's broken?
+
+- What is the expected behavior?
+- What is the actual behavior?
+- How significant is the gap?
+
+### How is it manifesting?
+
+- What error messages appear?
+- What UI/UX issues are visible?
+- Are there performance symptoms?
+- Is data affected (corrupted, lost, wrong)?
+
+### When did it start?
+
+- When was the bug first noticed?
+- Was there a recent deployment or change?
+- Did something trigger it (load spike, new feature)?
+
+### Who is affected?
+
+- All users or a subset?
+- Specific user types/roles?
+- Specific regions or environments?
+
+## Reproduction Questions
+
+### Can you reproduce it?
+
+- Always, sometimes, or rarely?
+- Are there specific conditions required?
+- Does reproduction require specific data?
+
+### What are the exact steps?
+
+1. What is the starting state?
+2. What action triggers the bug?
+3. What happens immediately after?
+4. How does the user know it's wrong?
+
+### What are the preconditions?
+
+- User state (logged in, permissions)
+- Data state (specific records, configurations)
+- Application state (cached data, session)
+- Time-based (time of day, day of week)
+
+## Environment Questions
+
+### Where does it occur?
+
+- Production, staging, development?
+- Specific servers or regions?
+- All instances or specific ones?
+
+### What platform?
+
+- Browser type and version
+- Operating system
+- Mobile vs desktop
+- App version (if applicable)
+
+### What are the external factors?
+
+- Network conditions
+- Third-party service status
+- Database load
+- Recent infrastructure changes
+
+## Impact Questions
+
+### How severe is this?
+
+- **Critical**: System down, data loss, security breach
+- **High**: Major feature broken, many users affected
+- **Medium**: Feature degraded, workaround exists
+- **Low**: Minor issue, few users affected
+
+### What is the business impact?
+
+- Revenue affected?
+- Customer trust impacted?
+- Compliance implications?
+- Support ticket volume?
+
+### What is the scope?
+
+- How many users affected?
+- How often does it occur?
+- Is it getting worse?
+
+## Reference Gathering
+
+### Do you have error logs?
+
+- Application logs
+- Server logs
+- Browser console
+- Network requests
+
+### Are there error tracking entries?
+
+- Sentry or similar
+- Stack traces
+- Frequency data
+- User sessions
+
+### Any relevant support tickets?
+
+- Customer reports
+- Internal reports
+- Related issues
+- Historical context
+
+### Screenshots or recordings?
+
+- Visual of the bug
+- Steps leading to it
+- Error states
+- Expected vs actual comparison
+
+## Follow-up Questions
+
+### What have you already tried?
+
+- Debugging attempts
+- Hypotheses tested
+- Workarounds attempted
+
+### What does your team suspect?
+
+- Initial hypotheses
+- Areas of concern
+- Recent changes that might be related
+
+### Any time sensitivity?
+
+- Is there a deadline?
+- Is there a workaround for now?
+- How urgent is the fix?
+
+## Question Order
+
+Start broad, then narrow:
+
+1. **Problem description** - What's wrong?
+2. **Impact assessment** - How bad is it?
+3. **Reproduction** - Can we trigger it?
+4. **Environment** - Where does it happen?
+5. **History** - When did it start?
+6. **References** - What do we have to work with?
+7. **Hypotheses** - What do you suspect?
+
+Don't ask all questions upfront. Start with the most important, gather initial context, then drill down based on responses.

package/skills/technical-investigation/references/template.md

@@ -0,0 +1,164 @@
+# Investigation Template
+
+*Reference for **[technical-investigation](../SKILL.md)***
+
+---
+
+Use this structure for investigation documents.
+
+```markdown
+---
+topic: {topic}
+status: in-progress
+work_type: bugfix
+date: {YYYY-MM-DD}
+---
+
+# Investigation: {Topic Title}
+
+## Symptoms
+
+### Problem Description
+
+**Expected behavior:**
+{What should happen}
+
+**Actual behavior:**
+{What actually happens}
+
+### Manifestation
+
+{How the bug surfaces:}
+- Error messages
+- UI glitches
+- Data corruption
+- Performance issues
+- etc.
+
+### Reproduction Steps
+
+1. {Precondition or setup}
+2. {Action that triggers the bug}
+3. {Observe the result}
+
+**Reproducibility:** {Always / Sometimes / Intermittent}
+
+### Environment
+
+- **Affected environments:** {Production, staging, local}
+- **Browser/platform:** {If relevant}
+- **User conditions:** {Specific user states, permissions, data}
+
+### Impact
+
+- **Severity:** {Critical / High / Medium / Low}
+- **Scope:** {Number of users affected}
+- **Business impact:** {Revenue, trust, compliance}
+
+### References
+
+- {Link to error tracking (Sentry, etc.)}
+- {Link to support tickets}
+- {Link to relevant logs}
+
+---
+
+## Analysis
+
+### Initial Hypotheses
+
+{What the user or team initially suspected}
+
+### Code Trace
+
+**Entry point:**
+{Where the problematic flow starts}
+
+**Execution path:**
+1. {file:line - description}
+2. {file:line - description}
+3. {file:line - description}
+
+**Key files involved:**
+- {file} - {role in the bug}
+- {file} - {role in the bug}
+
+### Root Cause
+
+{Clear, precise statement of what causes the bug}
+
+**Why this happens:**
+{Explanation of the underlying issue}
+
+### Contributing Factors
+
+- {Factor 1 - why it enables the bug}
+- {Factor 2 - why it enables the bug}
+
+### Why It Wasn't Caught
+
+- {Testing gap}
+- {Edge case not considered}
+- {Recent change that introduced it}
+
+### Blast Radius
+
+**Directly affected:**
+- {Component/feature}
+- {Component/feature}
+
+**Potentially affected:**
+- {Component/feature that shares code/patterns}
+
+---
+
+## Fix Direction
+
+### Proposed Approach
+
+{High-level description of the fix direction}
+
+### Alternatives Considered
+
+**Alternative 1:** {Approach}
+- Pros: {benefits}
+- Cons: {drawbacks}
+- Why not: {reason}
+
+**Alternative 2:** {Approach}
+- Pros: {benefits}
+- Cons: {drawbacks}
+- Why not: {reason}
+
+### Testing Recommendations
+
+- {Test that should be added}
+- {Test that should be added}
+- {Existing test that should be modified}
+
+### Risk Assessment
+
+- **Fix complexity:** {Low / Medium / High}
+- **Regression risk:** {Low / Medium / High}
+- **Recommended approach:** {Hotfix / Regular release / Feature flag}
+
+---
+
+## Notes
+
+{Any additional observations, questions for later, or context}
+```
+
+## Section Guidelines
+
+### Symptoms Section
+
+Gather all observable information about the bug before analyzing code. This creates a clear target for analysis and helps validate the fix.
+
+### Analysis Section
+
+Document your investigation journey. Even dead ends are valuable — they show what's NOT the cause and help others avoid the same paths.
+
+### Fix Direction Section
+
+Don't detail the implementation here — that's for the specification. Focus on high-level direction, alternatives, and risk assessment.

package/skills/technical-planning/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: technical-planning
-description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from .workflows/specification/{topic}/specification.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in .workflows/planning/{topic}/plan.md that can be executed via strict TDD."
 user-invocable: false
 ---
 
@@ -264,3 +263,27 @@ The plan contains **{N} phases** with **{M} tasks** total, reviewed for traceabi
 
 Status has been marked as `concluded`. The plan is ready for implementation.
 ```
+
+4. **Check for pipeline continuation** — Check the plan frontmatter for `work_type`
+
+**If work_type is set** (feature, bugfix, or greenfield):
+
+This plan is part of a pipeline. Invoke the `/workflow:bridge` skill:
+
+```
+Pipeline bridge for: {topic}
+Work type: {work_type from artifact frontmatter}
+Completed phase: planning
+
+Invoke the workflow:bridge skill to enter plan mode with continuation instructions.
+```
+
+**If work_type is not set:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Plan concluded: {topic}
+
+The plan is ready for implementation. Run /start-implementation to begin.
+```

package/skills/technical-planning/references/author-tasks.md

@@ -8,7 +8,7 @@ This step uses the `planning-task-author` agent (`../../../agents/planning-task-
 
 ---
 
-## Section 1: Prepare the Scratch File
+## A. Prepare the Scratch File
 
 Scratch file path: `.workflows/.cache/planning/{topic}/phase-{N}.md`
 
@@ -16,7 +16,7 @@ Create the `.workflows/.cache/planning/{topic}/` directory if it does not exist.
 
 ---
 
-## Section 2: Invoke the Agent (Batch)
+## B. Invoke the Agent (Batch)
 
 > *Output the next fenced block as a code block:*
 
@@ -38,7 +38,7 @@ The agent writes all tasks to the scratch file and returns.
 
 ---
 
-## Section 3: Validate Scratch File
+## C. Validate Scratch File
 
 Read the scratch file and count tasks. Verify task count matches the task table in the Plan Index File for this phase.
 
@@ -48,11 +48,11 @@ Re-invoke the agent with the same inputs.
 
 #### If valid
 
-→ Proceed to **Section 4**.
+→ Proceed to **D. Check Gate Mode**.
 
 ---
 
-## Section 4: Check Gate Mode
+## D. Check Gate Mode
 
 Check `author_gate_mode` in the Plan Index File frontmatter.
 
@@ -64,15 +64,15 @@ Check `author_gate_mode` in the Plan Index File frontmatter.
 Phase {N}: {count} tasks authored. Auto-approved. Writing to plan.
 ```
 
-→ Jump to **Section 6**.
+→ Proceed to **F. Write to Plan**.
 
 #### If `author_gate_mode: gated`
 
-→ Enter **Section 5**.
+→ Proceed to **E. Approval Loop**.
 
 ---
 
-## Section 5: Approval Loop
+## E. Approval Loop
 
 For each task in the scratch file, in order:
 
@@ -114,7 +114,7 @@ Mark the task `approved` in the scratch file. Continue to the next task.
 
 Mark the task `approved` in the scratch file. Set all remaining `pending` tasks to `approved`. Update `author_gate_mode: auto` in the Plan Index File frontmatter.
 
-→ Jump to **Section 6**.
+→ Proceed to **F. Write to Plan**.
 
 #### If the user provides feedback
 
@@ -133,17 +133,17 @@ Continue to the next task.
 
 #### If the user navigates
 
-→ Return to **Plan Construction**. The scratch file preserves approval state.
+→ Return to **[plan-construction.md](plan-construction.md)**. The scratch file preserves approval state.
 
 ---
 
-### Section 5b: Revision
+### Revision
 
 After completing the approval loop, check for rejected tasks.
 
 #### If no rejected tasks
 
-→ Proceed to **Section 6**.
+→ Proceed to **F. Write to Plan**.
 
 #### If rejected tasks exist
 
@@ -153,11 +153,11 @@ After completing the approval loop, check for rejected tasks.
 {N} tasks need revision. Re-invoking author agent...
 ```
 
-→ Return to **Section 2**. The agent receives the scratch file with rejected tasks and feedback, rewrites only those, and the flow continues through validation, gate check, and approval as normal.
+→ Return to **B. Invoke the Agent (Batch)**. The agent receives the scratch file with rejected tasks and feedback, rewrites only those, and the flow continues through validation, gate check, and approval as normal.
 
 ---
 
-## Section 6: Write to Plan
+## F. Write to Plan
 
 > **CHECKPOINT**: If `author_gate_mode: gated`, verify all tasks in the scratch file are marked `approved` before writing.
 
@@ -181,10 +181,10 @@ Repeat for each task.
 
 ---
 
-## Section 7: Cleanup
+## G. Cleanup
 
 Delete the scratch file: `rm .workflows/.cache/planning/{topic}/phase-{N}.md`
 
 Remove the `.workflows/.cache/planning/{topic}/` directory if empty.
 
-→ Return to **Plan Construction**.
+→ Return to **[plan-construction.md](plan-construction.md)**.

package/skills/technical-planning/references/define-tasks.md

@@ -68,7 +68,7 @@ Check `task_list_gate_mode` in the Plan Index File frontmatter.
 Phase {N}: {Phase Name} — task list approved. Proceeding to authoring.
 ```
 
-→ Skip to **If approved** below.
+→ Proceed to **If approved** below.
 
 #### If `task_list_gate_mode: gated`
 
@@ -110,4 +110,4 @@ Note that `task_list_gate_mode` should be updated to `auto` during the commit st
 
 **If the task list was already approved and unchanged:** No updates needed.
 
-→ Return to **Plan Construction**.
+→ Return to **[plan-construction.md](plan-construction.md)**.