dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-debug/references/investigation-techniques.md

@@ -0,0 +1,384 @@
+# Investigation Techniques
+
+Techniques for deeper investigation when standard code tracing is not enough. Load this when a bug does not reproduce reliably, involves timing or concurrency, is a performance regression, or requires framework-specific tracing.
+
+---
+
+## Root-Cause Tracing
+
+When a bug manifests deep in the call stack, the instinct is to fix where the error appears. That treats a symptom. Instead, trace backward through the call chain to find where the bad state originated.
+
+**Backward tracing:**
+
+- Start at the error
+- At each level, ask: where did this value come from? Who called this function? What state was passed in?
+- Keep going upstream until finding the point where valid state first became invalid — that is the root cause
+
+**Worked example:**
+
+```
+Symptom: API returns 500 with "Cannot read property 'email' of undefined"
+Where it crashes: sendWelcomeEmail(user.email) in NotificationService
+Who called this? UserController.create() after saving the user record
+What was passed? user = await UserRepo.create(params) — but create() returns undefined on duplicate key
+Original cause: UserRepo.create() silently swallows duplicate key errors and returns undefined instead of throwing
+```
+
+The fix belongs at the origin (UserRepo.create should throw on duplicate key), not where the error appeared (NotificationService).
+
+**When manual tracing stalls**, add instrumentation:
+
+```
+// Before the problematic operation
+const stack = new Error().stack;
+console.error('DEBUG [operation]:', { value, cwd: process.cwd(), stack });
+```
+
+Use `console.error()` in tests — logger output may be suppressed. Log before the dangerous operation, not after it fails.
+
+---
+
+## Multi-Component Boundary Instrumentation
+
+Root-cause tracing walks one call chain. When a bug crosses subsystems — CI → build → signing, API → service → database, frontend → API → background worker — the failure localizes poorly to a single chain. Instead, instrument every component boundary in one run, capture what enters and what exits each, and let the evidence point to the failing layer.
+
+**Shape:**
+
+1. List the component boundaries data crosses from trigger to observed symptom.
+2. At each boundary, log what enters and what exits — include the values, relevant environment, and a short tag identifying the boundary.
+3. Run the scenario once.
+4. Read the log linearly, comparing each "exits" value to the next "enters" value.
+5. The boundary where data first stops matching expectation is the failing layer.
+
+**Worked example (app signing on CI):**
+
+```bash
+# Layer 1: workflow env
+echo "=== workflow env ==="
+echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+# Layer 2: build script env
+echo "=== build script env ==="
+echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+# Layer 3: signing stage keychain state
+echo "=== keychain ==="
+security list-keychains
+security find-identity -v
+
+# Layer 4: the actual signing call
+codesign --sign "$IDENTITY" --verbose=4 "$APP"
+```
+
+One run, and the log shows precisely which layer drops the value — secrets → workflow ✓, workflow → build ✗ → focus investigation on the workflow-to-build-script inheritance, not on signing.
+
+**When this beats backward tracing:** When the symptom is far from the trigger (many components apart), when components are owned by different systems (CI vs app code), when the "call stack" is conceptual rather than literal (message bus, HTTP, process boundaries). Backward tracing still applies within each layer once the failing layer is identified.
+
+---
+
+## Git Bisect for Regressions
+
+When a bug is a regression ("it worked before"), use binary search to find the breaking commit:
+
+```bash
+git bisect start
+git bisect bad                    # current commit is broken
+git bisect good <known-good-ref> # a commit where it worked
+# git bisect will checkout a middle commit — test it
+# mark as good or bad, repeat until the breaking commit is found
+git bisect reset                  # return to original branch when done
+```
+
+For automated bisection with a test script:
+
+```bash
+git bisect start HEAD <known-good-ref>
+git bisect run <test-command>
+```
+
+The test command should exit 0 for good, non-zero for bad.
+
+---
+
+## Intermittent Bug Techniques
+
+When a bug does not reproduce reliably after 2-3 attempts:
+
+**Logging traps.** Add targeted logging at the suspected failure point and run the scenario repeatedly. Capture the state that differs between passing and failing runs.
+
+**Statistical reproduction.** Run the failing scenario in a loop to establish a reproduction rate:
+
+```bash
+for i in $(seq 1 20); do echo "Run $i:"; <test-command> && echo "PASS" || echo "FAIL"; done
+```
+
+A 5% reproduction rate confirms the bug exists but suggests timing or data sensitivity.
+
+**Environment isolation.** Systematically eliminate variables:
+- Same test, different machine?
+- Same test, different data seed?
+- Same test, serial vs parallel execution?
+- Same test, with vs without network access?
+
+**Data-dependent triggers.** If the bug only appears with certain data, identify the trigger condition:
+- What is unique about the failing input?
+- Does the input size, encoding, or edge value matter?
+- Is the data order significant (sorted vs random)?
+
+**Test-order pollution.** If an individual test passes in isolation but fails when the suite runs, tests are leaking state between each other:
+
+- Run the failing test alone — if it passes, pollution is confirmed
+- Run the failing test's file alone — narrows pollution to same-file or cross-file
+- Run the suite with randomized test order (most runners support a seed flag) — a different failing-test neighbor each run implies global state mutation
+- Bisect the preceding tests: run the failing test with just the first half of the earlier tests, then the second half, then narrow
+
+Common culprits once isolated: module-level state, mocks not torn down, temp files not cleaned up, database rows not rolled back, environment variables mutated and not restored.
+
+---
+
+## Repro Minimization
+
+Once a bug reproduces reliably, the reproduction is often large — a 500-line integration test, a huge payload, a lengthy form-filling sequence. A smaller reproduction makes every subsequent investigation step faster and localizes the actual trigger.
+
+**Delta debugging (manual):**
+
+1. Cut the reproduction in half.
+2. Does it still fail? If yes, discard the other half; recurse on what remains. If no, the failing behavior depends on something in the half you cut — put it back and cut the other half instead.
+3. Continue until no further reduction is possible without losing the failure.
+
+**For input payloads:**
+
+- Remove fields one at a time (or half at a time) while confirming the bug persists
+- Shrink string values until the minimum length that still triggers the bug
+- Replace complex nested structures with the smallest shape that reproduces
+
+**For test sequences:**
+
+- Remove setup steps that don't appear to affect the failing assertion
+- Inline helpers into the test to see what actually runs
+- Remove other assertions to isolate which one fails and on what state
+
+The minimized repro often reveals the root cause directly — "the bug only triggers when the string contains a tab character" is a much louder signal than "the bug triggers in this 500-line integration test."
+
+---
+
+## Framework-Specific Debugging
+
+### Rails
+- Check callbacks: `before_save`, `after_commit`, `around_action` — these execute implicitly and can alter state
+- Check middleware chain: `rake middleware` lists the full stack
+- Check Active Record query generation: `.to_sql` on any relation
+- Use `Rails.logger.debug` with tagged logging for request tracing
+
+### Node.js
+- Async stack traces: run with `--async-stack-traces` flag for full async call chains
+- Unhandled rejections: check for missing `.catch()` or `await` on promises
+- Event loop delays: `process.hrtime()` before and after suspect operations
+- Memory leaks: `--inspect` flag + Chrome DevTools heap snapshots
+
+### Python
+- Traceback enrichment: `traceback.print_exc()` in except blocks
+- `pdb.set_trace()` or `breakpoint()` for interactive debugging
+- `sys.settrace()` for execution tracing
+- `logging.basicConfig(level=logging.DEBUG)` for verbose output
+
+---
+
+## Stepping Debugger vs Instrumentation
+
+Print-debugging is the default reach — it is fast to add and scales across many cases. But there are cases where an interactive stepping debugger converges to the root cause far faster. The rule of thumb:
+
+- **Reach for a stepping debugger when:** the failing code path is localized (a specific function or tight call chain), the bug is reliably reproducible, and you need precise state at a known point — values of many locals at once, the exact shape of a structure, or the progression of state across a loop. One break, inspect everything.
+- **Reach for instrumentation when:** the bug is intermittent, spans many calls or distributed components, or happens in a context where breaking execution is disruptive (production, concurrent code whose timing matters, long-running processes). Instrumentation captures diffuse behavior across time and environments.
+
+Mixed use is common: instrument first to localize, then attach a debugger at the localized point.
+
+**Entry points by language:**
+
+| Language | Interactive breakpoint | Attach to running process |
+|----------|------------------------|---------------------------|
+| Python | `breakpoint()` in code, or `python -m pdb script.py` | `python -m pdb -p <pid>` (Python 3.14+ only); on earlier versions, instrument the target with `rpdb` / `remote-pdb` and connect after it triggers |
+| Node.js | `debugger;` in code + `node --inspect-brk`, then connect via Chrome DevTools or VS Code | `kill -SIGUSR1 <pid>` to enable the inspector on the running process (Linux/macOS), then connect Chrome DevTools or VS Code to the default port 9229 |
+| Ruby | `binding.irb` (stdlib), `binding.pry` (pry gem), `debugger` (debug gem), `rdbg` | `rdbg --attach <pid>` with `debug` gem loaded |
+| Go | `dlv debug` or `dlv test`, then `break`, `continue`, `print` | `dlv attach <pid>` |
+| Rust / C / C++ | `lldb target/debug/binary` or `gdb binary`, then `break`, `run`, `print` | `lldb -p <pid>` / `gdb -p <pid>` |
+| Browser JS | `debugger;` in code, or DevTools Sources → set breakpoint | DevTools attaches to page automatically |
+
+For test runs, most test runners integrate with the above — e.g., `node --inspect-brk $(which jest)`, `pytest --pdb`, `rspec` with `binding.pry`, `dlv test`. Prefer the runner's integration over trying to attach post-hoc.
+
+---
+
+## Performance Regressions
+
+When the symptom is "slow" rather than "wrong", logs and code reading mislead: intuition about where time goes is unreliable, and a plausible-looking hot spot is a hypothesis, not evidence. Measure first, change second:
+
+- Establish a numeric baseline before touching anything — a timing harness around the slow operation, a profiler run, a query plan (`EXPLAIN ANALYZE`). The baseline is Phase 1's reproduction check for a perf bug: the number is the red, and the fix is verified by re-measuring the same thing, not by reasoning that the change should be faster.
+- Attribute before optimizing: a profile or per-stage timings that show where the time actually goes. Optimizing an unmeasured suspect is the perf version of shotgun debugging.
+- If the slowness is a regression, bisect against the measurement (see Git Bisect above) rather than reading diffs for something that looks expensive.
+
+---
+
+## Race Condition Investigation
+
+When timing or concurrency is suspected:
+
+**Timing isolation.** Add deliberate delays at suspect points to widen the race window and make it reproducible:
+
+```
+// Simulate slow operation to expose race
+await new Promise(r => setTimeout(r, 100));
+```
+
+**Shared mutable state.** Search for variables, caches, or database rows accessed by multiple threads or processes without synchronization. Common patterns:
+- Global or module-level mutable state
+- Cache reads without locks
+- Database rows read then updated without optimistic locking
+
+**Async ordering.** Check whether operations assume a specific execution order that is not guaranteed:
+- Promise.all with dependent operations
+- Event handlers that assume emission order
+- Database writes that assume read consistency
+
+**Condition-based waits instead of arbitrary delays.** Flaky tests are often built on `setTimeout`/`sleep` calls that guess at how long an operation takes. These pass on fast machines and fail under load or in CI. Replace the guess with polling the condition the test actually depends on, bounded by a timeout:
+
+```typescript
+// before: races under load
+await new Promise(r => setTimeout(r, 50));
+expect(getResult()).toBeDefined();
+
+// after: waits for the condition
+await waitFor(() => getResult() !== undefined, 'result available', 5000);
+expect(getResult()).toBeDefined();
+```
+
+Arbitrary delays remain correct only when testing actual timing behavior (debounce intervals, throttle windows) — in that case, comment why the specific duration is needed.
+
+---
+
+## Heisenbugs and the Observer Effect
+
+When adding `console.log`, attaching a debugger, or inserting instrumentation causes the bug to disappear, the observation is changing the system's behavior. That is itself diagnostic — do not conclude "fixed." The bug is still present; your instrumentation perturbed it out of sight.
+
+**What the disappearance tells you:**
+
+- **Timing-sensitive:** Instrumentation slowed the code enough that a race condition no longer wins. Investigate concurrency, async ordering, and shared mutable state rather than the nominal logic.
+- **Garbage-collection-sensitive:** Logging allocated memory and triggered a GC that hid the symptom. Look at memory pressure, finalizers, object lifecycle.
+- **Optimization-dependent:** Instrumentation prevented a compiler/JIT optimization that was producing wrong results. Rare but real (especially in C/C++/Rust release builds).
+- **Buffering-dependent:** Log flushing changed I/O ordering. Often indicates unflushed writes elsewhere.
+- **Async-ordering-sensitive:** Log I/O introduced a microtask boundary that reorders subsequent operations. Look for code that implicitly depends on synchronous ordering.
+
+**How to investigate without perturbing:**
+
+- Non-blocking instrumentation: write to a ring buffer in memory, dump it only after failure is observed
+- Sampling profilers instead of tracing: external observation of what's running without injecting code into the path
+- Platform-level instrumentation: `strace`, `dtrace`, eBPF, platform profilers that don't require code changes
+- Post-mortem evidence: core dumps, heap snapshots, captured state from after the failure, without observing during
+
+The defining rule: if the bug is sensitive to observation, the fix must survive re-introduction of the observation. A fix that only works while instrumentation is present is itself a heisenbug.
+
+---
+
+## Browser Debugging
+
+When investigating UI bugs with `agent-browser` or equivalent tools:
+
+```bash
+# Open the affected page
+agent-browser open http://localhost:${PORT:-3000}/affected/route
+
+# Capture current state
+agent-browser snapshot -i
+
+# Interact with the page
+agent-browser click @ref          # click an element
+agent-browser fill @ref "text"    # fill a form field
+agent-browser snapshot -i         # capture state after interaction
+
+# Save visual evidence
+agent-browser screenshot bug-evidence.png
+```
+
+**Port detection:** If your in-context project instructions explicitly state the dev-server port, use it (don't grep instruction prose for a port — it's false-positive-prone); otherwise check `package.json` dev scripts, then `.env` files, falling back to `3000`.
+
+**Console errors:** Check browser console output for JavaScript errors, failed network requests, and CORS issues. These often reveal the root cause of UI bugs before any code tracing is needed.
+
+**Network tab:** Check for failed API requests, unexpected response codes, or missing CORS headers. A 422 or 500 response from the backend narrows the investigation immediately.
+
+---
+
+## Evidence Harvesting Across Systems
+
+When a bug spans a real environment — production, staging, a multi-service setup — the richest evidence usually already exists in logs, traces, and error-tracker payloads. Use it rather than reproducing from scratch when possible.
+
+**Follow a single request end-to-end.** Pick one concrete failing request (an exact timestamp, user ID, or event ID from an error tracker). Then:
+
+- Search every relevant log source for that identifier — correlation ID, request ID, trace ID, user ID
+- Assemble the timeline in order: edge → API → service → database → downstream calls → response
+- Note where the timeline has gaps (missing logs) or contradictions (timestamps out of order, IDs that don't propagate)
+
+One traced request usually reveals the root cause faster than a dozen attempts to reproduce.
+
+**Correlation IDs.** Most web frameworks either attach a request ID automatically or accept one via header (`X-Request-ID`, `traceparent`). When the project has one, every log line and every downstream call should carry it. If it's missing or not propagated, that is itself a finding — propagation gaps mean the agent cannot assemble the timeline, and neither could the on-call human who investigates the next incident.
+
+**Timestamp triangulation.** When the failing operation has no shared ID, timestamps are the fallback. Constrain every log query to a narrow window around the observed failure, then look for the first anomaly in order. Watch for clock skew between services — a 30-second drift between two hosts reorders evidence and misleads triangulation.
+
+**Error tracker payloads.** Sentry, Bugsnag, Honeybadger, AppSignal and similar tools capture stack traces, breadcrumbs, user context, request state, and release metadata at the moment of failure. Read the full payload before tracing code — it often contains the exact file:line, the variable state, and the breadcrumbs leading to the error. Grouping rules sometimes hide frequency and variant information; expand to see every instance rather than just the representative one.
+
+**APM / distributed traces.** When the project has Datadog APM, Honeycomb, New Relic, or an OpenTelemetry collector, the trace view shows the full call tree across services with timings. Look for: unexpectedly long spans (blocking or slow dependency), failed spans in the middle of the chain, spans that should exist but don't (missing instrumentation also masks bugs).
+
+**Preserve before investigating.** Error trackers and log systems have retention windows. Before starting a long investigation, export or snapshot the key evidence (event ID, trace ID, full stack trace, breadcrumbs) so it doesn't age out mid-session.
+
+---
+
+## System Boundary Checks
+
+Many bugs live at the boundary between an application and the system it runs on — network, database, filesystem, OS. A fast pass through these boundaries often eliminates whole categories of suspicion before deep code tracing.
+
+**Network.**
+
+- DNS resolution: `dig <host>`, `nslookup <host>`, `host <host>` — does the name resolve to what you expect from this host?
+- Reachability: `curl -v https://host/path` — full headers, redirects, TLS errors
+- Status codes and headers: check response for 4xx/5xx, unexpected redirects, missing CORS headers, content-encoding surprises
+- Connection state: `ss -tan` / `netstat -an` / `lsof -i` — open connections, listening ports, connections in TIME_WAIT or CLOSE_WAIT
+- TLS: `openssl s_client -connect host:443` — certificate chain, expiry, SNI mismatches
+
+**Database.**
+
+- Query plan: `EXPLAIN` / `EXPLAIN ANALYZE` on the suspect query — is it using the expected index, or scanning a large table?
+- Slow query log / recent queries: most databases can show the N slowest recent queries, and failing queries often show up there
+- Locks and transactions: inspect the lock/transaction tables (`pg_locks`, `information_schema.innodb_trx`, `sys.dm_tran_locks`) — is the operation waiting on a long-held lock?
+- Connection pool: is the app exhausting its pool? Are connections leaking?
+- Replication lag (if read replicas are in the path): a read right after a write may hit a replica that hasn't caught up yet
+
+**Filesystem.**
+
+- Existence and permissions: `ls -la <path>` — does the file exist, is it readable/writable by the running user?
+- Case sensitivity: bugs that only appear on Linux (not macOS) are often case mismatches
+- Open handles: `lsof <path>` or `lsof -p <pid>` — is something still holding the file, preventing write/unlink?
+- Disk space: `df -h`. Out-of-space errors sometimes appear as cryptic write failures elsewhere
+- File watching / inotify limits: EMFILE or "too many open files" often means an inotify/FD limit, not a leak in your code
+- Path separators and encoding: Windows-style paths in Unix code, or UTF-8 paths in a non-UTF-8 locale
+
+**Processes and signals.** Check whether the process is actually the version you think is running (`ps aux | grep`, cross-reference pid to build time). Zombies, orphaned workers, and crashed-then-restarted-with-old-code processes all masquerade as code bugs.
+
+---
+
+## Bug-Class Pattern Checklist
+
+Before deep tracing, run down this checklist. Many bugs match a recognizable class, and the class implies where to look first. Check whether the observed symptom fits any of these patterns:
+
+- **Time and timezone:** off-by-hours errors near midnight, failures specifically during DST transitions, epoch/milliseconds confusion, naive vs timezone-aware datetimes mixed, UTC-vs-local assumed incorrectly
+- **Encoding and locale:** mojibake in output, byte-vs-character length off-by-one, BOM at the start of a file breaking parsers, non-ASCII characters missing, locale-sensitive comparisons producing inconsistent results
+- **Floating-point precision:** comparisons that "should" be equal but aren't, NaN propagating through a calculation and silently corrupting downstream results, very large or very small numbers losing precision
+- **Integer overflow / underflow:** wraparound on bounded integer types, `int32` overflows in languages without arbitrary-precision integers, negative values where non-negative was assumed
+- **Off-by-one and boundaries:** empty-collection edge case, first or last element missing, inclusive vs exclusive range mismatch, fencepost errors
+- **Cache staleness:** correct behavior immediately after a change, wrong behavior after some time, fixed by restart or cache flush; includes HTTP caches, CDN caches, app-level memoization, browser service workers
+- **Permissions / auth:** works for one user and not another, works in dev without auth layer but fails in prod with it, works with superuser but not with the actual operating identity
+- **Dependency or version drift:** works on one machine but not another, lockfile out of sync with manifest, transitive dependency updated and changed behavior, native module built against a different runtime version
+- **Path / case sensitivity:** works on macOS and fails on Linux (case), works on Linux and fails on Windows (path separators, reserved names like `CON`/`PRN`)
+- **Concurrency / ordering:** works in serial test mode, fails in parallel; works one way and fails another when randomized
+- **Stale build artifacts:** `dist/`, `.next/`, compiled `.pyc`, generated code, Docker image layers — rebuild from clean and see if it reproduces
+- **Observer effect (heisenbug):** bug vanishes when logging, debugger, or profiler is attached — see the Heisenbugs section above
+- **TOCTOU (time-of-check vs time-of-use):** a check passed a moment ago but the underlying state changed before the dependent action ran
+
+Pattern-matching here is cheap. Spending 30 seconds checking whether the symptom fits a known class can eliminate hours of speculative tracing.

package/skills/ce-debug/references/pipeline-mode.md

@@ -0,0 +1,78 @@
+# ce-debug — pipeline mode (non-interactive)
+
+Loaded when `ce-debug` is invoked with `mode:pipeline` by an orchestrator (`ce-babysit-pr`, `lfg`). The skill runs to completion without ever asking the user and returns a structured result the caller composes. The investigation rigor is unchanged. Only the interaction and the fix-authority boundary change.
+
+## Authority: you act under the orchestrator's inherited scope
+
+Being invoked by an orchestrator is **not** itself authorization. You mutate under the **inherited** scope the orchestrator holds from the user: **actions** = fix / commit / push on the current branch; **exclusions** = merge, rebase, force-push, approve a gated CI run. That authorized scope is fixed. You may *narrow* it (defer a fix, return `needs-human`) but never *broaden* it. If the only way to make CI green is an excluded action (a rebase or force-push to untangle history, or approving a gated run), that action is outside the authorized scope: **defer as `needs-human`** with a `decision_context`, do not perform it. This is a boundary on the *mechanism* of a change. It sits alongside the convergent/divergent *content* boundary below. A fix can be convergent in content yet still outside the authorized scope in mechanism.
+
+## Non-interactive overrides (per phase)
+
+- **Phase 0 (triage):** If an issue fetch fails, do not ask the user to paste content. Proceed with the input you have and note the gap in the return. Do not ask "what have you tried"; infer prior attempts from the input.
+- **Phase 1 (reproduce):** When reproduction cannot run in this environment (a CI- or production-only failure), do not ask for access, artifacts, or a go-ahead. Continue on the best evidence already in reach: the failing job's logs, captured artifacts, the seeded log tails. If a gap-free root cause is still established, the ordinary statuses apply. If not, return `needs-human` with a `decision_context` naming what reproduction requires and what was tried.
+- **Phase 2 (root cause + fix gate):** There is no "Fix it now / Diagnosis only" question. The caller invoked this skill to fix, so **fix by default, but only convergent fixes** (see the boundary below). A divergent fix is deferred, not applied.
+- **Phase 3 (workspace/branch):** Operate on the current branch. The orchestrator decides branch context, so never prompt to create a branch and never prompt about uncommitted work. Commit the fix using the project's commit message conventions already in context; otherwise follow the recent log pattern, then use conventional commits (`fix(ci): <summary>` for a CI failure, `fix: <summary>` otherwise). User override wins. Push the fix. Never weaken, skip, or mock a failing assertion to make it pass. Repair the real issue or defer.
+- **Phase 4 (handoff):** No prompt. Emit the structured return below as the last thing this skill writes, then skip the compound offer. The return ends this skill, not the turn. The caller runs in this same session, and its next step follows the return.
+- **Post-fix simplify and review steps:** Skip them in pipeline to bound cost and nesting depth; the orchestrator scopes review at its own level. Keep the Phase 3 tests.
+
+## The fix-authority boundary: convergent vs divergent
+
+Apply a fix only when it **converges to intended behavior**. That means it repairs the real defect so the code meets its planned/tested intent (a genuine bug: null deref, off-by-one, a broken call, a regression against a test that encodes intended behavior).
+
+**Defer** (do not apply) any fix that would **diverge from intended behavior**: it would change a deliberate contract, API shape, default, or product/UX decision rather than repair a bug; or the "failure" is a test asserting a deliberate behavior that the fix would reverse; or making CI green would require a product/design call. This mirrors the `ce-resolve-pr-feedback` intent-conflict check. It requires evidence and is rare, and it is never a reason to dodge a real fix. When genuinely unsure whether a failure is a bug or a deliberate-behavior conflict, prefer deferring with a crisp `decision_context` over guessing.
+
+### Emergent trade-offs (when the caller passes a `trajectory`)
+
+Some divergence is not visible in one pass. It emerges across rounds as **ping-pong**: your fix for A causes B to appear, and the fix for B brings A back. When the orchestrator seeds you with a `trajectory` (`recurring_checks`, `check_recur_max`, `heads_since_progress`), reason over it before fixing again, and do not raise a false alarm:
+
+- **Progressive failure migration** (A fixed, B appears *once*, you fix B, done) is ordinary multi-step repair. **Keep fixing.** Do not park it.
+- **Oscillation** (the *same* check/invariant returns after a fix aimed at it, defects cycle, or each fix trades one failure for another) means A and B cannot both hold without a larger change. That larger change is a **product/design decision**, so **defer**: apply nothing this round and return `needs-human`, with a `decision_context` that names the two failures in tension, why they cannot be reconciled without a divergent change, the options, and your lean.
+- **Moving-target guard:** if the recurrence traces to an external cause (a base-branch merge, a dep bump, flaky infra) rather than your fixes fighting each other, it is *not* an emergent trade-off. Keep fixing, and note the external cause. Recurrence is only meaningful when your own fixes are what oscillate.
+
+To defer, name the invariant the fix would need to satisfy and why no bounded convergent change satisfies it. If unsure whether it is genuine oscillation or one more real bug, prefer one more convergent attempt over a premature park.
+
+## Reporting a deferred (divergent / needs-human) item
+
+Never write a PR-body section. Never block. Report it so the human sees it after the run:
+
+- If it maps to an **open review thread**, leave that thread open (and attach the `decision_context` as a reply when a thread reply is in scope).
+- Otherwise, **return it in the `residuals` list** for the caller to place in its single run-report comment. For a bare `ce-debug` invocation with no orchestrator and no PR, file it as a ticket in the project's tracker (detected in Phase 1.4) with enough background to action it standalone. When no tracker is reachable, return it in the structured result and say plainly that nothing else recorded it.
+
+Return each decision in the shared typed residual contract. Its `sources` enumerate every item this one decision covers: each failing check key with `kind: "check"`, plus the stable ID and kind of every open review thread, comment, or review body represented by the same decision. `decision_context` contains the quoted failure, investigation, decision reason, options with tradeoffs, and nullable recommendation. `thread_urls` includes every owned open thread (every open thread this decision covers) and is empty only when no source is a thread. The caller persists and invalidates the complete source set as one unit, so never split, omit, or summarize which items a decision covers.
+
+## Structured return
+
+The return in pipeline mode is machine-readable (the caller parses it):
+
+```json
+{
+  "status": "fixed-and-pushed | fixed-not-pushed | diagnosed-no-fix | flaky-infra | needs-human",
+  "summary": "<one line: what happened>",
+  "root_cause": "<causal chain, brief>",
+  "changed_files": ["..."],
+  "head_sha": "<sha of the fix commit, when fixed-and-pushed or fixed-not-pushed>",
+  "residuals": [
+    {
+      "type": "needs-human",
+      "sources": [
+        { "id": "<failing-check-key>", "kind": "check" },
+        { "id": "<owned-open-thread-id, when any>", "kind": "thread" }
+      ],
+      "decision_context": {
+        "quoted_feedback": "<the failure or constraint in tension>",
+        "investigation": "<what was inspected and found>",
+        "decision_reason": "<why no bounded convergent fix is safe>",
+        "options": [ { "option": "<choice>", "tradeoff": "<gain and loss>" } ],
+        "recommendation": "<lean and why, or null>"
+      },
+      "thread_urls": ["<URL for every owned open thread, or empty when none>"]
+    }
+  ]
+}
+```
+
+- `fixed-and-pushed`: a convergent fix was applied, tests pass, committed, and the push succeeded.
+- `fixed-not-pushed`: the same fix is applied and committed locally, but the push did not happen (no remote, no push access, an authorized scope that excludes pushing, a rejected push). `head_sha` is the local commit; the first residual says why. Never report this as `fixed-and-pushed` (the caller re-snapshots a remote head that has not moved) or as `diagnosed-no-fix` (the fix is applied).
+- `flaky-infra`: a flake or infrastructure failure, not a code defect (the caller may retry).
+- `needs-human`: the failure requires a divergent/product decision; nothing applied; see `residuals`.
+- `diagnosed-no-fix`: root cause found but no safe convergent fix available this run; see `residuals`.

package/skills/ce-debug/references/post-fix-handoff.md

@@ -0,0 +1,60 @@
+# ce-debug — post-fix handoff (interactive)
+
+Loaded at Phase 4 when Phase 3 actually applied a fix in interactive mode. Not used in `mode:pipeline` (see `pipeline-mode.md`) and not used when the user chose "Diagnosis only". In both of those cases Phase 4 ends at the Debug Summary.
+
+The goal of these post-fix steps is a **PR-ready** fix, not merely a locally green one, while never letting polish or review reach outside the bug's scope.
+
+## Post-fix polish and review steps (before commit or PR)
+
+**Contextual overrides first.** Check the user's original prompt, loaded memories, and the project's active instructions already in your context for explicit, clearly applicable preferences that conflict with automatic polish or review, such as "minimal hotfix only", "do not run review", "always ask before cleanup", or "ship the smallest possible diff". Honor them and state what was skipped.
+
+**Skip these steps only with a reason:** purely mechanical fixes (typo/import-only, formatting/lint-only, dependency-only, generated artifacts, docs-only, or roughly under 10 changed lines that touch nothing sensitive). Keep the Phase 3 tests and self-review regardless, and carry the skip reason into the summary.
+
+**Scope rule for both passes below: never let either pass reach work the user did not offer up.** Phase 3 recorded the fix-owned files (the files this fix changed) and which files were already dirty; that is the scope. Never widen it to the branch because the branch looks safe. A branch diff equals the fix scope only when the tree was clean anyway, so widening buys nothing there, and it silently swallows the user's WIP when the tree was not clean. Branch creation is not evidence of a clean tree: `git checkout -b` carries uncommitted work forward.
+
+**Simplify before review when useful.** Invoke `ce-simplify-code` with `mode:pipeline` when the fix diff is non-mechanical and large enough to benefit (default: >=30 changed lines), touches multiple implementation files, introduces a new helper or abstraction, or affects shared or risky areas (auth/authz, public contracts, persistence, concurrency, background jobs, external services). Always pass the fix-owned files that were clean before Phase 3 as an explicit scope, never the branch diff, and the bug's regression test as `proof-test:<path>`. `ce-simplify-code` treats a named scope as authoritative and will not widen it, and it *modifies* what it is given, so a named scope is the guardrail. If a fix-owned file already had pre-existing user edits, skip it and record `Simplify: skipped for overlapping pre-existing edits`. File-level simplification could rewrite unrelated hunks the user did not authorize.
+
+**Review the final fix scope.** Review every non-mechanical fix unless review tooling is unavailable. Run default `ce-code-review` **only when its diff scope is known to be this fix**: the pre-fix tree was clean and you can pass `base:<pre-fix-HEAD>`. Review reads rather than writes, so a base-scoped diff is worth preferring where it is provably the fix. It is the one place the scope may come from a revision rather than the file list. On a pre-existing dirty branch or one with unrelated committed work, standalone review would reach outside the bug scope. In that case use the harness's lightweight review tool if it accepts an explicit file scope; otherwise review the fix-owned files manually and record `Code review: targeted manual due to unrelated branch work`. If `ce-code-review` is unavailable on an otherwise fix-only scope, fall back to the harness's lightweight review tool, else one explicit manual diff scan, and state that dedicated review was unavailable.
+
+**Handle residual findings before shipping.** Do not auto-open a PR with unresolved P0/P1 findings, or with findings whose fix needs a product/design decision. Ask whether to fix now, accept/defer durably, or stop. Accepted residuals must not live only in the session. If a PR will be opened, pass them to `ce-commit-push-pr` as a `## Unapplied review findings` checklist section (`- [ ] <severity> — <file:line> — <title>` per finding). On commit-only or stop, file a ticket per finding in the tracker detected in Phase 1.4, with enough background to action it standalone (the finding, why it matters, file:line, severity, a pointer to the review run, and the branch/head SHA so it points at the code even without a PR). Pick the destination and file it; do not ask which destination to use. When no tracker is reachable, name the accepted findings in the final summary and say plainly that nothing else recorded them.
+
+**Re-verify after these edits.** If simplification or review changed code, rerun the bug's regression test and any targeted checks those steps identified. Never proceed to commit or PR with a red tree.
+
+Then append this block below the Debug Summary, before the commit/PR handoff:
+
+```
+## Post-Fix Quality
+**Scope**: [fix-only branch / base:<pre-fix-HEAD> / fix-owned files only / targeted manual due to unrelated branch work]
+**Simplify**: [ran/skipped + reason]
+**Review**: [ran/skipped/manual + outcome]
+**Residuals**: [none / unapplied review findings section for PR / filed as tracker tickets / stated in this summary only, no tracker reachable / blocked pending user decision]
+**Re-verification**: [checks rerun after tail edits]
+```
+
+## Commit / PR handoff detail
+
+SKILL.md's Phase 4 **Routing** block defines the bare per-case actions: which skill runs, and what to do when no PR is possible. It stays there because it must apply even if this file is never read. This section carries only the detail that shapes those actions.
+
+**Opening a PR is the default; do not ask for permission.** What varies the route is what else sits on the branch, never whether the user would approve. A branch carrying only this fix ships as a PR whether or not this skill created it.
+
+**Why a branch carrying unrelated work stops short of a push.** `ce-commit-push-pr` commits the changed files it finds, pushes the whole branch, and opens a PR spanning every commit on it. On a branch holding someone's in-progress work, that publishes what they never offered up, and hands that PR to `ce-babysit-pr`. The preview cannot catch this, because it does not wait for an answer. This is the same scope rule the polish steps above already apply to simplify and review; shipping gets no exemption from it.
+
+**Why the separable case acts and the entangled case asks.** Committing only the fix-owned files is safe and trivially reversible. The user who wanted exactly that pays no round trip, and the user who wanted the PR says one word. The routing offers the PR rather than asking permission for it. Entanglement is different in kind: when a fix-owned file already held the user's edits, every available move loses something real, and no default is defensible. Restricting the question to that state is what keeps it from becoming the reflexive prompt this routing exists to remove. Most runs reach neither state. A fresh branch or clean tree routes straight to the PR.
+
+**Contextual overrides come first.** An explicit, clearly applicable instruction such as "always review before pushing", "open PRs as drafts", "don't open PRs from skills", or "commit only" outranks the default routing: skip the PR step, adjust it, or stop, whichever matches what the user said. A vague tonal cue is not an override.
+
+**The preview is not a question.** State what gets committed, on what branch, and that a PR will be opened, then proceed without waiting. It exists so the user can interrupt.
+
+**`branding:on` is required.** The explicit branding signal records that `ce-debug` produced the fix. A handoff without it loses that provenance.
+
+**Link what already exists; never open a new record.** Reference the issue of record from Phase 0, plus any existing ticket Phase 1.4 found for this same bug. Linking something that already exists is always fine, and on an auto-closing tracker it is how the fix closes it. What is forbidden is *creating* a record for this bug. Do not open a ticket in a different system because the repo happens to use it, and do not ask the user whether you should. A Sentry issue, an alert, or a GitHub issue is as much the record as a Linear or Jira ticket, and a duplicate is noise the user then has to close. When Phase 0 found no issue of record (a pasted stack trace, a failing test), this run has none. Ship the fix without one rather than opening a ticket to fill the slot. A new ticket is warranted only for a *different* problem you found along the way, per the residual rule above.
+
+**Issue auto-close syntax.** When the issue you are linking lives in a tracker with auto-close support, include that tracker's syntax in the location it requires, so the fix flows back to the issue and closes it on merge. Most trackers parse PR descriptions (`Fixes #N` for GitHub, `Closes ABC-123` for Linear), but some parse only commit messages (Jira Smart Commits). When the record has no such syntax (an error monitor like Sentry, or a pasted alert), just link it in the PR description and say what the fix addresses.
+
+## Learning-capture criteria (after a PR is open)
+
+Offer once only when the verified fix produced non-obvious, durable project reasoning that is not readily recoverable from the final code, tests, types, comments, or existing documentation, and losing it would plausibly cause recurrence, material risk, or substantial rediscovery.
+
+Apply this counterfactual: if the learning document disappeared, would a future engineer reading the final implementation still be likely to repeat the mistake or redo substantial investigation? If not, skip silently. Completion, effort, and diff size do not establish eligibility.
+
+These are the criteria only; SKILL.md's Routing block defines what runs when the user accepts.

package/skills/ce-debug/references/return-to-caller.md

@@ -0,0 +1,57 @@
+# ce-debug — return-to-caller mode (non-interactive, caller owns the steps after the fix)
+
+Loaded when `ce-debug` is invoked with `mode:return-to-caller` by an orchestrator such as `lfg` on its defect route. The caller asked for the bug fixed and owns everything after the fix: simplify, review, compound, commit of anything further, push, PR, and CI. This skill investigates, fixes, verifies, commits on a feature branch, and returns a structured result. It never pushes and never asks.
+
+This is not `mode:pipeline`. Pipeline mode serves the babysitter on a PR branch it already owns: it is seeded with failing jobs, pushes its own commit, and skips review because the babysitter scopes review. Here nothing is pushed and the caller reviews.
+
+## What stays the same
+
+Phases 0 through 3 run as the body defines them, with the investigation rigor unchanged: the causal-chain gate, reproduction, the escalation table, the test-first fix sequence in `references/fix.md`, and the issue-of-record rule. The **Branch** rule in Phase 3 applies in full: on the default branch, detached, or unsure, create a feature branch named from the bug before the first edit and say which branch you moved to. `/lfg fix this bug` invoked on `main` must not commit to `main`. The pre-fix scope record and the fix-owned file list are kept, because the return is built from them: the caller ships only what the user offered, and this return is the only place it can learn what was already in the tree or on the branch before the fix.
+
+## What changes
+
+- **Phase 0:** if an issue fetch fails, continue with the input you have and record the gap in the return. Never ask the user to paste content.
+- **Phase 2 gate:** there is no fix-choice question. The caller's invocation authorized the fix, so proceed to Phase 3 with a **convergent** fix only. A **divergent** fix, one that would reverse a deliberate contract, behavior, or product decision, including a "failing" test that asserts intended behavior, is deferred as `needs-human` with a `decision_context`, never applied. Never route to `ce-brainstorm`; a design problem is a `needs-human` residual. When reproduction cannot run in this environment, continue on the best evidence in reach; if the causal chain still has a gap, return `needs-human` naming what reproduction requires and what was tried.
+- **Phase 3:** apply the fix on the feature branch, verify it as `references/fix.md` defines (red then green where a test can run here; otherwise the reproduction check or characterization that file allows, recorded in the evidence), and commit only the fix-owned files. Follow the project's commit message conventions already in context; otherwise follow the recent log pattern, then conventional commits (`fix: <summary>` for this bug). User override wins. Do not push. A file the fix must touch that already carries the user's uncommitted edits stops the run before the first edit to it: return `blocked` naming the file, with nothing applied, since no commit could separate their edits from the fix and the caller cannot answer for the user. The pre-fix scope record makes this known before Phase 3 edits anything.
+- **Phase 4:** skip the Debug Summary block, the post-fix polish and review steps (`references/post-fix-handoff.md`), the commit/PR routing, and the learning-capture offer. Emit the structured return below as the last thing this skill writes. The return ends this skill, not the turn. The caller runs in this same session, and its next step follows the return.
+
+## Structured return
+
+The return is machine-readable; the caller parses it and branches on the exact `status` spellings, so never rename, abbreviate, or add to them.
+
+```json
+{
+  "status": "fixed | diagnosed-no-fix | needs-human | blocked",
+  "summary": "<one line: what happened>",
+  "root_cause": "<the causal chain, trigger to symptom, with file:line references>",
+  "changed_files": ["<fix-owned files, tests included>"],
+  "head_sha": "<sha of the fix commit, when fixed>",
+  "branch": "<branch the fix was committed on, when fixed>",
+  "pre_fix_scope": {
+    "head": "<HEAD before the fix commit>",
+    "dirty_files": ["<files already modified or untracked before Phase 3 that are not fix-owned; left untouched>"],
+    "commits_beyond_base": ["<commits the branch carried beyond the default branch before the fix, oldest first; empty on a fresh branch>"],
+    "started_on_default_branch": false
+  },
+  "behavior_change": true,
+  "verification_evidence": {
+    "regression_test": "<file and case>",
+    "existing_tests_inspected": ["..."],
+    "tests_added_or_changed": ["..."],
+    "red_before_fix": "<the failure observed before the fix, or the characterization when a red run was impossible>",
+    "verification_run": "<commands and results>",
+    "exception_reason": null
+  },
+  "residuals": [ { "type": "needs-human", "sources": [ ... ], "decision_context": { ... }, "thread_urls": [] } ],
+  "issue_of_record": { "id": "<identifier>", "url": "<url>" },
+  "blockers": [],
+  "standalone_shipping_skipped": true
+}
+```
+
+- `fixed`: a convergent fix is applied, its regression test went red then green, and the fix-owned files are committed on the feature branch. Nothing was pushed.
+- `diagnosed-no-fix`: the root cause is established but no safe convergent fix exists this run; `residuals` says why.
+- `needs-human`: the fix would be divergent, or the causal chain could not be closed without a decision only a person can make; nothing applied; `residuals` carries the `decision_context` in the same typed residual contract `references/pipeline-mode.md` defines.
+- `blocked`: a required read failed, a fix-owned file carried the user's edits, or the workspace could not be prepared; `blockers` names it and nothing was committed.
+
+`pre_fix_scope` is present on every return and records what the branch and tree carried before the fix, as observed facts: the pre-fix `HEAD`, the files that were already dirty and are not fix-owned (the fix never touched them), and the commits beyond the default branch, pushed or not. It carries no verdict about what the user offered; the caller decides that, and this record is what it decides from. `issue_of_record` is `null` when the input carried no ticket. `verification_evidence` is present on every `fixed` return; when `behavior_change` is `false` (a pure test or tooling fix), `exception_reason` says why no red-then-green was possible. `residuals` is an empty array when there are none.