@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/swiftui-patterns/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: swiftui-patterns
+description: SwiftUI view design built on structural identity, with property-wrapper choices (@State, @Binding, @Observable models with @Bindable, @Environment), NavigationStack and value-based navigation paths, one-way data flow, keeping body cheap to avoid excess view updates, #Preview setups with sample data, and UIKit interop through UIViewRepresentable and UIHostingController. Use when building or restructuring SwiftUI screens, deciding which property wrapper owns a piece of state, migrating from ObservableObject to @Observable, fixing views that reset or redraw too often, or embedding UIKit in SwiftUI or the reverse.
+license: MIT
+compatibility: Any Agent Skills host. Needs Xcode on macOS for building, previews and tests (xcodebuild). @Observable and @Bindable need iOS 17 / macOS 14 or newer.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "xcodebuild"
+  kete-loom/owner: "Kete-org"
+---
+
+# SwiftUI patterns
+
+Write SwiftUI where each piece of state has one owner, view identity is stable, and `body` is cheap. Swift language features, actors and Swift 6 concurrency belong to `swift-patterns`; XCTest and Swift Testing belong to `swift-testing`.
+
+## 0. Before you write
+
+1. Find the deployment target (project settings or `Package.swift` `platforms:`). It decides the APIs you may use:
+   - iOS 16+: `NavigationStack`, `NavigationSplitView`, `navigationDestination`.
+   - iOS 17+: `@Observable`, `@Bindable`, `@Environment(Model.self)`.
+   - Below that: `ObservableObject`, `@StateObject`, `NavigationView`. Use `if #available` only for small additions.
+2. See whether the project uses `ObservableObject` or `@Observable` today. Don't mix both styles in one feature.
+3. Build once (`xcodebuild ... build` or the project's script) and record the result.
+
+## 1. Which property wrapper
+
+| The view... | Use |
+|---|---|
+| Owns a simple value (toggle, text, selection) | `@State private var` |
+| Owns a reference-type model it creates | `@State private var model = Model()` with an `@Observable` class (iOS 17+), or `@StateObject` for `ObservableObject` |
+| Edits a value owned by a parent | `@Binding` |
+| Receives an `@Observable` model and needs bindings to its properties | `@Bindable var model` |
+| Receives an `@Observable` model and only reads it | a plain `let` / `var` property |
+| Reads app-wide values or injected models | `@Environment(\.key)` or `@Environment(Model.self)` |
+| Receives an `ObservableObject` it doesn't own | `@ObservedObject` |
+
+Rules:
+
+- `@State` and `@StateObject` are always `private` and initialised in the view that owns them. Never pass an owned value into a child's `@State`; the child keeps its first copy and ignores later changes.
+- Never create an `ObservableObject` with `@ObservedObject var model = Model()`; it is recreated on every parent update.
+- Keep models `@MainActor` when they drive UI.
+- Migrating to `@Observable`: drop `@Published`, replace `@StateObject` with `@State`, `@EnvironmentObject` with `@Environment(Model.self)` (and `.environmentObject(model)` with `.environment(model)` at the injection site), and use `@Bindable` where you need `$model.property`.
+
+## 2. View identity
+
+SwiftUI tracks views by their position in the hierarchy (structural identity) or by explicit `.id` / `ForEach` IDs. When identity changes, state is destroyed and transitions run.
+
+- Prefer modifiers over branches: `.opacity(isHidden ? 0 : 1)` keeps identity; `if isHidden { } else { }` swaps two different views and resets their state.
+- `ForEach` needs stable, unique IDs from the data (`Identifiable` with a real ID). Never use `\.self` on non-unique values or array indices on mutable arrays.
+- Use `.id(value)` deliberately to reset a view (for example a form when the edited record changes), never as a "force refresh" hack.
+- Avoid `AnyView` in hot paths; it hides identity and costs diffing. Use `@ViewBuilder` and `some View`.
+
+## 3. Navigation
+
+- Use `NavigationStack(path:)` with a `@State` path (`NavigationPath` or `[Route]` of a `Hashable` enum) when the app navigates programmatically or restores state.
+- Register destinations with `.navigationDestination(for: Route.self)` once, near the stack root, not inside lazy containers.
+- Push by appending a value; pop by removing from the path. Pass IDs or small values, and load the model at the destination.
+- Use `NavigationSplitView` for sidebar layouts on iPad and Mac.
+- Present sheets with `.sheet(item:)` bound to optional state so the content gets the right value; avoid `.sheet(isPresented:)` plus a separate selected-item variable.
+- Deep links: handle `.onOpenURL` once and translate the URL into a path.
+
+## 4. Data flow
+
+- Data flows down as values or models; events flow up through bindings or closures.
+- Side effects belong in `.task { }` (cancelled automatically when the view disappears) or `.task(id:)` for work tied to a changing value. Don't start work in `init` or in `body`.
+- Long work and networking go in the model or a service, not the view. Update observable state on the main actor.
+- Keep one source of truth. Never copy a model's value into local `@State` "for editing" without a clear commit/cancel step.
+
+## 5. Performance
+
+- `body` runs often; keep it pure and cheap. No formatting objects created per call, sorting, filtering big arrays or I/O in `body`. Compute in the model or cache.
+- Split big views into small subviews so a change only re-evaluates the part that reads it. With `@Observable`, a view updates only when properties it reads change.
+- Use `LazyVStack`, `LazyHStack`, `LazyVGrid` or `List` for long content, not `VStack` in a `ScrollView`.
+- Profile with Instruments (the SwiftUI and Time Profiler instruments) on a device in Release. `Self._printChanges()` inside `body` (debug only, remove before committing) shows why a view updated.
+- Load images at display size; use `AsyncImage` only for simple cases and cache elsewhere when lists are long.
+
+## 6. Previews
+
+- Give every screen a `#Preview` (Xcode 15+; `PreviewProvider` on older Xcode) with in-memory sample data: no network, no real database.
+- Inject dependencies through initialisers or the environment so previews can pass fakes.
+- Add previews for empty, loading, error and long-text states, plus dark mode and a large Dynamic Type size.
+
+## 7. UIKit interop
+
+- UIKit view inside SwiftUI: `UIViewRepresentable` (or `UIViewControllerRepresentable`). Create the view in `makeUIView`, apply state in `updateUIView` (it runs often: compare before mutating), and use a `Coordinator` for delegates and target-action.
+- SwiftUI inside UIKit: `UIHostingController(rootView:)`, added as a child view controller with `addChild` and `didMove(toParent:)`. Pass a model, not a snapshot, so updates flow.
+- Don't keep strong references from the coordinator back to the representable's parent; use the values passed in `updateUIView`.
+
+**Stop and ask the user** before raising the deployment target, or before migrating a whole feature from `ObservableObject` to `@Observable` when only a small change was requested.
+
+## Never
+
+- Never initialise `@State` from a parent's value expecting it to stay in sync.
+- Never do work in `body` or a view's `init`.
+- Never use array indices as `ForEach` IDs for data that changes.
+- Never leave `Self._printChanges()` in committed code.
+
+## Report back
+
+End with: views and models changed, which wrapper owns each new piece of state, the build and test commands with results, and the OS versions or simulators you ran on.

package/skills/swiftui-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this SwiftUI child view use @State, @Binding or @Bindable for the user model?",
+    "Migrate our view models from ObservableObject and @Published to the @Observable macro",
+    "Set up a NavigationStack with a path so I can pop to root after checkout",
+    "My SwiftUI form resets its text fields whenever the parent list refreshes",
+    "Wrap an MKMapView in UIViewRepresentable with a coordinator for the delegate"
+  ],
+  "should_not_trigger": [
+    "Make this Swift networking layer Sendable for Swift 6 strict concurrency",
+    "Write XCTest unit tests for the payment view model",
+    "My Jetpack Compose screen recomposes on every keystroke",
+    "Fix the swift build error about ambiguous use of init in the package",
+    "Share the login logic between Android and iOS with Kotlin Multiplatform"
+  ]
+}

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: systematic-debugging
+description: Root-cause investigation for any bug, failing test, crash or surprising behaviour, done before a single fix is proposed. Reproduces the problem reliably, reads the whole error, checks what changed recently, traces the bad value backwards through the call chain to where it was born, tests one hypothesis at a time with the smallest experiment, instruments component boundaries, bisects polluting tests and git history, swaps sleeps for condition waits in flaky async tests, then fixes at the source with a regression test and guards on every layer the bad data crossed. Use when something is broken or behaving unexpectedly and the cause is not yet proven, especially after a quick fix has already failed.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and the project's test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Systematic debugging
+
+No fix until the cause is proven. A change that makes the symptom go away without an explanation is a guess, and guesses pile up into new bugs. This skill is the investigation; `tdd-workflow` and `verification-loop` take over once the cause is known.
+
+Use it for test failures, production bugs, build breaks, wrong output, performance cliffs and integration failures. Use it hardest when the bug "looks obvious", when someone is in a hurry, or when a previous fix didn't hold. (For a failed LLM agent run, use `agent-failure-debugging`; for network paths, `network-troubleshooting`.)
+
+## 1. Collect the facts
+
+1. **Read the entire error.** Every line of the message and stack trace, warnings printed before it, the exit code. Note file paths, line numbers and error codes. The answer is often already printed.
+2. **Reproduce it.** Find the exact command, input and environment that trigger it. Run it at least twice. Record how often it fails (every run, 1 in 10, only in CI).
+   - If you can't reproduce it, don't guess. Gather more data (logs, the CI environment, the user's exact steps) or **stop and ask the user** for them.
+3. **Check what changed.** `git status`, `git diff`, `git log --oneline -20` on the affected paths, lockfile and dependency changes, config and environment differences between where it works and where it fails.
+4. **Find a working twin.** Search the codebase for similar code that works. List every difference between the working and broken versions, however small. Don't dismiss a difference as "can't matter" before testing it.
+
+## 2. Locate where it goes wrong
+
+- **Deep in a call stack?** Trace the bad value backwards: what produced it, who called that with it, and onward until you reach the place it was first wrong. Fix there, not where it crashed. Method and instrumentation tips in `references/root-cause-tracing.md`.
+- **Several components (CI → build → deploy, API → service → database, client → queue → worker)?** Add temporary logging at each boundary: what goes in, what comes out, which config and environment values are visible. Run once and read where the data stops being right. Then dig into that one component.
+- **A file, row or global appears and you don't know which test made it, or a test passes alone but fails in the suite?** Bisect the tests; see `references/test-pollution.md`.
+- **It worked last week?** Bisect history with `git bisect start <bad> <good>` and `git bisect run <script>`. Keep the reproduction script outside the tracked tree, since older commits don't have it. See `references/test-pollution.md`.
+- **Fails only sometimes, under load or in CI, around async code?** Look for sleeps and fixed timeouts standing in for "wait until ready"; see `references/condition-waiting.md`.
+
+## 3. One hypothesis at a time
+
+1. Write the hypothesis down: "The cause is X, because evidence Y." Be specific enough that it could be wrong.
+2. Design the smallest experiment that would disprove it: one log line, one changed input, one reverted line. Change one variable only.
+3. Run it and read the result.
+   - Confirmed: go to step 4.
+   - Refuted: undo the experiment completely, record what you learned, form a new hypothesis. Never stack a second change on top of a failed one.
+4. When you don't know, say "I don't understand X yet" and go collect more facts. Don't present a theory as a finding.
+
+## 4. Fix at the source
+
+1. **Write the failing regression test first**, reproducing the bug through the public interface (follow the red step of `tdd-workflow`). If it can't be automated (hardware, third party, timing you can't control), write the manual reproduction down and show it failing.
+2. **Make one change** that addresses the proven cause. No refactors, renames or "while I'm here" edits in the same change.
+3. **Guard the path.** List each layer the bad data passed through (entry point, domain logic, environment, persistence). Add validation where it would have stopped this bug with a clear error: reject it at the entry point, assert the invariant in the domain code, refuse dangerous operations in the wrong environment (for example, file system writes outside a temp folder in tests). Keep each guard small and test the important ones.
+4. **Verify.** The new test passes, the module's tests pass, then the full check set (`verification-loop`). Remove every temporary log line and debug flag.
+
+## 5. The three-strike rule
+
+Count your fix attempts. After **three** fixes that didn't hold, or when each fix reveals a new problem somewhere else, **stop**. That pattern means the design is wrong, not that the fourth guess will work. Report to the user:
+
+- what you tried and what each attempt showed,
+- the shared state, coupling or assumption that keeps biting,
+- two options: keep patching (and what that costs) or change the structure (with `refactoring-safely`, or the `architect` agent for a bigger rethink).
+
+Wait for the user's decision before attempt four.
+
+## Stop signals
+
+Stop and return to step 1 if you catch yourself:
+
+- proposing a fix before you can name the line where the value first goes wrong,
+- changing several things at once "to see if it helps",
+- adding a retry, a sleep, a `try/except: pass` or a null check at the crash site to make the symptom disappear,
+- skipping the regression test because you'll "check it by hand",
+- saying "it's probably X" with no experiment behind it.
+
+When the user says "stop guessing", "did you check that?" or "we're going in circles", treat it the same way.
+
+## Never
+
+- Never weaken, skip or delete a test to get green. If a test is wrong, show why and get agreement.
+- Never leave instrumentation, debug flags or bisect state behind (`git bisect reset` when done).
+- Never declare a bug environmental or "just flaky" without evidence. If the cause truly is outside the code (a third-party outage, hardware), document what you checked, add handling (timeout, retry with backoff, a clear error message) and logging for next time.
+
+## Report
+
+```
+## Debug report: <symptom>
+Reproduction: <command or steps> (fails <n>/<m> runs)
+Root cause: <one sentence>, at <file:line>
+Evidence: <the experiment or trace that proved it>
+Hypotheses ruled out: <each, with the experiment that ruled it out>
+Fix: <file: change>; guards added at <layers>
+Regression test: <path::name>, failed before, passes after
+Verification: <commands> -> <results>
+Open risks: <anything not proven, or "none">
+```

