agent-skill-kit 3.9.135

package/.agent/workflows/diagnose.md

@@ -0,0 +1,302 @@
+---
+description: Systematic root cause analysis — hypothesis-driven debugging with ranked probability testing, evidence-based verification, and prevention-first resolution.
+chain: debug-complex
+skills: [debug-pro, code-review, code-craft, problem-checker, context-engineering, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, learner, debugger]
+---
+
+# /diagnose - Root Cause Detective
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Systematic debugging using the scientific method — form hypotheses, gather evidence, and eliminate possibilities until the root cause is found. **Differs from `/fix` (applies targeted fixes for known issues) by focusing exclusively on investigation and root cause identification before any code changes.** Uses `debugger` agent with `debug-pro` for methodology and `code-review` for code analysis.
+
+---
+
+## 🤖 Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate risk, check past bugs & knowledge-compiler patterns |
+| **Execution** | `orchestrator` | Coordinate diagnostic tasks and testing |
+| **Safety** | `recovery` | Save state before debug and restore on failure |
+| **Post-Fix** | `learner` | Log root cause and failure patterns for reuse |
+
+```
+Flow:
+recovery.save() �’ learner.check(past_bugs)
+       ↓
+hypotheses �’ test �’ found? �’ assessor.evaluate(fix)
+       ↓
+apply fix �’ verify �’ learner.log(root_cause, fix)
+       ↓ failure
+recovery.restore()
+```
+
+---
+
+## 🔴 MANDATORY: 5-Phase Investigation Protocol
+
+### Phase 0: Pre-flight & Auto-Learned Context
+
+> **Rule 0.5-K:** Auto-learned pattern check.
+
+1. Read `.agent/skills/auto-learned/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-diagnose"`).
+
+### Phase 1: Pre-flight & knowledge-compiler Context
+
+> **Rule 0.5-K:** knowledge-compiler pattern check.
+
+1. Read `.agent/skills/knowledge-compiler/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-diagnose"`).
+
+### Phase 2: Symptom Collection
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (bug description — error message, unexpected behavior) |
+| **OUTPUT** | Symptom report: error details, environment, reproduction steps |
+| **AGENTS** | `debugger`, `assessor` |
+| **SKILLS** | `debug-pro`, `context-engineering` |
+
+1. `recovery` saves current state before any investigation changes
+2. Gather evidence:
+
+```
+GATHER:
+□ Exact error message (copy/paste)
+□ When did it start?
+□ What changed recently?
+□ Reproduction steps
+□ Expected vs actual behavior
+□ Environment (dev/staging/prod)
+```
+
+3. `learner` checks past bug patterns for similar issues
+
+### Phase 3: Hypothesis Formation
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Symptom report from Phase 2 |
+| **OUTPUT** | 3+ ranked hypotheses with likelihood and test methods |
+| **AGENTS** | `debugger` |
+| **SKILLS** | `debug-pro` |
+
+Generate 3+ ranked hypotheses:
+
+| # | Hypothesis | Likelihood | Test Method |
+|---|-----------|------------|-------------|
+| 1 | [Most likely cause] | 70% | [How to verify] |
+| 2 | [Second possibility] | 20% | [How to verify] |
+| 3 | [Edge case] | 10% | [How to verify] |
+
+**Common Root Causes Checklist:**
+
+| Category | Things to Check |
+|----------|-----------------|
+| **Data** | Null values, wrong types, stale cache |
+| **Auth** | Expired tokens, missing headers, CORS |
+| **Network** | Timeouts, DNS, SSL certificates |
+| **Code** | Recent changes, missing await, wrong imports |
+| **Environment** | Env vars, versions, dependencies |
+
+### Phase 4: Evidence Gathering & Elimination
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Ranked hypotheses from Phase 3 |
+| **OUTPUT** | Investigation log: each hypothesis tested with verdict |
+| **AGENTS** | `debugger` |
+| **SKILLS** | `debug-pro`, `code-review` |
+
+For each hypothesis (highest likelihood first):
+
+1. Define the **TEST**
+2. Predict the **OUTCOME** if hypothesis is true
+3. Run the test
+4. Record **ACTUAL** result
+5. Verdict: ✅ Confirmed or ❌ Eliminated
+
+### Phase 5: Fix & Prevention
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Confirmed root cause from Phase 4 |
+| **OUTPUT** | Code fix + prevention measures |
+| **AGENTS** | `debugger` |
+| **SKILLS** | `debug-pro`, `code-craft` |
+
+1. `assessor` evaluates fix risk before applying
+2. Apply the fix with before/after code comparison
+3. Define prevention measures:
+   - Add test case for this scenario
+   - Add input validation if applicable
+   - Update documentation
+   - Add monitoring/alert if applicable
+4. `learner` logs root cause and fix for future reference
+
+### Phase 6: Verification
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Applied fix from Phase 5 |
+| **OUTPUT** | Verification result: fix confirmed, no regressions |
+| **AGENTS** | `debugger`, `learner` |
+| **SKILLS** | `debug-pro`, `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-6-test
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:diagnose" TRACE_ID="$TRACE_ID" npm test
+```
+
+1. Verify the fix resolves the original symptom
+2. Check for regressions
+3. If fix fails �’ `recovery.restore()` �’ re-investigate
+
+---
+
+## ⛔ MANDATORY: Problem Verification Before Completion
+
+> **CRITICAL:** This check MUST be performed before any `notify_user` or task completion.
+
+### Check @[current_problems]
+
+```
+1. Read @[current_problems] from IDE
+2. If errors/warnings > 0:
+   a. Auto-fix: imports, types, lint errors
+   b. Re-check @[current_problems]
+   c. If still > 0 �’ STOP �’ Notify user
+3. If count = 0 �’ Proceed to completion
+```
+
+### Auto-Fixable
+
+| Type | Fix |
+|------|-----|
+| Missing import | Add import statement |
+| Unused variable | Remove or prefix `_` |
+| Type mismatch | Fix type annotation |
+| Lint errors | Run eslint --fix |
+
+> **Rule:** Never mark complete with errors in `@[current_problems]`.
+
+---
+
+## 🔙 Rollback & Recovery
+
+If investigation causes system instability or tests fail unexpectedly:
+1. Restore to pre-diagnose checkpoint (`git checkout -- .` or `git stash pop`).
+2. Log failure via `learner` meta-agent.
+3. Notify user that debugging environment needs reset before attempting another diagnosis.
+
+---
+
+## Output Format
+
+```markdown
+## 🔍 Diagnosis: [Issue Title]
+
+### Symptom
+
+> [User's description of the problem]
+
+### Environment
+
+| Aspect | Value |
+|--------|-------|
+| File | `src/services/auth.ts` |
+| Line | 42 |
+| Environment | Development |
+| Last Working | 2 commits ago |
+
+### Hypotheses
+
+| # | Hypothesis | Likelihood | Status |
+|---|-----------|------------|--------|
+| 1 | Null reference in user object | 70% | ✅ CONFIRMED |
+| 2 | API timeout | 20% | ❌ Eliminated |
+| 3 | Cache stale data | 10% | ⏳ Not tested |
+
+### Root Cause
+
+🎯 **[Clear explanation of the confirmed root cause]**
+
+### Fix Applied
+
+| File | Change | Status |
+|------|--------|--------|
+| `src/services/auth.ts` | Added null check | ✅ |
+
+### Prevention
+
+- [x] Added null check before accessing properties
+- [ ] Add auth middleware to protect route
+- [ ] Add test for unauthenticated access
+
+### Next Steps
+
+- [ ] Run `/validate` to verify fix with full test suite
+- [ ] Monitor for recurrence
+```
+
+---
+
+## Examples
+
+```
+/diagnose login returns 401 even with correct credentials
+/diagnose form data not saving to database
+/diagnose page crashes on mobile Safari
+/diagnose API response is 10x slower since yesterday
+/diagnose deployment fails on Vercel with exit code 1
+```
+
+---
+
+## Key Principles
+
+- **Never guess** — form hypotheses and test them systematically
+- **Most likely first** — test the highest probability hypothesis before edge cases
+- **Log everything** — document the investigation for future reference
+- **Fix + Prevent** — don't just patch, prevent recurrence with tests and validation
+- **Verify the fix** — always confirm the fix resolves the original symptom
+
+---
+
+## �— Workflow Chain
+
+**Skills Loaded (6):**
+
+- `debug-pro` - Systematic 4-phase debugging methodology
+- `code-review` - Code quality validation and analysis
+- `code-craft` - Coding standards for fix implementation
+- `context-engineering` - Codebase parsing and error trace analysis
+- `problem-checker` - IDE problem verification and auto-fixing
+- `knowledge-compiler` - Finding past bugs and logging new patterns
+
+```mermaid
+graph LR
+    A["/diagnose"] --> B["/fix"]
+    B --> C["/validate"]
+    style A fill:#10b981
+```
+
+| After /diagnose | Run | Purpose |
+|----------------|-----|---------|
+| Root cause found, fix applied | `/validate` | Verify fix with full test suite |
+| Complex fix needed | `/fix` | Apply targeted fix |
+| Ready to deploy | `/launch` | Deploy the fix |
+
+**Handoff to /fix:**
+
+```markdown
+🔍 Root cause found: [description]. Fix applied to [files].
+Run `/fix` for additional targeted fixes or `/validate` to verify.
+```

