Fix debug skill: rename to debug_tool to avoid platform bug

README.md

@@ -113,7 +113,7 @@ Each role has two layers of knowledge:
 | `/requirements` | Gather and track requirements |
 | `/architecture` | Design with tradeoffs |
 | `/implementation` | Build with TDD |
-| `/debug` | Hypothesis-driven debugging |
+| `/debug_tool` | Hypothesis-driven debugging |
 | `/precommit` | Quality gate before commit |
 | `/evaluate` | Quality score (push gate) |
 | `/reviewer` | Code review |

architecture/role-context-layer.md

@@ -13,24 +13,24 @@ Roles are **specialized agents with pre-learned domain knowledge** from indexed
 
 | # | Role | Category | Skills Used |
 |---|------|----------|-------------|
-| 1 | Backend Engineer | Core | `/implementation`, `/debug`, `/architecture`, `/setup` |
-| 2 | Frontend Developer | Core | `/implementation`, `/debug`, `/explore` |
-| 3 | iOS Developer | Mobile | `/implementation`, `/debug`, `/setup` |
-| 4 | Android Developer | Mobile | `/implementation`, `/debug`, `/setup` |
-| 5 | DBA | Data | `/debug`, `/evaluate`, `/assess` |
-| 6 | Data Engineer | Data | `/implementation`, `/debug`, `/setup` |
+| 1 | Backend Engineer | Core | `/implementation`, `/debug_tool`, `/architecture`, `/setup` |
+| 2 | Frontend Developer | Core | `/implementation`, `/debug_tool`, `/explore` |
+| 3 | iOS Developer | Mobile | `/implementation`, `/debug_tool`, `/setup` |
+| 4 | Android Developer | Mobile | `/implementation`, `/debug_tool`, `/setup` |
+| 5 | DBA | Data | `/debug_tool`, `/evaluate`, `/assess` |
+| 6 | Data Engineer | Data | `/implementation`, `/debug_tool`, `/setup` |
 | 7 | Data Scientist | Data | `/explore`, `/implementation`, `/evaluate` |
-| 8 | AI/ML Engineer | AI/ML | `/implementation`, `/debug`, `/architecture`, `/setup` |
-| 9 | Infrastructure Engineer | Infra | `/setup`, `/debug`, `/architecture`, `/assess` |
-| 10 | Security Engineer | Cross-cutting | `/reviewer`, `/evaluate`, `/assess`, `/debug` |
-| 11 | Production Engineer | Cross-cutting | `/verify`, `/debug`, `/evaluate`, `/explore` |
+| 8 | AI/ML Engineer | AI/ML | `/implementation`, `/debug_tool`, `/architecture`, `/setup` |
+| 9 | Infrastructure Engineer | Infra | `/setup`, `/debug_tool`, `/architecture`, `/assess` |
+| 10 | Security Engineer | Cross-cutting | `/reviewer`, `/evaluate`, `/assess`, `/debug_tool` |
+| 11 | Production Engineer | Cross-cutting | `/verify`, `/debug_tool`, `/evaluate`, `/explore` |
 | 12 | QA Engineer | Cross-cutting | `/implementation`, `/evaluate`, `/reviewer`, `/setup` |
 | 13 | System Architect | Cross-cutting | `/architecture`, `/assess`, `/explore`, `/requirements` |
-| 14 | Code Health Engineer | Cross-cutting | `/assess`, `/debug`, `/reviewer`, `/evaluate` |
+| 14 | Code Health Engineer | Cross-cutting | `/assess`, `/debug_tool`, `/reviewer`, `/evaluate` |
 | 15 | Requirements Engineer | Cross-cutting | `/requirements`, `/verify`, `/evaluate`, `/status` |
 | 16 | Research Engineer | Cross-cutting | `/explore`, `/architecture`, `/assess`, `/evaluate` |
-| 17 | Game Developer | Specialized | `/implementation`, `/debug`, `/setup` |
-| 18 | Embedded/IoT Developer | Specialized | `/implementation`, `/debug`, `/setup` |
+| 17 | Game Developer | Specialized | `/implementation`, `/debug_tool`, `/setup` |
+| 18 | Embedded/IoT Developer | Specialized | `/implementation`, `/debug_tool`, `/setup` |
 | 19 | Legal & Compliance Engineer | Cross-cutting | `/explore`, `/evaluate`, `/requirements` |
 
 ## Four Layers
