nemonix-cli 1.0.0

package/src/config/claude-code-config/skills/workflow-debug/steps/step-00-init.md

@@ -0,0 +1,94 @@
+---
+name: step-00-init
+description: Initialize debug workflow - parse flags and setup state
+next_step: steps/step-01-analyze.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER skip flag parsing
+- ✅ ALWAYS parse `-a`/`--auto` flag before proceeding
+- 📋 Parse ALL input before any other action
+- 💬 FOCUS on initialization only - don't start debugging yet
+- 🚫 FORBIDDEN to analyze errors in this step
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Parse flags first, then extract error context
+- 💾 Set all state variables before proceeding
+- 📖 Initialize state for subsequent steps
+- 🚫 FORBIDDEN to load step-01 until init complete
+
+## YOUR TASK:
+
+Initialize the debug workflow by parsing flags and extracting the error context from user input.
+
+---
+
+## DEFAULTS CONFIGURATION:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `auto_mode` | false | `-a`/`--auto`: Skip confirmations, use recommended solutions |
+
+---
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Parse Flags and Input
+
+**Load defaults from config above, then parse user input:**
+
+| Flag | Action |
+|------|--------|
+| `-a` or `--auto` | Set `{auto_mode}` = true |
+| Everything else | Set as `{error_context}` |
+
+### 2. Validate Input
+
+**If `{error_context}` is empty:**
+→ Set `{error_context}` = "User will provide error details during analysis"
+
+### 3. Set Initial State
+
+Initialize all variables for the workflow:
+
+| Variable | Initial Value |
+|----------|---------------|
+| `error_context` | Parsed from input |
+| `auto_mode` | Parsed from flags |
+| `error_analysis` | Empty (filled in step 1) |
+| `solutions` | Empty list (filled in step 2) |
+| `selected_solution` | Empty (filled in step 3) |
+| `files_modified` | Empty list (filled in step 4) |
+| `verification_result` | Empty (filled in step 5) |
+
+### 4. Proceed to Analysis
+
+→ Proceed directly to step-01 (no confirmation needed)
+
+---
+
+## SUCCESS METRICS:
+
+✅ Flags correctly parsed (`-a`/`--auto` detected)
+✅ Error context extracted or placeholder set
+✅ All state variables initialized
+
+## FAILURE MODES:
+
+❌ Proceeding without parsing flags
+❌ Starting to analyze the error in this step
+❌ Missing state variables for subsequent steps
+
+---
+
+## NEXT STEP:
+
+After initialization, load `./step-01-analyze.md`
+
+<critical>
+Remember: Init is ONLY about setup - don't start debugging here!
+</critical>

package/src/config/claude-code-config/skills/workflow-debug/steps/step-01-analyze.md