package/.agent/workflows/fix.md

@@ -0,0 +1,253 @@
+---
+description: Targeted error remediation — triage, patch, and verify specific errors, lint failures, or broken tests with minimal diff and automatic rollback safety.
+chain: debug-complex
+skills: [debug-pro, code-craft, problem-checker, context-engineering, smart-router, knowledge-compiler]
+agents: [orchestrator, assessor, recovery, learner, debugger, backend-specialist, frontend-specialist, test-engineer]
+---
+
+# /fix - The Mechanic
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+Apply immediate, targeted fixes for known errors, lint issues, or test failures — focusing on remediation rather than root cause analysis. **Differs from `/diagnose` (investigates unknown root causes with hypothesis testing) by assuming the problem is already identified and applying the solution directly.** Uses the domain-appropriate specialist agent (auto-routed) with `debug-pro` for fix methodology and `code-craft` for coding standards.
+
+---
+
+## Workflow Modes
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **--auto** (default) | Simple/moderate fixes | Auto-approve if confidence = 9.5 |
+| **--review** | Critical/production code | Pause for user approval |
+| **--quick** | Type/lint errors | Fast fix cycle, minimal analysis |
+
+## Complexity Routing
+
+| Level | Indicators | Action |
+|-------|-----------|--------|
+| **Simple** | Single file, clear error | Quick fix ? verify |
+| **Moderate** | Multi-file, unclear scope | Standard workflow with `recovery` |
+| **Complex** | System-wide impact | Escalate to `/diagnose` first |
+
+---
+
+## ?? Meta-Agents Integration
+
+| Phase | Agent | Action |
+| ----- | ----- | ------ |
+| **Pre-Flight** | `assessor` | Evaluate fix risk and knowledge-compiler context |
+| **Execution** | `orchestrator` | Route fix to specialist agents and coordinate repair |
+| **Safety** | `recovery` | Save state and recover from failed fixes |
+| **Post-Fix** | `learner` | Log error resolution patterns for reuse |
+
+```
+Flow:
+recovery.save() ? analyze error ? apply fix ? verify
+       ? fail
+recovery.restore() ? learner.log(failure)
+       ? success
+learner.log(pattern)
+```
+
+---
+
+## ?? MANDATORY: Repair Protocol
+
+### Phase 1: Pre-flight & knowledge-compiler Context
+
+> **Rule 0.5-K:** knowledge-compiler pattern check.
+
+1. Read `.agent/skills/knowledge-compiler/patterns/` for past failures before proceeding.
+2. Trigger `recovery` agent to run Checkpoint (`git commit -m "chore(checkpoint): pre-fix"`).
+
+### Phase 2: Triage
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | $ARGUMENTS (error message, failing test, or issue description) |
+| **OUTPUT** | Located error: file, line, immediate context, fix type |
+| **AGENTS** | `debugger`, `assessor` |
+| **SKILLS** | `debug-pro`, `context-engineering` |
+
+// turbo — telemetry: phase-2-triage
+
+1. Read error message or failure log
+2. Locate the specific file and line
+3. Classify fix type:
+
+| Type | Action |
+|------|--------|
+| **Code Logic** | Correct algorithms, fix null handling, missing await |
+| **Configuration** | Update env, tsconfig, or package.json |
+| **Database** | Create migrations, fix schema, update queries |
+| **Security** | Sanitize inputs, update dependencies, fix permissions |
+| **Performance** | Optimize queries, add caching, reduce bundle |
+
+4. `recovery` saves checkpoint of affected files
+
+### Phase 3: Apply Fix
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Located error and fix type from Phase 2 |
+| **OUTPUT** | Modified source files with the fix applied |
+| **AGENTS** | `orchestrator`, Auto-routed specialist (`nodejs-pro`, `react-pro`, etc.) |
+| **SKILLS** | `code-craft`, `debug-pro`, `smart-router` |
+
+// turbo — telemetry: phase-3-fix
+
+1. Apply the fix following existing code patterns
+2. Minimal diff — change only what's needed
+3. No unrelated formatting or refactoring
+
+### Phase 4: Verification
+
+| Field | Value |
+|-------|-------|
+| **INPUT** | Modified files from Phase 3 |
+| **OUTPUT** | Verification result: error cleared, tests passing, no regressions |
+| **AGENTS** | `test-architect`, `learner` |
+| **SKILLS** | `problem-checker`, `knowledge-compiler` |
+
+// turbo — telemetry: phase-4-test
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:fix" TRACE_ID="$TRACE_ID" npm test
+```
+
+// turbo — telemetry: phase-4-lint-typecheck
+```bash
+npx cross-env OTEL_SERVICE_NAME="workflow:fix" TRACE_ID="$TRACE_ID" npm run lint; npx cross-env OTEL_SERVICE_NAME="workflow:fix" TRACE_ID="$TRACE_ID" npx tsc --noEmit
+```
+
+1. Verify the original error is resolved
+2. Check for regressions in related components
+3. If fix fails ? `recovery.restore()` ? escalate to `/diagnose`
+4. `learner` logs error pattern for future reference
+
+---
+
+## ? MANDATORY: Problem Verification Before Completion
+
+> **CRITICAL:** This check MUST be performed before any `notify_user` or task completion.
+
+### Check @[current_problems]
+
+```
+1. Read @[current_problems] from IDE
+2. If errors/warnings > 0:
+   a. Auto-fix: imports, types, lint errors
+   b. Re-check @[current_problems]
+   c. If still > 0 ? STOP ? Notify user
+3. If count = 0 ? Proceed to completion
+```
+
+### Auto-Fixable
+
+| Type | Fix |
+|------|-----|
+| Missing import | Add import statement |
+| Unused variable | Remove or prefix `_` |
+| Type mismatch | Fix type annotation |
+| Lint errors | Run eslint --fix |
+
+> **Rule:** Never mark complete with errors in `@[current_problems]`.
+
+---
+
+## ?? Rollback & Recovery
+
+If the attempted fix introduces new errors or fails verification:
+1. Restore to pre-fix checkpoint (`git checkout -- .` or `git stash pop`).
+2. Log failure via `learner` meta-agent to prevent loop.
+3. Automatically escalate to `/diagnose` if root cause is unclear.
+
+---
+
+## Output Format
+
+```markdown
+## ?? Fixed: [Error Description]
+
+### The Issue
+
+[Brief description of what was broken]
+
+### The Fix
+
+| File | Change | Type | Status |
+|------|--------|------|--------|
+| `path/to/file.ts` | Added null check | Code Logic | ? |
+
+### Verification
+
+| Check | Result |
+|-------|--------|
+| Error cleared | ? |
+| Tests passing | ? |
+| Lint clean | ? |
+| IDE Problems | ? 0 |
+
+### Next Steps
+
+- [ ] Run `/validate` for full regression suite
+- [ ] Deploy with `/launch` when ready
+```
+
+---
+
+## Examples
+
+```
+/fix "TypeError: Cannot read property 'map' of undefined"
+/fix "Login tests failing with 401 error"
+/fix "ESLint: no-unused-vars in auth.ts"
+/fix "TypeScript error TS2345 in UserService"
+/fix "failing GitHub Actions CI for test suite"
+```
+
+---
+
+## Key Principles
+
+- **Fix, don't investigate** — assume the problem is known, apply the solution
+- **Minimal diff** — change only what's needed, no unrelated refactoring
+- **Verify immediately** — run tests and lint after every fix
+- **Rollback ready** — checkpoint before fixing, restore on failure
+
+---
+
+## ?? Workflow Chain
+
+**Skills Loaded (6):**
+
+- `debug-pro` - Fix methodology and error analysis
+- `code-craft` - Coding standards for fix implementation
+- `problem-checker` - IDE error detection and auto-fix
+- `context-engineering` - Codebase parsing and error trace analysis
+- `smart-router` - Agent routing for targeted fixes
+- `knowledge-compiler` - Learning and logging failure patterns
+
+```mermaid
+graph LR
+    A["/diagnose"] --> B["/fix"]
+    B --> C["/validate"]
+    C --> D["/launch"]
+    style B fill:#10b981
+```
+
+| After /fix | Run | Purpose |
+|-----------|-----|---------|
+| Fix applied | `/validate` | Full regression suite |
+| Ready to deploy | `/launch` | Deploy the fix |
+| Fix failed | `/diagnose` | Re-analyze root cause |
+
+**Handoff to /validate:**
+
+```markdown
+?? Fix applied to [files]. Error: [description] ? resolved.
+Run `/validate` to ensure no regressions or `/launch` to deploy.
+```