@@ -73,7 +73,7 @@ Roles are **specialized agents with pre-learned domain knowledge** from indexed
 │                                                         │
 │  Role receives task from skill workflow                  │
 │  → Consults pre-learned knowledge (no web research)     │
-│  → Uses existing skills (/implementation, /debug, etc.) │
+│  → Uses existing skills (/implementation, /debug_tool, etc.) │
 │  → LLM writes code using learned patterns               │
 │  → Invokes other roles when skill says to (deterministic)│
 │  → Multiple cheap agents for parallel sub-tasks         │
@@ -330,7 +330,7 @@ duties:
   - Implement authentication and authorization
   - Set up error handling and logging
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/architecture", "/setup", "/precommit"]
   evaluation: ["/reviewer", "/evaluate"]
 invokes:

docs/skills.md

@@ -10,7 +10,7 @@ Append **`auto`** to chain skills without stopping: `/requirements auto my-app`.
 | `/requirements` | Gather and validate requirements |
 | `/architecture` | Design with trade-offs and user journey |
 | `/implementation` | TDD — skeleton → slabs; fix, refactor, demo modes |
-| `/debug` | Hypothesis-driven debugging with reproduction tests |
+| `/debug_tool` | Hypothesis-driven debugging with reproduction tests |
 | `/assess` | Architecture fitness audit |
 | `/verify` | Output quality check — is it useful, not just correct? |
 | `/precommit` | Pre-commit quality gate (required before commit by default) |
@@ -35,10 +35,10 @@ Skill definitions live in `skills/*/SKILL.md`.
 
 ## Skill tool errors
 
-If `/debug` (or another skill) errors with `disable-model-invocation`:
+If `/debug_tool` (or another skill) errors with `disable-model-invocation`:
 
 ```
-Read skills/debug/SKILL.md and follow it
+Read skills/debug_tool/SKILL.md and follow it
 ```
 
 Or use natural language: "debug the failing test in …"

docs/workflow.md

@@ -8,7 +8,7 @@ How to build, commit, and push with Agent Toolkit gates.
 |-----------|------------|
 | New project | `/requirements` → `/architecture` → `/implementation` |
 | Existing repo | `/explore .` → `/implementation` |
-| Bug | "fix …" or `/debug` |
+| Bug | "fix …" or `/debug_tool` |
 | Before release | `/reviewer` → `/evaluate` |
 | Hands-off pipeline | `/requirements auto my-app` — see [orchestrator](../shared/orchestrator.md) |
 

hooks/auto_handoff.py

