@kernel.chat/kbot 3.98.0 → 3.99.0

package/skills/software-development/systematic-debugging/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: systematic-debugging
+description: Use when any test fails, any bug surfaces, or any behavior is unexpected. Enforces root-cause analysis before code changes.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [debugging, root-cause, investigation, tdd]
+    related_skills: [test-driven-development, ship-pipeline, specialist-routing]
+---
+
+# Systematic Debugging
+
+Random fixes waste time and create new bugs. Before writing a single line of fix, you must understand *why* it broke.
+
+## Iron Law
+
+```
+NO FIX WITHOUT A NAMED ROOT CAUSE.
+```
+
+If you can't finish the sentence "It broke because ___", you are not ready to edit.
+
+## When to Use
+
+- Any failing test
+- Any exception in a log
+- Any "this used to work"
+- Any UI regression
+- Any flaky behavior
+- Any build failure
+
+Especially use this under time pressure — "quick fix" almost always means "new bug tomorrow."
+
+## Four Phases
+
+### Phase 1 — Reproduce
+
+- Run the failing case *exactly*. Don't paraphrase the command.
+- Capture the full error: message, stack, file, line.
+- If you can't reproduce, you don't understand the bug yet — stop and gather more evidence.
+
+Tools: `bash` to run the command, `kbot_read` to open the file at the stack trace line, `git_diff` to see what changed recently.
+
+### Phase 2 — Isolate
+
+- Binary-search the change set. Use `git log --oneline -20` and check the last commit that touched the area.
+- Trace the data flow upstream from the symptom. The bug almost never lives where the exception fires.
+- Find a *working* similar case in the same codebase. What's different?
+
+Tools: `grep` for the bad value, `git_log` for history, subagent with Explore to map the call graph.
+
+### Phase 3 — Hypothesize
+
+- Write down one sentence: "I think this is caused by X because Y."
+- Predict what the smallest possible reproduction looks like.
+- Predict what the smallest possible fix looks like.
+
+Do **not** write code yet. Share the hypothesis first if the user is watching.
+
+### Phase 4 — Fix
+
+1. Write a failing test that captures the bug (see `test-driven-development`).
+2. Make the minimal change that turns it green.
+3. Run the full suite. No regressions.
+4. Commit with a message that names the root cause, not the symptom.
+
+## The Rule of Three
+
+If your third fix attempt failed, **stop**. Don't try a fourth. The bug is not where you think it is, or the architecture is wrong. Escalate — use `kbot_plan` or hand off to a specialist agent.
+
+## Red Flags (stop and restart)
+
+- "Let me just try this and see"
+- "I'll comment this out for now"
+- Changing more than one thing per commit
+- Adding a try/except to make the error go away
+- "It works on my machine"
+
+## How kbot Helps
+
+- `kbot --thinking` shows reasoning — use it when debugging complex issues.
+- `kbot --agent coder` routes to the specialist with strongest code-patching track record.
+- `kbot --plan` forces read-only investigation mode for Phase 1 & 2.
+- `forge_tool` builds a throwaway diagnostic script when stdlib tools aren't enough.

package/skills/software-development/test-driven-development/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: test-driven-development
+description: Use when adding any new behavior or fixing any bug. Red → Green → Refactor, enforced.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [tdd, testing, quality, vitest]
+    related_skills: [systematic-debugging, ship-pipeline]
+---
+
+# Test-Driven Development
+
+## Iron Law
+
+```
+THE FIRST COMMIT ON ANY BEHAVIOR CHANGE IS A FAILING TEST.
+```
+
+No exceptions. Not "I'll add tests after." Not "this is too small." The failing test proves you understood the behavior before you wrote it.
+
+## Why
+
+- Writing the test first forces you to design the interface, not the implementation.
+- A failing test that turns green is the only honest proof the fix works.
+- Tests written after the fact confirm what you already did, not what you should have done.
+- Coverage that grows alongside code never has a "we should add tests" backlog.
+
+## The Cycle
+
+### RED
+
+1. Decide what the new behavior is, in one sentence.
+2. Write the smallest test that would fail if the behavior is missing.
+3. Run it. Confirm it fails for the *right reason* (not a typo, not a missing import).
+
+### GREEN
+
+1. Write the minimum code that makes the test pass.
+2. No extra features. No refactoring yet. No "while I'm here."
+3. Run the test. Confirm green.
+
+### REFACTOR
+
+1. Now — and only now — clean up the implementation.
+2. Rename, extract, deduplicate. Tests still green the whole time.
+3. If a refactor turns a test red, you changed behavior — revert and think.
+
+## kbot Toolchain
+
+- Framework: **Vitest** (`.test.ts` next to source).
+- Runner: `npx vitest run` (one-shot) or `npx vitest` (watch).
+- Typecheck gate: `npx tsc --noEmit` before every commit. Strict mode is non-negotiable.
+- UI tests: `@testing-library/react`.
+- E2E: Playwright (`npm run test:e2e`).
+
+## Mocking Policy
+
+- Mock Supabase. Never call the real API in tests.
+- Mock the Claude proxy. Never call the real API in tests.
+- Do NOT mock your own pure functions — test them directly.
+- Do NOT mock file I/O — use `tmpdir()` fixtures.
+
+## Anti-Patterns
+
+- Tests that assert implementation details (internal method calls) instead of observable behavior.
+- Tests that share state between cases. Each test starts clean.
+- Test names like `it('works')`. Name the behavior: `it('rejects unauthenticated requests')`.
+- "Fix the test" when the test correctly catches a regression. Fix the code.
+
+## When kbot Should Run Tests Autonomously
+
+After any edit under `src/` or `packages/kbot/src/`, kbot runs `npm run typecheck` and `npx vitest run <affected>` before reporting success. No UI claim without a browser check (see `ship-pipeline`).