@taskless-app/swarm 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taskless-app/swarm",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Local control plane for a fleet of AI coding agents (drones), coordinating through Taskless. The overmind runs the swarm.",
   "keywords": [
@@ -29,10 +29,11 @@
   },
   "files": [
     "dist",
-    "docs/HERO.md"
+    "docs/HERO.md",
+    "roles"
   ],
   "dependencies": {
-    "@hono/node-server": "^2.0.10",
+    "@hono/node-server": "^2.0.12",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "execa": "^10.0.0",
     "zod": "3.25.76"
@@ -46,7 +47,7 @@
     "playwright-core": "1.49.1",
     "tsup": "^8.5.1",
     "tsx": "4.19.2",
-    "typescript": "5.7.3",
+    "typescript": "7.0.2",
     "vitest": "2.1.8",
     "@taskless/swarm-core": "0.1.0"
   },

package/roles/README.md

@@ -0,0 +1,31 @@
+# Ролевые каталоги скиллов — то, что едет С РОЕМ
+
+Каждый подкаталог — плагин Claude Code (`.claude-plugin/plugin.json` + `skills/`), который
+демон подкладывает дрону флагом `--plugin-dir` по роли прогона (`run.kind`). Резолв — в
+`src/launcher.ts`, `bundledRoleDir()`: относительно МОДУЛЯ, поэтому работает и из
+`src/` в монорепо, и из `dist/` в опубликованном npm-пакете. Каталог попадает в пакет через
+`files: ["dist", "docs/HERO.md", "roles"]`.
+
+Сегодня здесь только `drone/`. У `hero/` каталога нет — устав `docs/HERO.md` ни на какой
+скилл не ссылается; появится ролевой скилл для героя — завести той же формой.
+
+## Что сюда можно, а что нельзя (TASWM-315)
+
+Признак один: **верно ли это для ЛЮБОГО проекта.**
+
+- **Можно:** дисциплина работы дрона — незапушенное умирает с процессом; базовую ветку
+  вливать, а не ребейзить запушенную; ждать условие, а не `sleep`; что считать зелёным;
+  искать первопричину до фикса.
+- **Нельзя:** как поднять стек, какие порты, какими командами гонять тесты, правила
+  вёрстки, «у нас postgres на :5433». Это знания о проекте — им место в `.claude/skills/`
+  самого репозитория, и владелец проекта правит их без релиза роя.
+
+Причина запрета не вкусовая: после компактизации все скиллы делят **~25k токенов**, и
+каждый скилл здесь тратит их у КАЖДОГО дрона в КАЖДОМ проекте. Набор держим маленьким, и
+скилл обязан себя окупать. Тот же скилл не должен лежать одновременно здесь и в
+`.claude/skills/` репозитория — иначе он доставляется дважды (инвариант закреплён тестом
+`bundledRoleDir` в `src/launcher.test.ts`).
+
+Чужие скиллы — только через аудит (trigger phrases, нет сетевого egress, нет рискованных
+bundled-скриптов, совместимая лицензия): чек-лист и история в
+[`../../../.claude/skills/README.md`](../../../.claude/skills/README.md).

package/roles/drone/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "swarm-drone",
+  "description": "Ролевой набор скиллов дрона роя, который едет С РОЕМ, а не с репозиторием: дисциплина, верная для любого проекта (сохраняться часто, вливать базовую ветку не ребейзом, ждать условие вместо sleep, что считать зелёным) плюс vendored systematic-debugging (MIT, superpowers 6.0.3). Подкладывается дрону через --plugin-dir из пакета @taskless-app/swarm, поэтому доступен и в чужом репозитории, где ни одного нашего файла нет. Знания о конкретном проекте (как поднять стек, как гонять тесты, UI-правила) сюда НЕ кладём — им место в .claude/skills/ самого репозитория.",
+  "version": "1.0.0",
+  "author": {
+    "name": "taskless swarm"
+  },
+  "license": "MIT"
+}