@@ -0,0 +1,180 @@
+---
+name: step-01-analyze
+description: Analyze the error in depth to understand root cause
+prev_step: steps/step-00-init.md
+next_step: steps/step-02-find-solutions.md
+---
+
+# Step 1: Analyze the Error
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER propose solutions in this step
+- ✅ ALWAYS gather complete error context before concluding
+- 📋 YOU ARE AN INVESTIGATOR, not a fixer
+- 💬 FOCUS on understanding the problem only
+- 🚫 FORBIDDEN to make code changes
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis reasoning before conclusions
+- 💾 Document all findings in `{error_analysis}`
+- 📖 Complete investigation before loading next step
+- 🚫 FORBIDDEN to load step-02 until analysis is thorough
+
+## CONTEXT BOUNDARIES:
+
+- Variables from step-00: `{error_context}`, `{auto_mode}`
+- Don't assume solutions exist yet
+- Focus purely on understanding what's wrong
+
+## YOUR TASK:
+
+Investigate the error thoroughly to understand its root cause, affected files, and scope of impact.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Gather Error Information
+
+**Read the COMPLETE error message first** - don't skim!
+- Parse the exact error message and type
+- Identify file paths and line numbers from stack trace
+- Note any error codes, exit codes, or status
+
+**If no specific error:**
+- Ask user to describe exact symptoms
+- Check `git status` and `git log --oneline -10` for recent changes
+- Look for obvious issues in mentioned files
+
+### 2. Reproduce the Error (CRITICAL)
+
+<critical>
+If you cannot reproduce consistently, you cannot verify a fix. This is non-negotiable.
+</critical>
+
+**Attempt reproduction:**
+- Run the exact command/action that triggers the error
+- Document the minimal steps to reproduce
+- Note any conditions (environment, data, timing)
+
+**If cannot reproduce:**
+- **→ Trigger Log Technique**: Load `./step-01b-log-instrumentation.md`
+- Check for Heisenbug indicators (timing-sensitive, race condition)
+- Ask user for more context about when it occurs
+
+<critical>
+When reproduction fails, the Log Technique is your best tool!
+Add strategic debug logs → User runs app → User shares output → Analyze
+</critical>
+
+### 3. Form Hypotheses (Ranked)
+
+**List 3-5 possible causes in order of likelihood:**
+
+| Rank | Hypothesis | Evidence | How to Test |
+|------|------------|----------|-------------|
+| Most Likely | *What you think is wrong* | *What supports this* | *How to verify/disprove* |
+| Likely | ... | ... | ... |
+| Possible | ... | ... | ... |
+
+**Test hypotheses systematically** - don't jump to the first idea!
+
+### 4. Investigate the Codebase
+
+**Search for relevant code:**
+- Use Grep to find related patterns
+- Read files mentioned in error COMPLETELY
+- Check imports and dependencies
+- Look for similar patterns that work elsewhere
+
+**Build context:**
+- What function/component is failing?
+- What data flows through this code?
+- Check git blame: who changed this recently and why?
+
+### 5. Identify Root Cause
+
+**Validate against hypotheses:**
+- Which hypothesis is confirmed/rejected by evidence?
+- What is the immediate cause vs. deeper underlying issue?
+- Are there related problems?
+
+**Document your analysis with:**
+
+| Field | Value |
+|-------|-------|
+| Error Type | *Type of error* |
+| Error Message | *Exact error message* |
+| Reproducible? | Yes / No |
+| Reproduction Steps | *Minimal steps to trigger* |
+| Root Cause | *What's actually causing this* |
+| Affected Files | *List of files involved* |
+| Scope | Localized / Widespread |
+| Complexity | Simple / Moderate / Complex |
+| Verification Method | *How to verify the fix works* |
+
+**Hypotheses tested:**
+
+| Hypothesis | Result |
+|------------|--------|
+| *What you thought* | Confirmed / Rejected |
+| ... | ... |
+
+### 6. Ask for Additional Context
+
+**If `{auto_mode}` = true:**
+→ Proceed to step-02 automatically
+
+**If `{auto_mode}` = false:**
+
+Present analysis summary, then use **AskUserQuestion** with:
+- **Header:** "Context"
+- **Question:** "Do you have additional information that could help with the analysis?"
+- **Options:**
+  1. "No, continue (Recommended)" → Analysis is sufficient, proceed to find solutions
+  2. "Yes, I have more info" → Let me provide additional context
+
+**Handle responses:**
+- **"No, continue":** Load step-02
+- **"Yes, I have more info":** Wait for user input, update `{error_analysis}`, then proceed to step-02
+
+**If reproduction was impossible:**
+→ Offer to use Log Technique (step-01b) before proceeding
+
+---
+
+## SUCCESS METRICS:
+
+✅ Error reproduced (or documented why it can't be)
+✅ 3+ hypotheses formed and tested systematically
+✅ Root cause clearly identified with evidence
+✅ Affected files documented
+✅ Verification method identified for later
+✅ `{error_analysis}` state variable populated
+
+## FAILURE MODES:
+
+❌ Jumping to solutions without thorough analysis
+❌ Skipping reproduction attempt
+❌ Testing only one hypothesis (tunnel vision)
+❌ Missing key files or dependencies in investigation
+❌ **CRITICAL**: Making code changes in this step
+
+## ANALYSIS PROTOCOLS:
+
+- Read actual error messages, don't assume
+- Check git history for recent changes that might have caused this
+- Look at test files to understand expected behavior
+- Don't skip investigating even if solution seems obvious
+
+---
+
+## NEXT STEP:
+
+After analysis confirmed, load `./step-02-find-solutions.md`
+
+<critical>
+Remember: This step is ONLY about analysis - don't fix or propose solutions yet!
+</critical>

package/src/config/claude-code-config/skills/workflow-debug/steps/step-01b-log-instrumentation.md

@@ -0,0 +1,271 @@
+---
+name: step-01b-log-instrumentation
+description: Add strategic logs and collect user feedback for visibility
+prev_step: steps/step-01-analyze.md
+next_step: steps/step-02-find-solutions.md
+reference: references/log-technique.md
+---
+
+# Step 1b: Log Instrumentation Technique
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER propose solutions in this step
+- ✅ ALWAYS add logs with proper prefixes `[DEBUG:xxx]`
+- 📋 YOU ARE AN INSTRUMENTER, adding visibility to the code
+- 💬 FOCUS on gathering runtime information only
+- 🚫 FORBIDDEN to fix the bug or change logic
+- 🔒 NEVER log sensitive data (passwords, tokens, PII)
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your log placement strategy before adding logs
+- 💾 Track all added logs in `{debug_logs}` for later removal
+- 📖 Wait for user to run and share logs before proceeding
+- 🚫 FORBIDDEN to proceed without log output from user
+
+## CONTEXT BOUNDARIES:
+
+- Variables from step-01: `{error_context}`, `{auto_mode}`, `{error_analysis}`
+- This step is OPTIONAL - only triggered when reproduction fails
+- Load [references/log-technique.md](../references/log-technique.md) for patterns
+
+## YOUR TASK:
+
+Add strategic debug logs to the suspected code area and ask the user to run the application and share the log output for analysis.
+
+---
+
+## When This Step Is Triggered
+
+This step is used when:
+- ❌ Cannot reproduce the error directly
+- 🌐 Bug only occurs in user's environment
+- ⏱️ Intermittent/timing-sensitive issue
+- 🔍 Need visibility into actual runtime behavior
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Identify Log Placement Areas
+
+Based on `{error_analysis}`, identify where to add logs:
+
+**Suspected Code Areas:**
+
+| Area | File | Lines | Why Log Here |
+|------|------|-------|--------------|
+| Entry point | {file} | {lines} | *To confirm function is called* |
+| Decision point | {file} | {lines} | *To see which branch is taken* |
+| Data transformation | {file} | {lines} | *To see actual values* |
+| Exit point | {file} | {lines} | *To see final result* |
+
+### 2. Add Debug Logs
+
+<critical>
+Use the [Log Technique Reference](../references/log-technique.md) for proper formatting!
+</critical>
+
+**Log Prefix Convention:**
+- `[DEBUG:entry]` - Function entry
+- `[DEBUG:exit]` - Function exit
+- `[DEBUG:decision]` - Conditional checks
+- `[DEBUG:branch]` - Branch taken
+- `[DEBUG:transform]` - Data changes
+- `[DEBUG:async]` - Async operations
+- `[DEBUG:state]` - State snapshots
+- `[DEBUG:error]` - Caught errors
+
+**For each log added, track it:**
+
+| # | File | Line | Prefix | Purpose |
+|---|------|------|--------|---------|
+| 1 | {path} | {line} | `[DEBUG:entry]` | *What you're checking* |
+| 2 | {path} | {line} | `[DEBUG:decision]` | *What condition* |
+| 3 | ... | ... | ... | ... |
+
+**Example Implementation:**
+
+```javascript
+// At function entry
+console.log('[DEBUG:entry] processOrder', {
+  timestamp: new Date().toISOString(),
+  orderId: order.id,
+  itemCount: order.items.length
+});
+
+// At decision point
+console.log('[DEBUG:decision] validateOrder', {
+  isValid: order.items.length > 0,
+  hasPayment: !!order.paymentMethod
+});
+
+// At async boundary
+console.log('[DEBUG:async:start] fetchInventory', { time: Date.now() });
+const inventory = await fetchInventory(order.items);
+console.log('[DEBUG:async:end] fetchInventory', {
+  time: Date.now(),
+  found: inventory.length
+});
+```
+
+### 3. Security Check
+
+<critical>
+Before asking user to run, verify NO sensitive data is logged!
+</critical>
+
+**Checklist:**
+- [ ] No passwords or tokens
+- [ ] No API keys or secrets
+- [ ] No personal identifiable information (PII)
+- [ ] No credit card numbers
+- [ ] No session IDs
+
+**If sensitive data needed, sanitize:**
+```javascript
+// BAD
+console.log('[DEBUG]', { password });
+
+// GOOD
+console.log('[DEBUG]', {
+  passwordProvided: !!password,
+  passwordLength: password?.length
+});
+```
+
+### 4. Ask User to Run and Share Logs
+
+**If `{auto_mode}` = true:**
+→ Skip this step entirely - cannot use log technique in auto mode
+→ Proceed to step-02 with best available analysis
+
+**If `{auto_mode}` = false:**
+
+Present summary of added logs, then use **AskUserQuestion**:
+
+```yaml
+questions:
+  - header: "Run App"
+    question: "I've added {N} debug logs to track the issue. Please run the application, reproduce the error, and paste the console output back here. Ready?"
+    options:
+      - label: "I'll run it now (Recommended)"
+        description: "I'll execute the app and share the logs"
+      - label: "Logs aren't in right place"
+        description: "I think the problem is elsewhere"
+      - label: "Can't run it now"
+        description: "I'll do this later or skip"
+    multiSelect: false
+```
+
+**Handle responses:**
+- **"I'll run it now":** Wait for user to paste logs, then proceed to Analysis
+- **"Logs aren't in right place":** Ask where they think the issue is, add logs there
+- **"Can't run it now":** Proceed to step-02 with current analysis
+
+### 5. Analyze Returned Logs
+
+When user shares logs:
+
+**Parse the output:**
+1. Look for all `[DEBUG:xxx]` lines
+2. Check execution order (timestamps if present)
+3. Identify unexpected values or missing logs
+4. Note which branches were taken
+
+**Log Analysis:**
+
+| Log | Expected | Actual | Insight |
+|-----|----------|--------|---------|
+| `[DEBUG:entry] func` | Called once | Called 3x | *Unexpected multiple calls* |
+| `[DEBUG:decision] check` | `true` | `false` | *Condition failing* |
+| `[DEBUG:async:end]` | Present | Missing | *Promise never resolved* |
+
+**Update `{error_analysis}` with findings:**
+- What the logs revealed
+- Root cause (if now clear)
+- Any remaining unknowns
+
+### 6. Decide Next Action
+
+**Use AskUserQuestion:**
+
+```yaml
+questions:
+  - header: "Analysis"
+    question: "Based on the logs, I found: [summary]. What would you like to do?"
+    options:
+      - label: "Proceed to fix (Recommended)"
+        description: "The root cause is clear, let's find solutions"
+      - label: "Add more logs"
+        description: "Need deeper visibility in another area"
+      - label: "Different area"
+        description: "The problem seems to be elsewhere"
+    multiSelect: false
+```
+
+**Handle responses:**
+- **"Proceed to fix":** Update `{error_analysis}`, go to step-02
+- **"Add more logs":** Return to step 2, add more targeted logs
+- **"Different area":** Update suspected area, return to step 2
+
+### 7. Track Logs for Cleanup
+
+**Store in `{debug_logs}` for later removal:**
+
+```yaml
+debug_logs:
+  - file: "src/api.ts"
+    line: 45
+    prefix: "[DEBUG:entry]"
+  - file: "src/api.ts"
+    line: 52
+    prefix: "[DEBUG:exit]"
+  - file: "src/utils.ts"
+    line: 23
+    prefix: "[DEBUG:transform]"
+```
+
+<critical>
+These logs MUST be removed in step-04-fix or step-05-verify!
+</critical>
+
+---
+
+## SUCCESS METRICS:
+
+✅ Strategic logs added at key checkpoints
+✅ All added logs tracked in `{debug_logs}`
+✅ No sensitive data in logs
+✅ User ran app and shared log output
+✅ Log output analyzed for insights
+✅ `{error_analysis}` updated with findings
+✅ Root cause clearer than before
+
+## FAILURE MODES:
+
+❌ Adding logs without a clear strategy
+❌ Logging sensitive data (passwords, tokens, PII)
+❌ Not tracking logs for later removal
+❌ Proceeding without user log output (unless auto mode)
+❌ **CRITICAL**: Making code fixes in this step
+❌ **CRITICAL**: Not asking user to run and share logs
+
+## STATE UPDATES:
+
+After this step, ensure:
+- `{error_analysis}` includes log findings
+- `{debug_logs}` lists all added logs for cleanup
+- Decision recorded on whether to iterate or proceed
+
+---
+
+## NEXT STEP:
+
+After log analysis complete, load `./step-02-find-solutions.md`
+
+<critical>
+Remember: This step is about VISIBILITY - don't fix anything yet!
+All debug logs MUST be removed later - track them carefully!
+</critical>

package/src/config/claude-code-config/skills/workflow-debug/steps/step-02-find-solutions.md

@@ -0,0 +1,141 @@
+---
+name: step-02-find-solutions
+description: Research and identify potential solutions to the error
+prev_step: steps/step-01-analyze.md
+next_step: steps/step-03-propose.md
+---
+
+# Step 2: Find Solutions
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER implement solutions in this step
+- ✅ ALWAYS find at least 2-3 potential solutions
+- 📋 YOU ARE A RESEARCHER, not an implementer
+- 💬 FOCUS on identifying options only
+- 🚫 FORBIDDEN to modify any files
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Research thoroughly before listing solutions
+- 💾 Document each solution with pros/cons in `{solutions}`
+- 📖 Complete solution research before loading next step
+- 🚫 FORBIDDEN to load step-03 until multiple solutions identified
+
+## CONTEXT BOUNDARIES:
+
+- Variables from previous steps: `{error_context}`, `{auto_mode}`, `{error_analysis}`
+- Use analysis to guide solution research
+- Don't assume one solution is best yet
+
+## YOUR TASK:
+
+Research and identify multiple potential solutions to the error, documenting trade-offs for each.
+
+---
+
+## Available State
+
+From previous steps:
+
+| Variable | Description |
+|----------|-------------|
+| `{error_context}` | Original error description |
+| `{auto_mode}` | Skip confirmations flag |
+| `{error_analysis}` | Analysis from step 1 with root cause, affected files |
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Review Analysis
+
+**Load from `{error_analysis}`:**
+- Root cause identified
+- Affected files list
+- Error complexity
+
+### 2. Research Solutions
+
+**For each potential fix approach:**
+
+**Search codebase for patterns:**
+- How are similar issues handled elsewhere?
+- Are there existing utilities or helpers to use?
+- What patterns does the codebase follow?
+
+**Consider solution types:**
+1. **Quick fix** - Minimal change to resolve immediate issue
+2. **Proper fix** - Address root cause properly
+3. **Refactor fix** - Improve architecture while fixing
+
+### 3. Document Solutions
+
+**For each solution found (minimum 2, ideally 3-4), document:**
+
+#### Solution 1: *Name*
+
+| Field | Value |
+|-------|-------|
+| **Approach** | *What this solution does* |
+| **Files to modify** | *file1, file2, ...* |
+| **Effort** | Low / Medium / High |
+| **Risk** | Low / Medium / High |
+| **Recommended?** | Yes / No |
+
+**Pros:**
+- Advantage 1
+- Advantage 2
+
+**Cons:**
+- Disadvantage 1
+
+*(Repeat for each solution)*
+
+### 4. Rank Solutions
+
+**Determine recommendation based on:**
+- Balance of effort vs. completeness
+- Risk of introducing new bugs
+- Alignment with codebase patterns
+- Long-term maintainability
+
+**Mark ONE solution as recommended**
+
+### 5. Proceed to Proposal
+
+→ Proceed directly to step-03 (no confirmation needed)
+
+---
+
+## SUCCESS METRICS:
+
+✅ At least 2 distinct solutions identified
+✅ Each solution has pros/cons documented
+✅ Effort and risk assessed for each
+✅ One solution marked as recommended
+✅ `{solutions}` state variable populated
+
+## FAILURE MODES:
+
+❌ Only finding one solution
+❌ Missing pros/cons analysis
+❌ Not identifying affected files for each solution
+❌ **CRITICAL**: Implementing any solution in this step
+
+## RESEARCH PROTOCOLS:
+
+- Check how similar code handles edge cases
+- Look for tests that might guide the solution
+- Consider backwards compatibility
+- Don't overlook simple solutions
+
+---
+
+## NEXT STEP:
+
+After solutions documented, load `./step-03-propose.md`
+
+<critical>
+Remember: This step is ONLY about finding options - don't implement or choose yet!
+</critical>