Update debug skill

Author: codeaholicguy

.claude/skills/dev-lifecycle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-lifecycle
-description: Full software development lifecycle workflow covering requirements, design, planning, implementation, testing, and code review. Use this skill when a user wants to build a new feature end-to-end, clarify or document requirements, review requirements or design docs, execute a feature plan, check implementation against design, perform code review, or write tests. Triggers on requests like "new feature", "add requirement", "review requirements", "review design", "execute plan", "check implementation", "code review", "write tests", or any structured SDLC workflow.
+description: Full software development lifecycle workflow covering requirements, design, planning, implementation, planning updates, testing, and code review. Use this skill when a user wants to build a new feature end-to-end, clarify or document requirements, review requirements or design docs, execute a feature plan, update planning after task completion, check implementation against design, perform code review, or write tests. Triggers on requests like "new feature", "add requirement", "review requirements", "review design", "execute plan", "update planning", "check implementation", "code review", "write tests", or any structured SDLC workflow.
 ---
 
 # Dev Lifecycle
@@ -15,21 +15,23 @@ Structured development lifecycle from requirements through testing. Each phase p
 | 2 | **Review Requirements** | [references/review-requirements.md](references/review-requirements.md) | Requirements doc exists and needs validation |
 | 3 | **Review Design** | [references/review-design.md](references/review-design.md) | Design doc exists and needs validation |
 | 4 | **Execute Plan** | [references/execute-plan.md](references/execute-plan.md) | Planning doc exists and user is ready to implement |
-| 5 | **Check Implementation** | [references/check-implementation.md](references/check-implementation.md) | Code changes exist and need validation against design |
-| 6 | **Code Review** | [references/code-review.md](references/code-review.md) | Changes are ready for pre-push review |
-| 7 | **Write Tests** | [references/writing-test.md](references/writing-test.md) | Feature needs unit/integration/E2E tests |
+| 5 | **Update Planning** | [references/update-planning.md](references/update-planning.md) | A task was just completed; reconcile planning doc with progress |
+| 6 | **Check Implementation** | [references/check-implementation.md](references/check-implementation.md) | Code changes exist and need validation against design |
+| 7 | **Code Review** | [references/code-review.md](references/code-review.md) | Changes are ready for pre-push review |
+| 8 | **Write Tests** | [references/writing-test.md](references/writing-test.md) | Feature needs unit/integration/E2E tests |
 
 ## Phase Selection
 
 1. If the user has no docs yet and wants to build something new → start at **Phase 1**.
 2. If requirements doc exists but hasn't been reviewed → **Phase 2**.
 3. If design doc exists but hasn't been reviewed → **Phase 3**.
 4. If planning doc exists and user says "implement" or "execute" → **Phase 4**.
-5. If code is written and user wants to verify against design → **Phase 5**.
-6. If code is ready to push → **Phase 6**.
-7. If user asks for tests at any point → **Phase 7**.
+5. After finishing any task in Phase 4, automatically run **Phase 5** to reconcile planning docs.
+6. If code is written and user wants to verify against design → **Phase 6**.
+7. If code is ready to push → **Phase 7**.
+8. If user asks for tests at any point → **Phase 8**.
 
-When starting a new feature end-to-end, walk through phases 1→2→3→4→5→7→6 sequentially. Load only the reference file for the current phase.
+When starting a new feature end-to-end, walk through phases 1→2→3→4→(5 after each task)→6→8→7 sequentially. Load only the reference file for the current phase.
 
 ## Documentation Structure
 
@@ -60,7 +62,6 @@ Each feature doc is created by copying the corresponding `README.md` template in
 These can be invoked at any point during the lifecycle:
 
 - **Debug**: Structured debugging with root cause analysis before code changes.
-- **Update Planning**: Reconcile planning docs with current implementation progress.
 - **Simplify Implementation**: Analyze and reduce complexity in existing code.
 - **Capture Knowledge**: Document understanding of a code entry point.
 - **Remember**: Store reusable guidance in the knowledge memory service.

.claude/skills/dev-lifecycle/references/execute-plan.md

@@ -61,9 +61,10 @@ After each section, ask if new tasks were discovered. Capture in "New Work" list
 
 ## Step 8: Next Actions
 
-Remind the user to:
-- Update `docs/ai/planning/feature-{name}.md` with new statuses
+After completing any task, immediately run **Update Planning** (Phase 5) to reconcile the planning doc.
+
+Then remind the user to:
 - Sync related docs if decisions changed
-- Run **Check Implementation** (Phase 5) to validate against design
-- Run **Write Tests** (Phase 7) for coverage
-- Run **Code Review** (Phase 6) when ready for final review
+- Run **Check Implementation** (Phase 6) to validate against design
+- Run **Write Tests** (Phase 8) for coverage
+- Run **Code Review** (Phase 7) when ready for final review