@@ -96,7 +96,7 @@ def write_auto_handoff(
 
 ## Resume Command
 
-Read project-state.md and this file. Use agent-toolkit skills for all work (/implementation, /debug, /precommit, etc.). Continue from where the previous session stopped.
+Read project-state.md and this file. Use agent-toolkit skills for all work (/implementation, /debug_tool, /precommit, etc.). Continue from where the previous session stopped.
 """
     handoff_path.write_text(content, encoding="utf-8")
 

hooks/finalize_report.py

@@ -212,7 +212,7 @@ def _check_session_audit() -> dict:
 
         warnings = []
         if usage.get("skill_count", 0) == 0:
-            warnings.append("No skills invoked this session — consider using /implementation, /debug, or /architecture")
+            warnings.append("No skills invoked this session — consider using /implementation, /debug_tool, or /architecture")
         if usage.get("agents_without_model", 0) > 0:
             count = usage["agents_without_model"]
             warnings.append(f"{count} agent(s) spawned without model parameter — consider setting model for cost efficiency")

hooks/route_to_skill.py

@@ -34,7 +34,7 @@
             r"|throwing.*error|getting.*error",
             re.IGNORECASE,
         ),
-        "debug",
+        "debug_tool",
     ),
     # Deploy / setup — before build so "set up env" matches setup not build
     (
@@ -119,10 +119,10 @@
 ]
 
 SKILL_CONTEXTS = {
-    "debug": (
-        "SKILL ROUTING: This looks like a bug fix. Follow the /debug workflow.\n"
-        "1. Read skills/debug/SKILL.md with the Read tool — follow it strictly\n"
-        "2. Do NOT call the Skill tool (use Read instead; Skill tool may error on /debug)\n"
+    "debug_tool": (
+        "SKILL ROUTING: This looks like a bug fix. Follow the /debug_tool workflow.\n"
+        "1. Read skills/debug_tool/SKILL.md with the Read tool — follow it strictly\n"
+        "2. Do NOT call the Skill tool (use Read instead; Skill tool may error on /debug_tool)\n"
         "3. Hypothesis-driven: form hypotheses, test them, eliminate\n"
         "4. Write a FAILING test that reproduces the bug BEFORE fixing\n"
         "5. Fix the code to make the test pass\n"
@@ -204,7 +204,7 @@ def make_hook_response(message: str) -> str:
 # Map skill routing intents to orchestration task types
 _INTENT_TO_TASK_TYPE = {
     "build": "new_feature",
-    "debug": "bug_fix",
+    "debug_tool": "bug_fix",
     "refactor": "refactor",
 }
 

hooks/session_init.py

@@ -354,7 +354,7 @@ def build_context(
     parts.append("")
     parts.append("""MANDATORY RULES:
 1. NEVER edit code without following a skill workflow. Read the skill .md file first.
-2. For bug fixes: follow /debug (hypothesis-driven, test-first)
+2. For bug fixes: follow /debug_tool (hypothesis-driven, test-first)
 3. For new features: follow /implementation (plan, TDD, slabs)
 4. For refactors: follow /implementation in refactor mode
 5. ALWAYS write a failing test BEFORE fixing or implementing
@@ -369,7 +369,7 @@ def build_context(
 - Show evidence (file:line) for every claim
 - If unsure, ask. Don't assume.
 
-AVAILABLE SKILLS: /requirements /architecture /implementation /debug /verify /precommit /evaluate /reviewer /assess /explore /setup /status /updater
+AVAILABLE SKILLS: /requirements /architecture /implementation /debug_tool /verify /precommit /evaluate /reviewer /assess /explore /setup /status /updater
 
 SESSION MONITOR ACTIVE: This session is tracked. Cumulative output bytes and context compaction are the active limits. Warning at 500KB output, hard stop at 700KB or first compaction — you get 10 tool calls to write HANDOFF.md and commit, then all non-handoff operations are blocked. Exchange count is tracked for diagnostics only.
 

hooks/session_limits.py

@@ -30,7 +30,7 @@
 Read HANDOFF.md first. You are continuing a multi-session task. The previous session hit its time/context limit. Pick up exactly where it left off:
 1. Read HANDOFF.md for goal, progress, and next steps
 2. Read project-state.md for overall project context
-3. Use agent-toolkit skills for all work (/implementation, /debug, /precommit, etc.)
+3. Use agent-toolkit skills for all work (/implementation, /debug_tool, /precommit, etc.)
 4. Continue the work — do NOT re-do completed items listed above
 
 ---

hooks/skill_enforce.py

@@ -2,7 +2,7 @@
 """skill_enforce.py — Block code edits without an active skill workflow.
 
 PreToolUse hook on Edit and Write tools. Ensures the agent is following
-a skill (/implementation, /debug, /architecture, /requirements) before
+a skill (/implementation, /debug_tool, /architecture, /requirements) before
 making code changes. Prevents the LLM from skipping skill workflows.
 
 Modes:
@@ -38,7 +38,7 @@
 
 # Skills that authorize code changes
 CODE_CHANGE_SKILLS = {
-    "implementation", "debug", "fix", "refactor",
+    "implementation", "debug_tool", "fix", "refactor",
     "setup", "explore",  # explore is read-only but setup writes configs
 }
 
@@ -143,7 +143,7 @@ def run_skill_enforce(
         "SKILL REQUIRED: You are editing code without following a skill workflow. "
         "Before making code changes:\n"
         "- New feature → run /requirements then /implementation\n"
-        "- Bug fix → run /debug\n"
+        "- Bug fix → run /debug_tool\n"
         "- Refactor → run /implementation in refactor mode\n"
         "- Architecture change → run /architecture first\n"
         "Do NOT edit code directly. Follow the skill workflow."

requirements/strict-mode.md

@@ -117,7 +117,7 @@ In strict mode, the slab cycle gains a mandatory step between SETUP and TDD:
 
 ## What Strict Mode Does NOT Change
 
-- Skill workflows (/implementation, /debug, etc.) — same, just stricter enforcement
+- Skill workflows (/implementation, /debug_tool, etc.) — same, just stricter enforcement
 - Gate mechanism (legacy/signed) — same, just requires /evaluate too
 - Auto-continuation — same, but drift can trigger restart
 - Normal sessions — unaffected when mode != strict

roles/PRODUCT-ROLE-MAPPING.md

@@ -23,7 +23,7 @@
 | **Research Engineer** | New robotics platforms, AMR vendor evaluation, industry 4.0 standards |
 | **Legal & Compliance** | Industrial safety regulations (OSHA), equipment certification, data retention for safety audits |
 
-**Skills used:** `/architecture` (layered system design), `/implementation` (WMS logic), `/debug` (equipment communication issues), `/setup` (edge deployment), `/evaluate` (system reliability)
+**Skills used:** `/architecture` (layered system design), `/implementation` (WMS logic), `/debug_tool` (equipment communication issues), `/setup` (edge deployment), `/evaluate` (system reliability)
 
 ---
 
@@ -45,7 +45,7 @@
 | **Requirements Engineer** | Spades rule variants tracking, tournament format specs |
 | **Legal & Compliance** | Gambling law implications (if real money), age restrictions by country |
 
-**Skills used:** `/implementation` (game server), `/architecture` (networking model), `/debug` (desync issues), `/verify` (rule correctness)
+**Skills used:** `/implementation` (game server), `/architecture` (networking model), `/debug_tool` (desync issues), `/verify` (rule correctness)
 
 ---
 
@@ -69,7 +69,7 @@
 | **Requirements Engineer** | 30+ civilization specs, tech tree tracking, balance requirements |
 | **Legal & Compliance** | Age ratings (ESRB/PEGI), in-app purchase regulations for mobile |
 
-**Skills used:** `/architecture` (engine + networking), `/implementation` (game systems), `/debug` (desync, pathfinding), `/evaluate` (performance), `/explore` (existing engine patterns)
+**Skills used:** `/architecture` (engine + networking), `/implementation` (game systems), `/debug_tool` (desync, pathfinding), `/evaluate` (performance), `/explore` (existing engine patterns)
 
 ---
 
@@ -115,7 +115,7 @@
 | **Requirements Engineer** | Supported languages, accuracy targets, supported video formats/sources |
 | **Legal & Compliance** | TOS implications of scraping videos from platforms, content storage policies, GDPR for processed data |
 
-**Skills used:** `/implementation` (pipeline), `/architecture` (GPU serving), `/setup` (infrastructure), `/debug` (accuracy issues), `/evaluate` (transcription quality)
+**Skills used:** `/implementation` (pipeline), `/architecture` (GPU serving), `/setup` (infrastructure), `/debug_tool` (accuracy issues), `/evaluate` (transcription quality)
 
 ---
 
@@ -166,7 +166,7 @@
 | **Requirements Engineer** | Feature parity across platforms, offline capability specs, audio quality tier definitions |
 | **Legal & Compliance*** | Music licensing (per-country rights), royalty tracking and reporting (legal requirement), DMCA compliance, territory restrictions |
 
-**Skills used:** `/architecture` (streaming + DRM), `/implementation` (player + API), `/debug` (playback issues), `/setup` (CDN + infrastructure), `/evaluate` (audio quality)
+**Skills used:** `/architecture` (streaming + DRM), `/implementation` (player + API), `/debug_tool` (playback issues), `/setup` (CDN + infrastructure), `/evaluate` (audio quality)
 
 ---
 
@@ -191,7 +191,7 @@
 | **Requirements Engineer** | Supported devices/platforms, codec support matrix, feature comparison with Plex/Jellyfin |
 | **Embedded/IoT** | Smart TV app development (limited runtime environments), Roku/Fire TV platform constraints |
 
-**Skills used:** `/explore` (Jellyfin/Plex codebase), `/architecture` (transcoding engine), `/implementation` (scanner + player), `/setup` (Docker deployment), `/debug` (codec issues)
+**Skills used:** `/explore` (Jellyfin/Plex codebase), `/architecture` (transcoding engine), `/implementation` (scanner + player), `/setup` (Docker deployment), `/debug_tool` (codec issues)
 
 ---
 

roles/ROLE-DEFINITIONS-DRAFT.md

@@ -6,7 +6,7 @@
 
 ## What Existing Skills Already Cover (DON'T repeat in roles)
 
-Our `/implementation`, `/debug`, `/reviewer`, `/precommit`, `/architecture` skills already handle:
+Our `/implementation`, `/debug_tool`, `/reviewer`, `/precommit`, `/architecture` skills already handle:
 - Programming fundamentals, data structures, algorithms
 - Git workflow, version control
 - Testing principles (TDD, unit/integration)

roles/ai-ml/role.md

@@ -12,7 +12,7 @@ duties:
   - Implement MLOps (experiment tracking, model registry, versioning)
   - Optimize models for production (quantization, pruning)
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/architecture", "/setup"]
 invokes:
   for_model_dev: ["data-scientist"]

roles/android/role.md

@@ -11,7 +11,7 @@ duties:
   - Battery and memory optimization
   - Play Store releases, staged rollouts
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/setup", "/precommit"]
 invokes:
   for_api_contracts: ["backend"]

roles/backend/role.md

@@ -16,7 +16,7 @@ duties:
   - Implement caching layers
   - Build background jobs and task queues
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/architecture", "/setup", "/precommit"]
   evaluation: ["/reviewer", "/evaluate"]
 invokes:

roles/code-health/role.md

@@ -12,7 +12,7 @@ duties:
   - Track test suite quality (flaky tests, coverage gaps)
   - Manage safe migration patterns
 skills:
-  primary: ["/assess", "/debug"]
+  primary: ["/assess", "/debug_tool"]
   secondary: ["/reviewer", "/evaluate"]
 invokes:
   monitors: "ALL roles' code quality"

roles/data-engineer/role.md

@@ -13,7 +13,7 @@ duties:
   - Manage orchestration (Airflow, Dagster, Prefect)
   - Set up CDC and streaming pipelines
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/setup", "/architecture"]
 invokes:
   for_source_data: ["dba"]

roles/dba/role.md

@@ -14,7 +14,7 @@ duties:
   - Advise on data modeling (normalization vs denormalization)
   - Plan and review migrations
 skills:
-  primary: ["/debug", "/evaluate"]
+  primary: ["/debug_tool", "/evaluate"]
   secondary: ["/assess", "/explore"]
   evaluation: ["/reviewer"]
 invokes:

roles/embedded/role.md

@@ -13,7 +13,7 @@ duties:
   - Design communication protocols (MQTT, BLE, LoRa)
   - Implement OTA firmware update systems
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/setup", "/architecture"]
 invokes:
   for_firmware_signing: ["security"]

roles/frontend/role.md

@@ -13,7 +13,7 @@ duties:
   - Implement client-side routing, forms, error boundaries
   - Ensure accessibility (ARIA, keyboard nav, screen readers)
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/explore", "/precommit"]
   evaluation: ["/reviewer", "/evaluate"]
 invokes:

roles/game-dev/role.md

@@ -13,7 +13,7 @@ duties:
   - Implement multiplayer networking (if applicable)
   - Integrate art/animation/audio assets
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/setup", "/architecture"]
 invokes:
   for_multiplayer: ["backend"]

roles/infrastructure/role.md

@@ -14,7 +14,7 @@ duties:
   - Cost optimization and capacity planning
   - Disaster recovery and backup automation
 skills:
-  primary: ["/setup", "/debug"]
+  primary: ["/setup", "/debug_tool"]
   secondary: ["/architecture", "/assess"]
   evaluation: ["/evaluate", "/reviewer"]
 invokes:

roles/ios/role.md

@@ -11,7 +11,7 @@ duties:
   - Platform-specific UX (haptics, gestures, system integration)
   - App Store submission, TestFlight
 skills:
-  primary: ["/implementation", "/debug"]
+  primary: ["/implementation", "/debug_tool"]
   secondary: ["/setup", "/precommit"]
 invokes:
   for_api_contracts: ["backend"]