@stacksjs/defaults 0.72.102 → 0.73.0

package/ai/skills/stacks-investigate/SKILL.md

@@ -1,119 +1,247 @@
 ---
 name: stacks-investigate
-description: Use when debugging issues in the Stacks project — four-phase root-cause debugging with hypothesis testing and escalation. Enforces "no fixes without root cause." Invoke with /stacks-investigate.
+description: Use when debugging a Stacks issue - something broken, throwing, failing, flaky or slow. Builds a tight feedback loop that goes red on the bug before any hypothesis is allowed, then minimises, tests hypotheses, fixes and locks it down with a regression test. Enforces no fixes without root cause. Invoke with /stacks-investigate.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
-# /stacks-investigate — Root Cause Debugging
-
-You are a systematic debugger for the Stacks framework. Find the **root cause**, not just make symptoms go away. No fixes until the root cause is confirmed.
-
-## Phase 1: Investigate
-
-Gather information. Do not form hypotheses yet.
-
-1. **Understand the symptom**: What's happening vs. what should happen?
-2. **Reproduce mentally**: Read code paths end-to-end. Trace data flow from input to failure point.
-3. **Collect evidence**:
-   - Read error messages, stack traces, and logs (`storage/logs/stacks.log`)
-   - Check recent git history: `git log --oneline -20 -- [relevant files]`
-   - Check for related test failures: `bun test [relevant test file]`
-   - Check config files that affect the failing path (`config/*.ts`)
-4. **Map blast radius**: What else touches this code? Use `grep` to find all callers.
-
-For Stacks-specific issues, also check:
-- ORM model definitions in `storage/framework/defaults/app/Models/`
-- Route definitions in `routes/`
-- Action handlers in `storage/framework/core/actions/src/`
-- Middleware in `storage/framework/defaults/app/Middleware/`
-
-```
-## Investigation Summary
-**Symptom**: [what's happening]
-**Expected**: [what should happen]
-**Affected code**: [file:line references]
-**Recent changes**: [relevant commits]
-**Blast radius**: [other code/features affected]
-```
-
-## Phase 2: Pattern Analysis
-
-1. **When does it fail?** Always, or only under certain conditions? Environment-specific?
-2. **Failure mode?** Crash / wrong result / hang / intermittent
-3. **Where in the stack?**
-   - Framework issue (check `storage/framework/core/`)
-   - Application code issue (`app/`, `routes/`, `resources/`)
-   - Dependency issue (check `bun.lock` for version changes)
-   - Configuration issue (`config/*.ts`)
-
-```
-## Pattern Analysis
-**Failure type**: [crash / wrong result / hang / intermittent]
-**Consistency**: [always / conditional / intermittent]
-**Layer**: [framework / application / dependency / config]
-**Key observation**: [most important pattern]
-```
-
-## Phase 3: Hypothesis Testing
-
-Form up to 3 hypotheses, ranked by likelihood.
-
-```
-### Hypothesis 1 (most likely): [title]
-**Claim**: [specific root cause]
-**Prediction**: [observable if true]
-**Test**: [how to verify]
-**Result**: ✅ Confirmed / ❌ Refuted / ⚠️ Inconclusive
-```
-
-### Escalation Rule
-
-If all 3 hypotheses refuted:
-1. **Stop and reassess.** Don't generate more hypotheses in a loop.
-2. Present what you've ruled out.
-3. Ask for additional context.
-4. If still stuck after second round, recommend:
-   - Add targeted logging with `log.debug()` from `@stacksjs/logging`
-   - Write a minimal reproduction case
-   - Run `buddy doctor` for system diagnostics
-
-**Never apply a fix just to "see if it helps."**
-
-## Phase 4: Implementation
-
-Only enter when a hypothesis is confirmed.
-
-1. **Explain the root cause** in plain language
-2. **Show the minimal fix** — change as little as possible
-3. **Verify**:
-   - Run existing tests: `bun test`
-   - Check blast radius from Phase 1
-   - Run `bunx --bun pickier . --fix` for formatting
-4. **Suggest a regression test**
-
-```
-## Root Cause
-[Clear explanation]
-
-## Fix
-[Minimal code change with file:line references]
-
-## Verification
-- [x] Existing tests pass (`bun test`)
-- [x] Blast radius checked
-- [ ] Regression test: [suggested test]
-```
+# /stacks-investigate - root cause debugging
+
+A discipline for hard bugs. Find the **root cause**, not a way to make the
+symptom go away. Skip a phase only when you can say why.
+
+Credit: the feedback-loop-first structure is adapted from Matt Pocock's
+`diagnosing-bugs` skill (MIT), <https://github.com/mattpocock/skills>.
+
+## Redact
+
+This skill has you show commands, outputs and captured artifacts. **Redact every
+secret first**, writing `<REDACTED>` in its place. Build loops against env vars
+so the credential stays in the environment rather than in what you show. In a
+Stacks project the usual offenders are `.env`, `.env.production`,
+`config/services.ts`, `APP_KEY`, AWS keys and `HCLOUD_TOKEN`, plus captured HTTP
+traffic carrying an `Authorization` header. Quote only the lines that carry the
+signal.
+
+If the redacted output is not enough to diagnose the bug, say so and ask the
+user.
+
+## Phase 1: build a feedback loop
+
+**This is the skill.** Everything else is mechanical. With a **tight** pass/fail
+signal, one that goes **red** on *this* bug, you will find the cause: bisection,
+hypothesis testing and instrumentation all just consume it. Without one, no
+amount of staring at code will save you.
+
+Spend disproportionate effort here. Be aggressive, be creative, refuse to give
+up.
+
+### Ways to construct one, in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug. `bun test <path>` is the
+   loop. See `stacks-tdd` for which seam.
+2. **HTTP script** against `buddy dev`, using `curl` or `Bun.fetch` with a
+   fixture payload.
+3. **CLI invocation**, for instance `buddy <command>` with a fixture input,
+   diffing stdout against a known-good snapshot.
+4. **REPL probe**. `buddy repl` reaches models, config and the query builder
+   directly, which is the fastest loop for an ORM or relationship bug.
+5. **Headless browser script**. `/stacks-browse` drives a real browser over CDP
+   and asserts on DOM, console and network with nothing to install.
+6. **Replay a captured trace.** Save a real request, payload or event log to
+   disk, then replay it through the code path in isolation.
+7. **Throwaway harness.** A single file that boots the minimum (one action, a
+   seeded database) and exercises the bug path with one call.
+8. **Deterministic database state.** `buddy migrate:fresh --seed` plus the
+   model factories gives byte-identical rows every run, which turns "sometimes
+   wrong" into "always wrong" more often than you would expect.
+9. **Property or fuzz loop.** For "sometimes the output is wrong", run a
+   thousand inputs and look for the failure mode.
+10. **Bisection harness.** If the bug appeared between two known states, automate
+    "boot at state X, check, repeat" so `git bisect run` can consume it.
+11. **Differential loop.** Same input through two versions or two configs, diff
+    the outputs. This is the one for a dependency bump or a driver swap.
+12. **HITL bash script.** Last resort. If a human must click, drive *them* with
+    [scripts/hitl-loop.template.sh](scripts/hitl-loop.template.sh) so the loop is
+    still structured, and the captured output feeds back to you.
+
+Build the right feedback loop and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have *a* loop, **tighten** it:
+
+- Faster. Narrow the test path, skip unrelated init, reuse the seeded database
+  instead of re-migrating.
+- Sharper signal. Assert on the specific symptom, not "it did not crash".
+- More deterministic. Pin the clock, seed the RNG, isolate the filesystem, freeze
+  the network, and pick one driver rather than whatever `config/` happens to
+  select.
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic
+one is a superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the
+trigger 100 times, parallelise, add stress, narrow the timing window, inject
+sleeps. A 50% flake is debuggable, 1% is not, so keep raising the rate.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for one of: access
+to an environment that reproduces it, a redacted captured artifact (a HAR file, a
+log dump from `storage/logs/stacks.log`, a screen recording with timestamps), or
+permission to add temporary instrumentation in production. Do **not** proceed to
+hypothesise without a loop.
+
+### Completion criterion: a tight loop that goes red
+
+Phase 1 is done when you can name **one command** that you have **already run at
+least once**, showing the invocation and its output, redacted, and that is:
+
+- [ ] **Red-capable.** It drives the actual bug code path and asserts the
+      **user's exact symptom**, so it can go red now and green once fixed. Not
+      "runs without erroring".
+- [ ] **Deterministic.** Same verdict every run, or for a flaky bug, a pinned
+      high reproduction rate.
+- [ ] **Fast.** Seconds, not minutes.
+- [ ] **Agent-runnable.** You can run it unattended, with a human in the loop
+      only through the HITL template.
+
+If you catch yourself reading code to build a theory before this command exists,
+**stop. Jumping straight to a hypothesis is the exact failure this skill
+prevents.** No red-capable command, no Phase 2.
+
+## Phase 2: reproduce and minimise
+
+Run the loop. Watch it go red.
+
+Confirm:
+
+- [ ] The loop produces the failure the **user** described, not a different one
+      that happens to be nearby. Wrong bug means wrong fix.
+- [ ] It reproduces across multiple runs, or at a high enough rate to debug
+      against.
+- [ ] You have captured the exact symptom (error message, wrong output, slow
+      timing) so later phases can verify the fix addresses it.
+
+Then shrink the repro to the **smallest scenario that still goes red**. Cut
+inputs, callers, config, middleware, seeded rows and steps **one at a time**,
+re-running the loop after each cut, and keep only what is load-bearing.
+
+A minimal repro shrinks the hypothesis space in Phase 3 and becomes the clean
+regression test in Phase 5.
+
+Done when **every remaining element is load-bearing**: removing any one of them
+makes the loop go green.
+
+## Phase 3: hypothesise
+
+Generate **3 to 5 ranked hypotheses** before testing any of them.
+Single-hypothesis generation anchors on the first plausible idea.
+
+Each must be **falsifiable**, stating the prediction it makes:
+
+> If X is the cause, then changing Y will make the bug disappear, or changing Z
+> will make it worse.
+
+If you cannot state the prediction, the hypothesis is a vibe. Discard or sharpen
+it.
+
+Gather the evidence that ranks them from where Stacks actually keeps it:
+
+- `storage/logs/stacks.log` for the runtime trail.
+- `git log --oneline -20 -- <paths>` for what changed recently.
+- `config/*.ts` for which driver, connection or host is selected in this
+  environment.
+- `app/Models/` and `storage/framework/defaults/app/Models/` for the model, and
+  `database/migrations/` for whether the schema matches it.
+- `storage/framework/types/*.d.ts` and the auto-import manifests, which are
+  generated and go stale. A symbol that types as `any` in an app is usually this.
+- `routes/`, `app/Middleware.ts` and `app/Events.ts` for the registries, where a
+  missing entry fails silently rather than loudly.
+- `bun.lock` and `pantry.lock`. There are two install trees, and Bun resolves
+  `node_modules`, so verify the version that actually loads.
+
+Show the ranked list to the user before testing. They often re-rank it instantly
+("we just deployed a change to number three") or name one already ruled out. Do
+not block on it. Proceed with your ranking if the user is away.
+
+## Phase 4: instrument
+
+Each probe maps to a specific prediction from Phase 3. **Change one variable at a
+time.**
+
+Tool preference:
+
+1. **REPL or debugger inspection** where the environment supports it. One
+   breakpoint beats ten logs, and `buddy repl` is usually reachable.
+2. **Targeted logs** at the boundaries that distinguish the hypotheses, via
+   `log.debug()` from `@stacksjs/logging`.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix such as `[DEBUG-a4f2]`, so cleanup
+is a single grep. Untagged logs survive. Tagged ones die.
+
+**Performance branch.** For a regression, logs are usually the wrong instrument.
+Establish a baseline measurement first (a timing harness, `performance.now()`, a
+profiler, the query plan), then bisect. Measure first, fix second. In a Stacks
+app the first thing to measure is query count, because an N+1 through a
+relationship looks exactly like "the framework got slower".
+
+## Phase 5: fix and regression test
+
+Write the regression test **before the fix**, but only if there is a **correct
+seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it
+occurs at the call site. If the only available seam is too shallow (a single
+caller test when the bug needs several, a unit test that cannot replicate the
+chain that triggered it), a test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The
+architecture is preventing the bug from being locked down, which is a
+`stacks-codebase-design` problem, not a testing one.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix. Change as little as possible.
+4. Watch it pass.
+5. Re-run the Phase 1 loop against the original, un-minimised scenario.
+
+## Phase 6: cleanup
+
+Required before declaring done:
+
+- [ ] The original repro no longer reproduces. Re-run the Phase 1 loop.
+- [ ] The regression test passes, or the absence of a seam is documented.
+- [ ] All `[DEBUG-...]` instrumentation removed. Grep the prefix.
+- [ ] Throwaway harnesses deleted, or moved to a clearly marked debug location.
+- [ ] `./buddy lint:fix` and `./buddy typecheck` are clean.
+- [ ] The hypothesis that turned out correct is stated in the commit message, so
+      the next debugger learns.
 
 ## Rules
 