package/roles/drone/skills/swarm-await-process/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: swarm-await-process
+description: >-
+  Use when you need to wait for something to become ready or finish — a server to
+  boot, a port to open, a migration/build/test run to complete, a health check to
+  pass — or when tempted to `sleep N`, or to run a long command in the background
+  "to wait for it". "жди процесс", "poll for readiness", "condition polling".
+  Read this so you wait on a CONDITION (not a fixed sleep) and don't lose work by
+  backgrounding long runs.
+license: see LICENSE of @taskless-app/swarm
+metadata:
+  area: swarm-role
+  audience: swarm-drone
+---
+
+# Wait on a condition, not on a sleep
+
+A fixed `sleep 10` is wrong in both directions: too short and it flakes, too long
+and it wastes the whole fleet's time. **Poll the actual condition** with a short
+interval and a hard cap.
+
+## The pattern
+
+```bash
+for i in $(seq 1 60); do
+  <check the condition> >/dev/null 2>&1 && { echo ready; break; }
+  [ "$i" = 60 ] && { echo "timed out" >&2; exit 1; }
+  sleep 1
+done
+```
+
+`<check the condition>` — то, что становится истинным, когда ожидаемое случилось:
+`curl -sf <health-url>`, `pg_isready`, `nc -z localhost <port>`, наличие файла-
+артефакта, `gh pr checks` в терминальном статусе. Хорошие dev-скрипты проекта уже
+делают так — подсмотри у них condition и таймаут, прежде чем изобретать свой.
+
+Poll intervals: ~0.5–1s for a local process/port, ~30s+ for a remote API (rate
+limits). Always give the loop a hard ceiling so a stuck process fails loud
+instead of hanging forever. `systematic-debugging` (vendored for drones as
+`swarm-drone:systematic-debugging`) ships a `condition-based-waiting` reference
+with the same principle for async code.
+
+## Headless drones: keep long work BLOCKING (don't background to wait)
+
+This is the one that kills drones. Your session ends the moment you stop calling
+tools — a process you launched with `&` / `run_in_background` **will not save you**
+once you go quiet, and its output dies with the session.
+
+- Run builds, test suites, and migrations as a **blocking foreground call** and
+  read the result. Don't fire-and-forget and "check later".
+- If a run is genuinely long, split the task into parts and
+  **commit + push between them** (see [[swarm-save-often]]) — that's your
+  checkpoint, not a background process.
+- Never `sleep` in the foreground just to pass time — either you have a condition
+  to poll, or you have nothing to wait for.
+
+## Why polling, not sleeping
+
+Sleeps encode a guess about timing; conditions encode the truth. Startup time
+varies with cold caches, machine load, and fork contention — a poll adapts, a
+sleep gambles.

package/roles/drone/skills/swarm-merge-main/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: swarm-merge-main
+description: >-
+  ТОЛЬКО ДЛЯ ДРОНА РОЯ с открытым PR: твоя ветка конфликтует с базовой веткой или
+  отстала от неё — "merge conflict", "PR out of date with main", "конфликт с main",
+  "влить main". Читать ДО любого git merge/rebase на уже запушенной ветке, чтобы не
+  переписать историю и не затереть чужую работу.
+license: see LICENSE of @taskless-app/swarm
+metadata:
+  area: swarm-role
+  audience: swarm-drone
+---
+
+# Integrate the base branch into yours (merge-in), don't rebase
+
+Parallel drones share the base branch. When another PR merges and your branch falls
+behind — or the host says your PR conflicts — **merge the base branch INTO your
+branch**. Never rebase or force-push a branch that has an open PR.
+
+Базовая ветка — та, в которую открыт (или будет открыт) твой PR: обычно ветка по
+умолчанию (`main`/`master`), но устав мог явно назвать другую. Ниже `<base>` —
+именно она; не подставляй `main` машинально.
+
+## The move
+
+```bash
+git fetch origin
+git merge origin/<base>      # from inside your worktree, on your PR branch
+```
+
+- **Clean merge** → `git push` (a normal fast-forwardable push). Done.
+- **Conflicts** → resolve them (below), then:
+  ```bash
+  git add -A
+  git commit --no-edit       # finish the merge commit, keep the default message
+  git push                   # normal push — NOT --force / --force-with-lease
+  ```
+
+## Resolving conflicts — keep both sides, don't touch the feature
+
+The job is to reconcile the merge, not to redesign anything. Most conflicts are
+mechanical:
+
+- **Duplicate import / declaration** → keep one copy.
+- **Two independent additions** in the same hunk → keep **both**.
+- Delete nothing beyond the conflict markers; add no new features; do no refactor.
+
+If a conflict is a real **logical / product ambiguity** — which of two values or
+behaviours is correct, not just how to stitch text — that's a decision, not
+mechanics. Don't guess: `ask(...)` the operator and wait. (For review-PRs the
+swarm may also spin up a dedicated resolver drone.)
+
+After resolving, re-run the project's checks and make sure they're green before
+pushing — рецепт и критерий зелёности у каждого проекта свой, ищи их в скиллах
+репозитория / README (см. [[swarm-verify-green]]). Красное после мержа значит, что
+твоё разрешение конфликта неверно — чини разрешение, а не фичу.
+
+## Never rewrite a shared PR branch
+
+`git rebase`, `git push --force`, `git push --force-with-lease` on a PR branch are
+**forbidden** and gated by the swarm — they discard the reviewer's context and
+can lose commits. The only integration path for an open PR is merge-in.
+
+## Prevention beats cure
+
+Merge `origin/<base>` into long-running branches **early and often**, especially
+right after another PR lands on files you also touch. A stale branch that sat for
+hours is where the ugly conflicts come from. See also [[swarm-save-often]].