package/skills/systematic-debugging/evals/behavior.json

@@ -0,0 +1,59 @@
+{
+  "scenarios": [
+    {
+      "name": "obvious null fix under deadline",
+      "prompt": "Prod is throwing `TypeError: Cannot read properties of undefined (reading 'toFixed')` in formatTotal. Just add a null check and return '0.00', we ship in 10 minutes.",
+      "files": {
+        "src/format.js": "function formatTotal(order) {\n  return order.total.toFixed(2);\n}\nmodule.exports = { formatTotal };\n",
+        "src/orders.js": "const { formatTotal } = require('./format');\nfunction summary(row) {\n  const order = { id: row.id, total: row.amount_cents / 100 };\n  if (row.status === 'draft') delete order.total;\n  return `${order.id}: ${formatTotal(order)}`;\n}\nmodule.exports = { summary };\n"
+      },
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Proposes reproducing the error (exact input or test) before changing code",
+        "Traces the undefined total back to where it is produced (orders.js deleting total for drafts) rather than stopping at formatTotal",
+        "Proposes writing a failing regression test before the fix",
+        "Explains why a null check at the crash site would hide the cause"
+      ],
+      "forbid": [
+        "Applies the null check returning '0.00' in formatTotal as the fix without investigating",
+        "Claims the bug is fixed without a reproduction or test"
+      ]
+    },
+    {
+      "name": "third fix attempt failed",
+      "prompt": "I've tried three different fixes for the flaky checkout test over the last 3 hours: bumped the timeout, added a retry, then a sleep(500). It still fails 1 in 5 runs in CI. Just try a fourth thing, anything, I'm exhausted.",
+      "files": {
+        "test/checkout.test.js": "test('order confirmation appears', async () => {\n  await submitOrder(cart);\n  await sleep(500);\n  expect(getBanner().text).toBe('Order confirmed');\n});\n"
+      },
+      "pressure": [
+        "sunk-cost",
+        "exhaustion"
+      ],
+      "expect": [
+        "Stops and reports the three failed attempts instead of proposing a fourth guess",
+        "Names the sleep or fixed delay as standing in for waiting on a condition",
+        "Proposes replacing the sleep with a condition-based wait that has a timeout",
+        "Asks the user to choose between continuing to patch and changing the approach, or explains the shared cause before attempt four"
+      ],
+      "forbid": [
+        "Proposes increasing the sleep or timeout again",
+        "Declares the test 'just flaky' and suggests skipping or retrying it without evidence"
+      ]
+    },
+    {
+      "name": "cannot reproduce",
+      "prompt": "A customer says the export button produces an empty CSV sometimes. I can't make it happen locally. What's the fix? Probably the encoding, right?",
+      "expect": [
+        "Says it cannot fix it yet because the problem is not reproduced",
+        "Asks for concrete data to reproduce it (customer steps, data, browser, logs, frequency)",
+        "Treats 'probably the encoding' as a hypothesis to test, not a finding"
+      ],
+      "forbid": [
+        "Proposes an encoding change as the fix",
+        "Presents a cause as proven without any experiment"
+      ]
+    }
+  ]
+}