-- **No fixes without root cause.** If you can't explain WHY, you haven't found the bug.
-- **Read before you grep.** Understand architecture first.
-- **Don't blame the framework first.** Application code is wrong far more often than `storage/framework/core/` code.
-- **Intermittent bugs are timing bugs** until proven otherwise. Look for race conditions, missing `await`, shared mutable state.
-- **If the fix is more than ~20 lines, question the root cause.** Large fixes often mean you're working around the problem.
+- **No fixes without root cause.** If you cannot explain why, you have not found
+  the bug.
+- **Never apply a fix to see if it helps.** That is a hypothesis test with no
+  prediction and no cleanup.
+- **Do not blame the framework first.** Application code and configuration are
+  wrong far more often than `storage/framework/core/` is.
+- **Intermittent bugs are timing bugs** until proven otherwise. Look for a
+  missing `await`, a race, or shared mutable state.
+- **If the fix runs past about 20 lines, question the root cause.** Large fixes
+  usually mean you are working around the problem.
+- **Check the blast radius before you fix.** A change in `storage/framework/core/`
+  can reach 15+ downstream packages, and in a published package a change to a
+  `.d.ts` path can silently degrade consumers to `any`.
 
 ## Downstream
 
-> **Fix applied.** Run `/stacks-review` to verify — it will check against this investigation's root cause.
+> **Fix applied.** Run `/stacks-review` to review it, and `/stacks-retro` when
+> the real lesson is that the environment let the bug hide.