package/roles/drone/skills/swarm-save-often/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: swarm-save-often
+description: >-
+  ТОЛЬКО ДЛЯ ДРОНА РОЯ, работающего в своём worktree на ветке-слаге: коммить и
+  пушить после каждого шага, чекпойнт перед долгим прогоном, слаг задачи и трейлер
+  дрона в каждом коммите. "незапушенное умирает с дроном", "checkpoint", "push
+  after every step". НЕ для оркестратора и не для обычной сессии — там пуш только
+  по просьбе владельца.
+license: see LICENSE of @taskless-app/swarm
+metadata:
+  area: swarm-role
+  audience: swarm-drone
+---
+
+# Commit and push after every step — unpushed work dies with the drone
+
+**Кому это адресовано.** Ты дрон роя: у тебя свой worktree, своя ветка по слагу
+задачи, и тебя могут убить в любой момент. Если ты не дрон, а главная сессия —
+этот скилл не про тебя: там действует обратное правило владельца, пушить только
+когда попросили.
+
+A drone can be killed at any moment (process kill, network drop, storm mode,
+respawn). Only what's **pushed to `origin`** survives. Local commits and
+uncommitted edits in the worktree are lost with the process — and a fresh respawn
+starts from the last pushed state, so anything not pushed is redone or gone.
+
+## The rhythm
+
+After each meaningful step (a file written, a fix made, a check greened):
+
+```bash
+git add <the files you changed>          # not `git add -A` blindly — see below
+git commit -m "<type>(<scope>): <what> (<SLUG>)
+
+Drone: <NAME> · run #<id>"
+git push -u origin <your-branch>          # branch == task slug
+```
+
+Don't save the whole task for one final commit. Checkpoint often. If you're about
+to start something long (a big build, an e2e run), commit + push **first** — the
+push is your checkpoint, not a background process (see [[swarm-await-process]]).
+
+## Two things every commit needs
+
+1. **The task slug** (`<SLUG>`, e.g. `PRJ-42`) in the message — the tracker links
+   tasks to releases by parsing slugs from commits. No slug → the task shows up in
+   no release, even if its status changed. **Сначала убедись, что слаг
+   существует** (`get_task <SLUG>`): однажды несколько коммитов сослались на номер,
+   которого в проекте не было — счётчик стоял ниже, — и деплой зарегистрировался с
+   `linkedTasks: 0`.
+2. **The drone trailer** — a `Drone: <NAME> · run #<id>` line, so runs are greppable.
+
+## Stage deliberately (parallel-agent hygiene)
+
+Prefer `git add <paths>` over `git add -A`. Multiple drones and tools can leave
+stray files in a worktree; `-A` sweeps them into your commit. Stage what you
+actually changed.
+
+## If you forgot the slug
+
+Don't rewrite history on a pushed branch (see [[swarm-merge-main]]). Add an empty
+marker commit instead:
+
+```bash
+git commit --allow-empty -m "chore: link (<SLUG>)
+
+Drone: <NAME> · run #<id>"
+```