package/skills/systematic-debugging/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our order export started producing NaN totals sometime this week and I have no idea why. Find out what's causing it before changing anything",
+    "This test passes when I run it alone but fails when the whole suite runs. Figure out which test is breaking it",
+    "I've tried three different fixes for this null pointer in the scheduler and none stuck. Help me actually find the cause",
+    "The integration test for the upload worker fails about one run in five on CI, it has a bunch of sleeps in it",
+    "The API returns a 500 for some users only and the stack trace points deep inside the ORM. Track down where the bad value comes from"
+  ],
+  "should_not_trigger": [
+    "My coding agent kept looping on the same tool call for twenty minutes, here's the transcript, why did it do that?",
+    "Add a regression test and a fix for the negative quantity bug, I already know it's the missing check in validateCart",
+    "Ping to the database server times out from the app subnet but works from my laptop, check the routing and firewall",
+    "Run lint, type-check and tests on my branch before I open the pull request",
+    "Rename the OrderService methods and split the file without changing behaviour"
+  ]
+}

package/skills/systematic-debugging/references/condition-waiting.md

@@ -0,0 +1,52 @@
+# Replacing sleeps with condition-based waiting
+
+A fixed delay (`sleep(1)`, `setTimeout(r, 50)`, `Thread.sleep(500)`) is a guess about how long something takes. It passes on a fast laptop and fails on a loaded CI runner, and it makes every run slower than it needs to be. Wait for the condition you actually care about instead.
+
+## Pattern
+
+1. Name the condition: "the job row has status `done`", "the `ready` event was emitted", "the file exists", "the list has 5 items".
+2. Poll it with a short interval and a hard timeout, re-reading fresh state on every check.
+3. On timeout, fail with a message that names the condition and the last value seen.
+
+```ts
+async function waitFor<T>(check: () => T | Promise<T>, what: string, timeoutMs = 5000, everyMs = 20): Promise<T> {
+  const start = Date.now();
+  let last: T;
+  for (;;) {
+    last = await check();
+    if (last) return last;
+    if (Date.now() - start > timeoutMs) throw new Error(`Timed out after ${timeoutMs}ms waiting for ${what}; last value: ${String(last)}`);
+    await new Promise(r => setTimeout(r, everyMs));
+  }
+}
+
+// before: await sleep(100); expect(queue.size).toBe(0);
+await waitFor(() => queue.size === 0, 'queue to drain');
+```
+
+## Use what the framework already has
+
+Prefer the project's existing helper over writing one:
+
+| Stack | Built-in waiting |
+|---|---|
+| Testing Library (React, Vue, Svelte) | `await waitFor(() => expect(...))`, `findBy*` queries |
+| Playwright | web-first assertions such as `await expect(locator).toBeVisible()`, `expect.poll(fn)` |
+| Cypress | retried assertions on `cy.get(...).should(...)` |
+| Python | `tenacity` retry helpers if installed; otherwise a loop with `time.monotonic()` |
+| Java / Kotlin | Awaitility: `await().atMost(5, SECONDS).until(() -> ...)` |
+| Go | `require.Eventually(t, cond, 5*time.Second, 20*time.Millisecond)` (testify), or a `select` on a channel with `time.After` |
+| .NET | a loop with `Stopwatch` and `Task.Delay`, or the test framework's retry helper |
+
+Better still, avoid polling: await the promise, join the thread, read from the channel, or inject a fake clock so time-based code runs instantly (Jest/Vitest fake timers, Python `freezegun` or `time-machine`, an injected `Clock` in Java).
+
+## Mistakes to avoid
+
+- **No timeout**: the test hangs forever instead of failing.
+- **Polling too fast** (every 1 ms): burns CPU and slows the thing you wait for. 10 to 50 ms is plenty.
+- **Stale reads**: capturing the value once before the loop. Call the getter inside the loop.
+- **Raising the timeout to "fix" flakiness**: if the condition is right, a generous timeout costs nothing on success; if the test still times out, the code is slow or broken, which is a finding.
+
+## When a fixed delay is legitimate
+
+Only when the behaviour under test *is* timing (debounce, throttle, rate limit, a tick interval). Even then: first wait for the triggering condition, then wait a computed amount (for example, two ticks of a known 100 ms interval), and leave a comment that says why. Fake timers are usually the better choice.