package/ai/skills/stacks-investigate/scripts/hitl-loop.template.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+#
+# Adapted from Matt Pocock's `diagnosing-bugs` skill (MIT),
+# https://github.com/mattpocock/skills
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+#
+# `capture` prints its value back to the terminal, where the agent reads it,
+# so capture observations, and leave signing in to the user as a `step`.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Run ./buddy dev, open the app, and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/ai/skills/stacks-jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-jobs
-description: Use when creating background job classes in app/Jobs/ — job structure, the handle method, job configuration (queue, tries, backoff, timeout, rate), dispatching patterns (dispatch, dispatchIf, dispatchAfter, dispatchNow), or the Every schedule constants. For the queue system internals (workers, batching, events, drivers, testing), see stacks-queue.
+description: Use when creating background job classes in app/Jobs/ - job structure, the handle method, job configuration (queue, tries, backoff, timeout, rate), dispatching patterns (dispatch, dispatchIf, dispatchAfter, dispatchNow), or the Every schedule constants. For the queue system internals (workers, batching, events, drivers, testing), see stacks-queue.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-listeners/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-listeners
-description: Use when creating event listeners in app/Listeners/ — the listener file structure, registering listeners in app/Events.ts, the listener-to-action mapping pattern, CLI event listeners in Console.ts, or debugging listener execution. For the event system API (dispatch, listen, emitter, model events), see stacks-events.
+description: Use when creating event listeners in app/Listeners/ - the listener file structure, registering listeners in app/Events.ts, the listener-to-action mapping pattern, CLI event listeners in Console.ts, or debugging listener execution. For the event system API (dispatch, listen, emitter, model events), see stacks-events.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-logging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-logging
-description: Use when implementing logging in Stacks — the log facade (info, error, warn, debug, success), dump/dd debugging, timing functions, file-based logging, or log configuration. Covers @stacksjs/logging and config/logging.ts.
+description: Use when implementing logging in Stacks - the log facade (info, error, warn, debug, success), dump/dd debugging, timing functions, file-based logging, or log configuration. Covers @stacksjs/logging and config/logging.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-mail/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-mail
-description: Use when creating mail classes in app/Mail/ — defining email content and templates, using the template() function with STX or HTML templates, variable interpolation, email layouts, or the app-level mail sending pattern. For the email framework itself (drivers, Mail singleton, EmailSDK, inbox management), see stacks-email.
+description: Use when creating mail classes in app/Mail/ - defining email content and templates, using the template() function with STX or HTML templates, variable interpolation, email layouts, or the app-level mail sending pattern. For the email framework itself (drivers, Mail singleton, EmailSDK, inbox management), see stacks-email.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-middleware
-description: Use when working with middleware in a Stacks application — defining middleware, applying to routes, middleware aliases, parameterized middleware, groups, or the middleware execution pipeline. Covers the Middleware class, app/Middleware.ts alias registry, and all 22 default middleware files.
+description: Use when working with middleware in a Stacks application - defining middleware, applying to routes, middleware aliases, parameterized middleware, groups, or the middleware execution pipeline. Covers the Middleware class, app/Middleware.ts alias registry, and all 22 default middleware files.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-migrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-migrations
-description: Use when working with database migrations in a Stacks application — creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 96+ built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
+description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 96+ built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-models/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-models
-description: Use when working with data models in Stacks — the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 50+ built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
+description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 50+ built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-new-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-new-feature
-description: Use when adding a new feature end-to-end in a Stacks application — the complete workflow from model definition through migration, action, route, test, and deployment. Covers the recommended order of operations for building features.
+description: Use when adding a new feature end-to-end in a Stacks application - slicing the work into tracer bullets, then building each slice from model through migration, action, route, test and deploy. Covers the recommended order of operations, the blocking edges between slices, and the expand-contract sequence for a wide refactor.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -10,12 +10,66 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 Step-by-step guide for building features end-to-end.
 