package/roles/drone/skills/swarm-verify-green/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: swarm-verify-green
+description: >-
+  Use right before you claim a task is complete, open a PR, or call done — что
+  считать ЗЕЛЁНЫМ и каким доказательством это подтверждать, в любом проекте и на
+  любом стеке. "before done", "before PR", "is it finished", "готово?", "claim it
+  passes", "verification", "зелёное ли". Read this to know what counts as evidence;
+  КАКИЕ команды дают это зелёное в конкретном репозитории — в скиллах самого
+  репозитория.
+license: see LICENSE of @taskless-app/swarm
+metadata:
+  area: swarm-role
+  audience: swarm-drone
+---
+
+# Verify before you say done — evidence, not intent
+
+Claiming work is complete without running the check is not efficiency, it's a
+guess. Этот скилл — универсальная половина гейта: он говорит, ЧТО считается
+зелёным. Вторая половина живёт в репозитории проекта (его скиллы / README /
+CONTRIBUTING): КАКИМИ командами это зелёное получить.
+
+**Iron rule:** если ты не прогнал проверку в этой сессии, только что — ты не можешь
+утверждать, что она проходит. «Should pass» / «seems fine» / «выглядит правильно» —
+не доказательство.
+
+## Что считается зелёным
+
+1. **Проверка реально ИСПОЛНИЛАСЬ, а не отыгралась из кеша.** Сборочные системы с
+   кешем (turbo, nx, gradle, bazel, ccache, CI-кеши) отдают прошлый результат
+   мгновенно, если хеш входов не поменялся — и печатают это в выводе (`cache hit`,
+   `FULL TURBO`, `up-to-date`, `>>> replayed`). Зелёное из кеша не значит, что твой
+   код проверили: перепрогони принудительно (флаг вида `--force`/`--no-cache`) и
+   покажи строку, где видно реальный прогон.
+2. **Ноль упавших, а не «в основном зелёно».** Прочитай ИТОГ, не первые строки; не
+   экстраполируй с частичного прогона на весь сьют.
+3. **Проверка покрывает именно твоё изменение.** Зелёный сьют, который не касается
+   твоего кода, ничего о нём не говорит — найди (или прогони) то, что его касается.
+4. **Изменил видимое поведение — прогони его.** «Компилируется» это не «работает»:
+   пройди сценарий на живом приложении (встроенный скилл `/verify`, рецепт запуска —
+   в скиллах репозитория). Для UI — скрины mobile + desktop в задачу.
+5. **Доказательство приложено.** В сдаче — сам вывод (итоговая строка, exit 0,
+   наблюдаемое поведение), а не утверждение «проверил».
+
+Нечего прогнать (в проекте нет проверок вовсе) — это факт о проекте, а не
+разрешение молча сдать: скажи прямо, чем проверял вместо них. Инфраструктуру
+проекта под гейт роя НЕ достраивай.
+
+## Red flags — stop and go get evidence
+
+- «should», «probably», «seems to», «кажется, работает»
+- Радость от готовности РАНЬШЕ прогона («Отлично, починил!») — сначала прогон
+- Собираешься коммитить / пушить / открывать PR / звать `done()` без свежего прогона
+- Веришь отчёту сабагента «успешно» вместо диффа в VCS и своей проверки
+- Кеш-хит принял за прогон (см. пункт 1)
+- Тест красный, и рука тянется подправить тест — это охота за баг-первопричиной,
+  а не правка: `swarm-drone:systematic-debugging` (root cause до фикса)
+- Красное списал на «оно и до меня падало» — проверь это на базовой ветке, а не
+  предполагай
+
+## Почему это отдельный скилл
+
+Универсальный мантра-скилл «всегда проверяй» сам по себе даёт мало — работает
+пара: критерий доказательства (здесь) + конкретные команды проекта (в его
+репозитории). Поэтому эта половина едет С РОЕМ в любой проект, а вторая остаётся у
+владельца репозитория и переживает смену стека.

package/roles/drone/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Write the failing test first, then the fix (TDD)
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultra-think this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- Write the failing test case first, then the fix (Phase 4, Step 1) — TDD
+- **verify-before-done** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common