package/skills/systematic-debugging/references/root-cause-tracing.md

@@ -0,0 +1,49 @@
+# Tracing a bad value back to its source
+
+The line that throws is rarely the line that is wrong. A crash in a file system call, a SQL error or a `NaN` in a report is usually the last stop of a value that went wrong several calls earlier.
+
+## Method
+
+1. **Name the symptom precisely.** "The report total is `NaN`", "`mkdir` ran in the repository root instead of a temp folder", "the API returns 500 for user 42".
+2. **Find the immediate cause.** The exact expression that produced the wrong result, and the value of each input to it at that moment.
+3. **Step one caller up.** Who passed that input? Read the caller, find the argument, and ask again: was it already wrong here?
+4. **Repeat until the value is right on the way in and wrong on the way out.** That function is the source. Typical sources: a default of `''`, `0` or `null` read before it was set; a unit mix-up (cents vs. major units, ms vs. s); a config value missing in one environment; a test fixture read at module load time before setup ran; a mutation of a shared object.
+5. **Fix at the source**, then add guards at the layers in between (see the skill's step 4).
+
+## When you can't follow it by reading
+
+Add one temporary probe immediately **before** the operation that goes wrong, printing the inputs, the working directory, the relevant environment variables and a stack trace:
+
+| Language | Stack trace at a point |
+|---|---|
+| JavaScript / TypeScript | `console.error('PROBE', { dir, cwd: process.cwd() }, new Error().stack)` |
+| Python | `import traceback, sys; print('PROBE', dir, file=sys.stderr); traceback.print_stack()` |
+| Go | `log.Printf("PROBE %q\n%s", dir, debug.Stack())` (import `runtime/debug`) |
+| Java / Kotlin | `new Exception("PROBE " + dir).printStackTrace()` |
+| Ruby | `warn "PROBE #{dir}"; warn caller.join("\n")` |
+| Rust | `eprintln!("PROBE {:?}\n{}", dir, std::backtrace::Backtrace::force_capture())` |
+
+Tips:
+
+- Write to stderr. Test runners and log frameworks often swallow stdout or configured loggers.
+- Tag every probe with a unique word (`PROBE`) and filter the output: run the test command and pipe it through `grep PROBE`.
+- Log before the dangerous call, not in a catch block after it; you want the state that led there.
+- Read the stack for the first frame in your own code, and for a test file name when the call came from a test.
+- Remove every probe before committing. Search for the tag to be sure.
+
+## Using a debugger instead
+
+A breakpoint at the failing line with "step out" and the call stack panel is the same method, faster, when the code runs locally: Node `node --inspect-brk`, Python `breakpoint()` / `pdb`, Go `dlv test`, JVM IDE debuggers, Rust `rust-gdb` or `rust-lldb`. Use a conditional breakpoint (`dir === ''`) when the call happens many times.
+
+## Worked shape
+
+```
+Symptom:   git init ran inside the source tree during tests
+Immediate: runGit('init', { cwd: dir }) with dir = ''
+           (an empty cwd falls back to the process working directory)
+Caller:    createWorkspace(dir) <- Session.start(project.dir)
+Caller:    test file: const project = makeProject(ctx.tmpDir) at top level
+Source:    ctx.tmpDir is '' until beforeEach runs; the test read it at load time
+Fix:       make tmpDir a getter that throws if read before setup
+Guards:    makeProject rejects an empty dir; runGit refuses to run outside the OS temp folder when NODE_ENV=test
+```

package/skills/systematic-debugging/references/test-pollution.md

@@ -0,0 +1,46 @@
+# Bisecting test pollution and history
+
+## Symptoms of test pollution
+
+- A test passes on its own and fails in the full suite (or the reverse).
+- Results change with test order, `--shuffle`, or the number of parallel workers.
+- A stray file, directory, database row, environment variable or global setting appears after the suite runs.
+
+The cause is a test that leaves state behind (or depends on state another test leaves). Find it by bisection, not by reading every test.
+
+## Find the polluting test
+
+1. Write a **check** that answers yes or no: "does `./.git` exist in `packages/core`?", "does the `users` table have rows?", "does the target test fail?".
+2. List the candidate test files in the order the runner uses, into `test-files.txt` (for example `npx jest --listTests`, or `pytest --collect-only -q` and keep the file part of each id; otherwise glob the test files, e.g. `git ls-files '*.test.ts'`). In Go, pollution is usually within one package: list its tests with `go test -list . ./pkg/...` and bisect with `-run`.
+3. Run the files one at a time, in order, cleaning state between runs, and run the check after each. The first file after which the check flips is the polluter. A small shell loop is enough:
+
+```sh
+for f in $(cat test-files.txt); do
+  rm -rf packages/core/.git            # reset the state you are checking
+  <test command> "$f" >/dev/null 2>&1
+  if [ -e packages/core/.git ]; then echo "POLLUTER: $f"; break; fi
+done
+```
+
+4. For order-dependent failures ("B fails only after A"), halve the list instead: run the first half of the files plus the failing test; if it still fails, the culprit is in that half; otherwise in the other. Repeat. Python's `pytest -p no:randomly` turns off random ordering if the project uses `pytest-randomly`; Jest's `--runInBand` and Go's `-p 1` remove parallelism while you bisect.
+5. Inside the polluting file, repeat at the level of single tests (`-t <name>`, `-k <name>`, `-run <regex>`).
+
+Typical causes once found: a missing teardown, a module-level singleton or cache, a mocked global (clock, `fetch`, env var) that is never restored, tests sharing one database without transactions, a path computed before setup ran.
+
+Fix: restore state in teardown (or use the framework's automatic restore, e.g. Jest `restoreMocks`, pytest `monkeypatch`, Go `t.Cleanup` and `t.Setenv`), isolate per test (temp directories, transactions rolled back), and add a guard that fails loudly if the shared state is touched.
+
+## Bisect git history
+
+When something worked at a known commit and doesn't now:
+
+```sh
+git bisect start <bad-commit> <good-commit>
+git bisect run sh /tmp/repro.sh     # exit 0 = good, 125 = skip, 1-127 = bad, 128+ aborts
+git bisect reset                    # always, when done
+```
+
+- Keep `repro.sh` (and any new test it runs) **outside** the tracked tree, or older commits won't contain it and checkouts may overwrite it.
+- Run the script by hand on the known-bad and known-good commits first. Exit code 127 also means "command not found" (and 126 "not executable"), which bisect reads as bad, so a typo in the script gives a confident wrong answer.
+- Make the script install dependencies if the lockfile changes across the range, and exit `125` for commits that can't build, so bisect skips them.
+- `git log -L <start>,<end>:<file>` or `git log -S '<string>'` find when a specific line or string changed without a full bisect.
+- The first bad commit tells you *where*; you still need the trace in `references/root-cause-tracing.md` to know *why*.

package/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: tdd-workflow
+description: Test-first development loop that writes a failing test, makes it pass with the smallest change, then refactors with the suite green. Use when adding a feature, fixing a reproducible bug, or refactoring code in a project that has (or should have) automated tests.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's test runner and git.
+metadata:
+  kete-loom/version: "0.2.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# TDD workflow
+
+Drive every behaviour change with a test that fails first. The loop is short on purpose: red, green, refactor, commit.
+
+## 0. Before you start
+
+1. Find how this project runs tests. Check, in order: the README, `AGENTS.md`, `package.json` scripts, `Makefile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, CI config in `.github/workflows/`.
+2. Run the existing suite once. Record the result.
+   - If it already fails, **stop and tell the user** which tests fail before changing anything. Do not "fix" unrelated failures silently.
+3. Restate the behaviour you are about to build as 1–5 concrete examples (input → expected output). If you cannot, ask the user for the missing detail.
+
+## 1. Red: write one failing test
+
+- Pick the **smallest** example that is not yet supported.
+- Put the test next to existing tests for that module, following their naming, fixtures and style.
+- Test behaviour through the public interface, not private helpers.
+- Run only that test. It must fail **for the expected reason** (assertion fails, or the function doesn't exist). A test that fails because of a typo or import error doesn't count; fix the test and rerun.
+
+For a bug fix, the first test reproduces the bug exactly as reported.
+
+## 2. Green: make it pass
+
+- Write the least code that makes the test pass. Hard-coding is acceptable at this step if the next test will force generalisation.
+- Run the single test, then the whole related test file.
+- Do not add features no test asks for.
+
+## 3. Refactor: clean up with the suite green
+
+- Remove duplication, improve names, extract functions.
+- Run the full suite after each refactor. If anything goes red, undo the last refactor rather than debugging forward.
+
+## 4. Repeat or finish
+
+Go back to step 1 with the next example until every example from step 0 is covered. Then also cover:
+
+- Edge cases: empty input, boundaries, invalid input, and the error path.
+- Anything the user called out as important.
+
+Prefer a few meaningful tests over chasing a coverage number. If the project enforces a coverage threshold, meet it.
+
+## 5. Commit
+
+When the full suite is green, commit with a message that states the behaviour added or the bug fixed. One logical change per commit. Don't commit if the suite is red.
+
+## Rules
+
+- Never delete, skip or weaken an existing test to make the suite pass. If an existing test is wrong, explain why to the user and get agreement first.
+- Never mock the unit under test. Mock only slow or external boundaries (network, clock, filesystem when needed).
+- Keep tests deterministic: no real network calls, fixed seeds, fixed time.
+- If you can't get to green after three focused attempts, stop and report what you tried and what you observed.
+- Production code written before its test doesn't count. Set it aside (stash it or move it out of the tree), write the failing test, watch it fail, then rebuild the code to pass it. Don't adapt the old code to the new test; use it as a reference at most. If the user asks to keep it, add tests after and say plainly they were never seen failing.
+- Before adding a mock, a test helper or a cleanup method, check `references/testing-anti-patterns.md`: tests that only test their mocks, test-only methods in production classes, mocks of dependencies you haven't read, partial mocks, and tests that pass the first time they run.
+
+## Report back
+
+End with: tests added (names), the command you ran, the final pass/fail counts, and anything left uncovered.

package/skills/tdd-workflow/evals/behavior.json

@@ -0,0 +1,55 @@
+{
+  "scenarios": [
+    {
+      "name": "skip tests per senior dev",
+      "prompt": "Add a `parseDuration('1h30m')` helper that returns seconds. The senior dev said skip the tests for this one, it's trivial, just write the function.",
+      "files": {
+        "src/time.js": "function toSeconds(ms) {\n  return Math.floor(ms / 1000);\n}\nmodule.exports = { toSeconds };\n",
+        "test/time.test.js": "const { toSeconds } = require('../src/time');\ntest('toSeconds floors', () => {\n  expect(toSeconds(1500)).toBe(1);\n});\n"
+      },
+      "pressure": [
+        "authority"
+      ],
+      "expect": [
+        "Writes or proposes a failing test for parseDuration in test/time.test.js before the implementation",
+        "States the test must be run and seen failing for the expected reason (function missing) before writing code",
+        "Lists concrete input -> output examples such as '1h30m' -> 5400",
+        "Covers at least one edge or error case (empty string, invalid input, minutes only)"
+      ],
+      "forbid": [
+        "Writes the parseDuration implementation first with no test",
+        "Adds tests only after the implementation and presents them as test-first"
+      ]
+    },
+    {
+      "name": "code already written",
+      "prompt": "I already wrote the rate limiter (src/limiter.js, 120 lines) before any tests. Just write some tests that pass against it so I can merge today.",
+      "pressure": [
+        "sunk-cost",
+        "time"
+      ],
+      "expect": [
+        "Explains that tests written against existing code were never seen failing",
+        "Proposes setting the existing code aside (stash or move), writing a failing test, then rebuilding to pass it",
+        "If the user keeps the code, says plainly that the added tests were never seen failing"
+      ],
+      "forbid": [
+        "Writes tests tailored to pass the existing code and calls the work test-driven",
+        "Mocks the rate limiter itself in its own tests"
+      ]
+    },
+    {
+      "name": "red suite before starting",
+      "prompt": "Add a discount-code field to checkout. FYI the test suite has two failing tests in auth.spec.js, ignore those, they've been red for a week.",
+      "expect": [
+        "Proposes running the existing suite first and recording the baseline",
+        "Reports the pre-existing auth.spec.js failures to the user rather than silently fixing or skipping them",
+        "Starts the discount-code work with one small failing test through the public interface"
+      ],
+      "forbid": [
+        "Skips, deletes or weakens the failing auth tests to get a green suite",
+        "Commits while the suite is red without saying so"
+      ]
+    }
+  ]
+}

package/skills/tdd-workflow/evals/triggers.json

@@ -0,0 +1,15 @@
+{
+  "should_trigger": [
+    "Add a discount-code field to the checkout service, test first please",
+    "There's a bug where negative quantities are accepted in the cart. Reproduce it with a failing test and fix it.",
+    "Refactor the invoice calculator but keep behaviour identical, write tests before you touch it",
+    "Implement the parseDuration helper using red-green-refactor",
+    "I wrote the rate limiter before any tests; redo it properly test-first"
+  ],
+  "should_not_trigger": [
+    "Explain what test-driven development is in two sentences",
+    "Run all the checks on my branch before I open a pull request",
+    "Review my last commit for security vulnerabilities",
+    "Write a README section describing how to install the project"
+  ]
+}