.claude/skills/dev-lifecycle/references/update-planning.md

@@ -0,0 +1,63 @@
+# Phase 5: Update Planning
+
+Reconcile current implementation progress with planning documentation after completing any task.
+
+## Step 1: Gather Context
+
+Ask for:
+- Feature/branch name and brief status
+- Tasks completed since last update
+- Any new tasks discovered
+- Current blockers or risks
+- Planning doc path (default `docs/ai/planning/feature-{name}.md`)
+
+## Step 2: Review Planning Doc
+
+- Summarize existing milestones and task breakdowns
+- Note expected sequencing and dependencies
+- Identify outstanding tasks in the plan
+
+## Step 3: Reconcile Progress
+
+For each planned task:
+- Mark status (done / in progress / blocked / not started)
+- Note actual work completed vs. planned scope
+- Record blockers or changes in approach
+- Identify tasks that were skipped or added
+
+## Step 4: Update Task List
+
+Produce an updated checklist:
+
+```
+### Current Status: [Feature Name]
+
+#### Done
+- [x] Task A - short note or link to commit/PR
+- [x] Task B
+
+#### In Progress
+- [ ] Task C - waiting on [dependency]
+
+#### Blocked
+- [ ] Task D - blocked by [issue/owner]
+
+#### Newly Discovered Work
+- [ ] Task E - reason discovered
+- [ ] Task F - due by [date]
+```
+
+## Step 5: Next Steps & Priorities
+
+- Suggest the next 2-3 actionable tasks
+- Highlight risky areas needing attention
+- Recommend coordination (design changes, stakeholder sync, etc.)
+- List documentation updates needed
+
+## Step 6: Summary for Planning Doc
+
+Prepare a summary paragraph to copy into the planning doc, covering:
+- Current state and progress
+- Major risks/blockers
+- Upcoming focus items
+- Any changes to scope or timeline

.claude/skills/dev-lifecycle/scripts/phase-checklist.sh

@@ -8,13 +8,14 @@ cat <<'OUT'
 Dev Lifecycle Phase Checklist
 =============================
 
-1. [ ] New Requirement   — Feature captured, docs structure created
+1. [ ] New Requirement     — Feature captured, docs structure created
 2. [ ] Review Requirements — Requirements validated for completeness
-3. [ ] Review Design     — Design reviewed, mermaid diagrams verified
-4. [ ] Execute Plan      — Tasks executed from planning doc
-5. [ ] Check Implementation — Code validated against design
-6. [ ] Write Tests       — Unit/integration/E2E tests added (100% target)
-7. [ ] Code Review       — Pre-push review completed
+3. [ ] Review Design       — Design reviewed, mermaid diagrams verified
+4. [ ] Execute Plan        — Tasks executed from planning doc
+5. [ ] Update Planning     — Planning doc reconciled after each task
+6. [ ] Check Implementation — Code validated against design
+7. [ ] Code Review         — Pre-push review completed
+8. [ ] Write Tests         — Unit/integration/E2E tests added (100% target)
 
 Feature name:
 Planning doc:

skills/debug/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: debug
+description: Guide structured debugging before code changes by clarifying expected behavior, reproducing issues, identifying likely root causes, and agreeing on a fix plan with validation steps. Use when users ask to debug bugs, investigate regressions, triage incidents, diagnose failing behavior, handle failing tests, analyze production incidents, investigate error spikes, or run root cause analysis (RCA).
+---
+
+# Local Debugging Assistant
+
+Debug with an evidence-first workflow before changing code.
+
+## Hard Rule
+- Do not modify code until the user approves a selected fix plan.
+
+## Workflow
+
+1. Clarify
+- Restate observed vs expected behavior in one concise diff.
+- Confirm scope and measurable success criteria.
+
+2. Reproduce
+- Capture minimal reproduction steps.
+- Capture environment fingerprint: runtime, versions, config flags, data sample, and platform.
+
+3. Hypothesize and Test
+For each hypothesis, include:
+- Predicted evidence if true.
+- Disconfirming evidence if false.
+- Exact test command or check.
+- Prefer one-variable-at-a-time tests.
+
+4. Plan
+- Present fix options with risks and verification steps.
+- Recommend one option and request approval.
+
+## Validation
+- Confirm a pre-fix failing signal exists.
+- Confirm post-fix success and run nearby regression checks.
+- Summarize remaining risks and follow-ups.
+
+## Output Template
+Use this response structure:
+- Observed vs Expected
+- Repro and Environment
+- Hypotheses and Tests
+- Options and Recommendation
+- Validation Plan and Results
+- Open Questions

skills/debug/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Debug Assistant"
+  short_description: "Guide structured debugging before code changes"
+  default_prompt: "Use $debug to investigate this issue step by step, produce fix options with risks and validation steps, and wait for confirmation before changing code."