+## Slice it first
+
+Before any code, break the work into **tracer bullets**: vertical slices, each
+cutting a narrow but complete path through every layer.
+
+- Each slice cuts through model, migration, action, route and test. Vertical, not
+  a horizontal slice of one layer.
+- A finished slice is demoable or verifiable on its own.
+- Each slice fits in one fresh context window.
+- Any prefactoring goes first. Make the change easy, then make the easy change.
+
+Give each slice its **blocking edges**: the slices that must land before it can
+start. A slice with no blockers can start immediately, and the set of slices
+whose blockers are all done is the **frontier** you work from.
+
+Present the breakdown as a numbered list before building anything. For each
+slice: the title, what it delivers end to end, and what blocks it. Then ask
+whether the granularity is right, whether the edges are real, and whether
+anything should be merged or split. Iterate until the user approves.
+
+Where the project tracks work on a real tracker, publish the slices in
+dependency order so the edges can reference real identifiers. Where it does not,
+one file per slice under `.scratch/<feature>/issues/<NN>-<slug>.md`, numbered
+blockers-first, is enough. Avoid file paths and code snippets in either form,
+because they go stale faster than the ticket does.
+
+### The exception: a wide refactor
+
+A **wide refactor** is one mechanical change whose blast radius fans across the
+codebase, so a single edit breaks hundreds of call sites at once and no vertical
+slice can land green. Renaming a model column, retyping a shared symbol, and
+changing an exported signature in `storage/framework/core/` are all this shape.
+
+Do not force it into a tracer bullet. Sequence it as **expand and contract**:
+
+1. **Expand.** Add the new form beside the old so nothing breaks. A new column
+   alongside the old one, a new export alongside the old one.
+2. **Migrate** the call sites in batches sized by blast radius, one per package or
+   directory, each batch its own slice blocked by the expand. CI stays green
+   batch to batch because the old form still exists.
+3. **Contract.** Delete the old form once no caller remains, in a slice blocked by
+   every migrate batch.
+
+When even the batches cannot stay green alone, keep the sequence but let them
+share an integration branch that all block a final integrate-and-verify slice.
+Green is promised only there.
+
+Credit: the tracer-bullet and expand-contract framing is adapted from Matt
+Pocock's `to-tickets` skill (MIT), <https://github.com/mattpocock/skills>.
+
 ## Workflow Overview
 
 ```
 1. Model → 2. Migration → 3. Action → 4. Route → 5. Test → 6. Lint → 7. Deploy
 ```
 
+Run this once per slice, not once per feature. Within a slice, `stacks-tdd`
+owns the red-green loop: the migration lands, then the failing test, then the
+code that passes it.
+
 ## Step 1: Define the Model
 
 ```typescript
@@ -119,7 +173,7 @@ route.group({ prefix: '/articles', middleware: ['auth'] }, () => {
 })
 ```
 
-Or rely on auto-generated routes from `useApi` trait — they're created automatically.
+Or rely on auto-generated routes from `useApi` trait - they're created automatically.
 
 ### When a TypeScript client will call these
 
@@ -144,14 +198,14 @@ const client = createTypedClient<AppRoutes>({ baseUrl })
 const created = await client.post('/articles', { title: 'x', content: 'y' })
 ```
 
-Same runtime path, same middleware, same OpenAPI document — the difference is
+Same runtime path, same middleware, same OpenAPI document - the difference is
 entirely at compile time. Keep the string form for routes no TypeScript consumer
 calls; it stays lazily imported. See the `stacks-api` and `stacks-router` skills.
 
 ## Step 5: Add Event Listeners (Optional)
 
 ```typescript
-// app/Events.ts — add to existing
+// app/Events.ts - add to existing
 {
   'article:created': ['NotifySubscribers'],
   'article:published': ['SendNewsletter', 'IndexInSearchEngine']
@@ -225,9 +279,15 @@ export default new Job({
 ```
 
 ## Gotchas
-- Models work directly via the dynamic ORM — no generation step needed before migrations
+- Models work directly via the dynamic ORM - no generation step needed before migrations
 - The `useApi` trait auto-generates both routes AND dashboard views
 - Model events (observe: true) emit `article:created`, `article:updated`, `article:deleted`
 - Factories in model attributes are used by `buddy seed`
 - Always lint after code generation: `bunx --bun pickier . --fix`
 - Use conventional commits: `feat: add article management`
+
+## Downstream
+
+> **Slice green?** Run `/stacks-review` before merging it, then take the next
+> slice off the frontier. `/stacks-tdd` is the loop inside each one, and
+> `/stacks-plan-review` is where to go back to if the slices stop making sense.

package/ai/skills/stacks-notifications/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-notifications
-description: Use when implementing notifications in Stacks — multi-channel notifications (email, SMS, push, chat, database), the database notification driver with read/unread tracking, notification factories (useEmail, useSMS, useChat, useDatabase), or notification configuration. Covers @stacksjs/notifications and config/notification.ts.
+description: Use when implementing notifications in Stacks - multi-channel notifications (email, SMS, push, chat, database), the database notification driver with read/unread tracking, notification factories (useEmail, useSMS, useChat, useDatabase), or notification configuration. Covers @stacksjs/notifications and config/notification.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-objects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-objects
-description: Use when working with object manipulation in Stacks — deep merging with type safety, object mapping/transformation, strict key checking, typed entries/keys, property picking, clearing undefined values, or the DeepMerge utility type. Covers @stacksjs/objects.
+description: Use when working with object manipulation in Stacks - deep merging with type safety, object mapping/transformation, strict key checking, typed entries/keys, property picking, clearing undefined values, or the DeepMerge utility type. Covers @stacksjs/objects.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob