gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/skills/forensics/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: forensics
+description: Post-mortem a failed GSD auto-mode run. Traces from symptom to root cause using `.gsd/activity/*.jsonl`, `.gsd/journal/YYYY-MM-DD.jsonl`, `.gsd/metrics.json`, and `.gsd/auto.lock`. Produces a filing-ready bug report with file:line references and a concrete fix suggestion. Use when asked to "forensics", "post-mortem", "why did auto-mode fail", "trace the stuck loop", "debug the crash", after `/gsd forensics` is invoked, or when a session ended in an unexpected terminal state. Reads existing artifacts — does NOT re-run anything.
+---
+
+<objective>
+Turn scattered GSD runtime artifacts into one coherent cause chain. The deliverable is a GitHub-issue-ready report that names the file and line where the bug lives, cites the evidence, and proposes a fix. Forensics is archaeology, not re-run — no modifying state, no triggering commands, just reading the paper trail.
+</objective>
+
+<context>
+GSD persists a lot of runtime evidence under `.gsd/`:
+
+- `activity/{seq}-{unitType}-{unitId}.jsonl` — full tool-call and message stream per unit
+- `journal/YYYY-MM-DD.jsonl` — iteration-level events (dispatch-match, stuck-detected, guard-block, unit-start/end, terminal)
+- `metrics.json` — token/cost ledger; duplicate `type/id` entries indicate a stuck loop
+- `auto.lock` — JSON snapshot of the currently-owning PID; stale lock = crash mid-unit
+- `forensics/` — saved prior reports
+- `debug/` — debug logs if enabled
+- `runtime/paused-session.json` — serialized session when auto-mode paused
+- `doctor-history.jsonl` — doctor check history
+
+The `/gsd forensics` command pre-computes a forensic report with anomalies flagged. This skill is the manual investigation that goes deeper, or runs when the automated report isn't enough.
+
+Invocation points:
+- `/gsd forensics` has been run and user wants deeper analysis
+- Auto-mode exited unexpectedly, no obvious cause
+- Same unit dispatched multiple times (stuck loop suspected)
+- A session crashed and `auto.lock` is stale
+- User reports "it just stopped" or "it did the wrong thing"
+</context>
+
+<core_principle>
+**READ-ONLY.** Forensics touches no live state. Non-mutating inspection commands (e.g., `ps`, `top -b`, `cat /proc/*`) are allowed for checking process status or reading system files. Strictly prohibited: `gsd_*` writes, commands that modify state, executing binaries that produce side effects, writing to files (outside the final report), or re-running the failed unit. The evidence must stay pristine for future investigations.
+
+**SYMPTOM → ROOT CAUSE, WITH CITATIONS.** Every claim in the report is backed by an artifact path and either a line number or a JSONL field. "The loop got stuck because of a race" is not useful; "`.gsd/journal/2026-04-19.jsonl:142` shows `stuck-detected` with flowId X, caused by `dispatch-guard.ts:87` returning the same unit after `unit-end`" is.
+
+**PRE-PARSED LEADS, NOT CONCLUSIONS.** If `/gsd forensics` has surfaced anomalies, treat them as hypotheses to verify, not answers.
+</core_principle>
+
+<process>
+
+## Step 1: Locate the evidence
+
+Read what's in `.gsd/`:
+
+1. `auto.lock` — is it stale? Check PID against `ps` (read-only inspection, allowed). Stale = crash.
+2. Most recent `.gsd/activity/*.jsonl` — sort by mtime, newest first. That's the last unit that ran.
+3. Today's `.gsd/journal/YYYY-MM-DD.jsonl` — the iteration-level view.
+4. `.gsd/metrics.json` — does any `type/id` appear more than once? (stuck loop signal)
+5. `.gsd/runtime/paused-session.json` — if present, what was the pause reason?
+
+## Step 2: Reconstruct the failure from the activity log
+
+Activity JSONL format:
+- Each line is `{type: "message", message: {...}}`.
+- `message.role: "assistant"` → `content[]` with `type: "text"` reasoning and `type: "toolCall"` invocations.
+- `message.role: "toolResult"` → `{toolCallId, toolName, isError, content}`.
+- `usage` on assistant messages tracks tokens and cost.
+
+To trace a failure:
+1. Search for `isError: true` tool results in the last activity log. That's usually the proximate symptom.
+2. Walk backwards to the assistant message that made the call. Read the `text` content — that's the agent's reasoning at the moment of failure.
+3. Keep walking back. Find where the agent's model of the state diverged from reality.
+
+## Step 3: Cross-reference the journal
+
+For each symptom from the activity log, find the matching journal events:
+- `stuck-detected` + same `flowId` → the loop detected repetition. `data.reason` says why.
+- `guard-block` → a dispatch guard refused to run a unit. Check `data.reason` and trace to `dispatch-guard.ts` logic.
+- `unit-end` followed by another `unit-start` for the same `unitId` → re-dispatch. If tied to `stuck-detected`, the artifact verification failed after the unit succeeded.
+- `terminal` → auto-mode decided to stop. `data.reason` tells you why.
+
+Use `flowId` to reconstruct one iteration; use `causedBy` to follow causal chains across iterations.
+
+## Step 4: Name the root cause
+
+A good root cause is:
+- Specific: a function, a state transition, a missing guard.
+- Falsifiable: if we changed X, would the failure go away?
+- Sourced: cites a file and (where applicable) a line number.
+
+Bad root cause: "Auto-mode got stuck in a loop." Good root cause: "After slice completion, `auto-unit-closeout.ts` emits `unit-end` before `auto-post-unit.ts` updates the roadmap checkbox. The next `iteration-start` finds the same unit `[ ]` and re-dispatches — `dispatch-guard.ts:42` has no check against the freshly-ended `unitId`."
+
+Consult the source map in `src/resources/extensions/gsd/prompts/forensics.md` to map symptoms to the likely domain files.
+
+## Step 5: Propose a fix
+
+For the root cause:
+- Which file and function holds the bug?
+- What minimal change would eliminate it?
+- What test would have caught it? Can one be added?
+- Is this a regression from a recent commit? (Run `git log -- path/to/file.ts` mentally; do NOT run git commands that could modify state.)
+
+## Step 6: Write the report
+
+Format the output as a GitHub-issue-ready report:
+
+```markdown
+## Symptom
+
+<what the user saw — quote the error or describe the observed behavior>
+
+## Evidence Trail
+
+1. `.gsd/auto.lock` — <state: stale / fresh>
+2. `.gsd/activity/042-slice-S02.jsonl:128` — <isError: true from `gsd_task_complete`>
+3. `.gsd/journal/2026-04-19.jsonl:87` — <stuck-detected flowId 7a3c…>
+4. `.gsd/metrics.json` — <unit type/id "slice/S02" appears 3 times>
+
+## Root Cause
+
+<specific named cause — file, function, state transition>
+
+`src/resources/extensions/gsd/auto-unit-closeout.ts:<line>`: <exactly what goes wrong>
+
+## Proposed Fix
+
+<minimal change — file, function, what to change>
+
+## Test
+
+<what test would have caught this; whether one should be added>
+
+## Confidence
+
+<high / medium / low> — <what would change this confidence>
+```
+
+Offer to file this as a GitHub issue via `mcp__github__issue_write` — explicit confirmation required per the outward-action rule. Also save a copy to `.gsd/forensics/<slug>.md` for future reference.
+
+</process>
+
+<anti_patterns>
+
+- **Running any `gsd_*` write tool during forensics.** Evidence stays pristine.
+- **Re-running the auto-mode loop to "reproduce."** That overwrites the activity log. Read the existing one.
+- **Vague root cause.** "There's a race" is not a root cause. Name the race.
+- **No citations.** Every claim gets an artifact path.
+- **Skipping the journal.** The journal is the only view that shows dispatch-level decisions.
+- **Auto-filing the GitHub issue.** Outward actions need confirmation.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] The symptom is quoted, not paraphrased.
+- [ ] Every claim in the evidence trail cites a file and a line or field.
+- [ ] The root cause names a specific file, function, or state transition.
+- [ ] The proposed fix is minimal and falsifiable.
+- [ ] Confidence is stated honestly.
+- [ ] Report is saved under `.gsd/forensics/` even if not filed as an issue.
+
+</success_criteria>

package/src/resources/skills/grill-me/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: grill-me
+description: Relentless sequential interview that stress-tests a plan or design until every decision branch is resolved. Use when the user wants to "grill me", "stress-test the plan", "interrogate my design", "resolve the decision tree", or whenever a plan feels hand-wavy, under-specified, or carries hidden coupling that planning phases must surface before execution. Pairs with the discuss phase and blocks execution until alignment is reached.
+---
+
+<objective>
+Interview the user one question at a time until every material branch of the decision tree is resolved and you both share one mental model of the plan. Output is not a document — it is alignment. Surface hidden assumptions, kill fuzzy language, and walk the dependencies between decisions instead of asking everything in parallel.
+</objective>
+
+<context>
+Planning conversations in GSD ship to `M###-CONTEXT.md`, `S##-CONTEXT.md`, or `.gsd/DECISIONS.md`. Those artifacts are only as good as the interview that produced them. This skill is the interview. It runs during the `discuss` phase, after `research`, or any time a plan has open branches the user has not actually thought through.
+
+Use this skill when:
+- The user asks to be grilled, stress-tested, or interrogated
+- A plan reads like a list of happy paths with no failure modes
+- Two or more sections of a plan implicitly depend on one undecided choice
+- The user says "I think" or "probably" about something that will bind the design
+</context>
+
+<core_principle>
+**ONE QUESTION AT A TIME.** Parallel questions destroy dependency order — the answer to Q2 is often contingent on the answer to Q1, and asking both at once forces the user to reason about a combinatoric space instead of a single fork. Ask, wait, absorb, ask the next.
+
+**RECOMMEND AN ANSWER.** Every question ships with your recommendation and a one-line reason. The user's job is to confirm, override, or redirect — not to generate answers from scratch.
+
+**CODEBASE BEFORE QUESTION.** If the answer exists in the repo — a convention, an existing pattern, a prior decision — find it and cite it rather than asking.
+</core_principle>
+
+<process>
+
+## Step 1: Map the decision tree silently
+
+Before asking anything, read what the user has already said in this conversation plus any existing `M###-CONTEXT.md`, `S##-CONTEXT.md`, and `.gsd/DECISIONS.md`. Build a private list of every decision the plan depends on, in dependency order. Do not show this list — it is scaffolding.
+
+If the plan touches unfamiliar code, spawn `Agent(subagent_type=Explore)` in parallel to map the relevant modules while you prepare Question 1. Do not wait for it to finish before starting the interview.
+
+## Step 2: Ask Question 1
+
+Pick the root decision — the one that the most other decisions depend on. Format:
+
+```text
+**Q1:** <precise question>.
+
+**Recommendation:** <your pick>, because <one sentence>.
+
+Alternatives worth considering: <A | B | C>.
+```
+
+Stop. Wait for the answer.
+
+## Step 3: Absorb and branch
+
+Take the answer. If it kills branches of the tree, cross them off your private map. If it opens new branches, add them. Do not move on to Q2 until the current answer has been integrated. If the answer is ambiguous, ask one clarifying follow-up — not three.
+
+## Step 4: Continue until the tree is closed
+
+Repeat Q2, Q3, … in dependency order. Each question follows the same format (question, recommendation, alternatives). Cap at the natural end of the decision tree, not a round number.
+
+Stop the interview when:
+- Every remaining open decision is either deferred by explicit user choice ("decide at execution time") or out of scope
+- The user says to stop
+- You have nothing left where the answer would materially change the plan
+
+## Step 5: Offer to write it up
+
+At the end, offer the user one of:
+
+1. Append resolved decisions to `.gsd/DECISIONS.md` (one line each, dated).
+2. Write or update `M###-CONTEXT.md` or `S##-CONTEXT.md` for the active milestone/slice.
+3. Draft a GitHub issue via `mcp__github__issue_write` (only with explicit confirmation per the outward-action rule).
+4. Leave it as conversation context if the work is ephemeral.
+
+Default: ask which they want. Do not auto-write.
+
+</process>
+
+<anti_patterns>
+
+- **Parallel questions:** "What's the schema? And the API? And the auth model?" — ask one.
+- **Yes/no railroading:** "Should we use X?" instead of "Between X and Y, which fits — given Z constraint?"
+- **Recommendation-free questions:** forces the user to generate from scratch; you have more context than you think.
+- **Asking what the code already answers:** check the repo first.
+- **Grilling past the useful horizon:** if the next question is about an implementation detail that will be decided during execution, stop.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Every decision with cross-cutting impact has an answer.
+- [ ] No "probably", "I think", or "we'll figure it out" remains on load-bearing decisions.
+- [ ] The user has confirmed the shape of the plan, not just each individual answer.
+- [ ] Resolved decisions are captured in an enduring artifact or explicitly left ephemeral.
+
+</success_criteria>

package/src/resources/skills/handoff/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: handoff
+description: Prepare a clean cross-session handoff so the next agent (or you tomorrow) can pick up exactly where you left off. Writes a focused `continue.md` in the active slice directory and ensures `STATE.md` + summary artifacts are current. Use when asked to "hand off", "prepare handoff", "pause work", "bookmark this", "I'll come back to this later", before running out of context budget, or at the end of a long session with unfinished work. Closes the v1 `/gsd-pause-work` parity gap.
+---
+
+<objective>
+Leave the project in a state where a fresh agent with no memory of this session can read two or three files and be productive within one minute. The deliverable is `continue.md` in the active slice directory plus up-to-date summary artifacts — not a chat recap.
+</objective>
+
+<context>
+GSD already writes `STATE.md` (rebuilt after each unit) and summary files (`M###-SUMMARY.md`, `S##-SUMMARY.md`, `T##-SUMMARY.md`). The gap is the *mid-task* handoff: you're partway through a task, context is getting long, and the next session shouldn't start by re-deriving your mental state.
+
+`continue.md` exists for exactly this — see `auto-prompts.ts`, `guided-flow.ts`, `phase-anchor.ts`, `state.ts`. This skill is the deliberate authoring ritual.
+
+Invocation points:
+- User says "pause", "hand off", "I'll come back later", "this is a good stopping point"
+- Context usage nearing budget — better to hand off cleanly than truncate mid-thought
+- Before a risky operation (dependency upgrade, major refactor) where you want a known-good checkpoint
+- End of a long session, multi-day work
+</context>
+
+<core_principle>
+**WRITE FOR A STRANGER.** The next reader is not you. They do not have this conversation. They have `STATE.md`, `continue.md`, the last summary, and the code. That has to be enough.
+
+**CURRENT STATE ONLY.** `continue.md` is ephemeral — it says "pick up HERE." It is not a log of what you did; that goes in summaries. It is not a plan for future work; that lives in the plan files.
+
+**NO SECRETS, NO STALE PATHS.** Do not inline env values, tokens, or paths that only exist in your working directory. Cite artifacts by relative path from the project root.
+</core_principle>
+
+<process>
+
+## Step 1: Identify what's in flight
+
+Answer briefly:
+1. What task (`T##`) am I on? What's its current plan file?
+2. What have I completed since the last summary?
+3. What's the next concrete action? (Not a goal — an action: "Run X. If Y, do Z.")
+4. What, if anything, is blocking or uncertain?
+
+## Step 2: Update the summaries, not the handoff
+
+Before writing `continue.md`:
+
+- **Any task that's actually done?** Use `gsd_task_complete` (or the equivalent tool) to toggle state. Do NOT edit checkboxes by hand. This triggers `STATE.md` rebuild and `T##-SUMMARY.md` generation.
+- **Any slice-level decisions worth preserving?** Append to `S##-CONTEXT.md` if the slice has one, or `.gsd/DECISIONS.md` if the decision was project-wide.
+- **Any patterns or traps future agents should know about?** Append a single line to `.gsd/KNOWLEDGE.md`.
+
+This shrinks what `continue.md` has to carry.
+
+## Step 3: Write continue.md
+
+Create `.gsd/milestones/<MID>/slices/<SID>/continue.md` with the following shape. Keep it tight — one screenful max.
+
+```markdown
+# Continue — S02 / T03
+
+## Last action
+
+<one sentence — what you just did, with evidence>
+Example: "Ran `npm test` after editing `src/auth/session.ts`; 2 failures in `session.test.ts` — both complain about a missing `expiresAt` field in the mock fixture."
+
+## Next action
+
+<one concrete action the next agent should take>
+Example: "Update `fixtures/sessions.ts` to include `expiresAt: Date.now() + 3600_000` on every fixture, then re-run `npm test`."
+
+## Why
+
+<one or two sentences — why this next step, not something else>
+Example: "The session refactor moved `expiresAt` from optional to required in `Session`; fixtures were never updated."
+
+## Open threads
+
+<list of things you noticed but deliberately didn't act on>
+- Validator in `src/auth/validator.ts` still accepts unbounded session lengths — file as a separate issue after T03 lands.
+
+## Do not
+
+<traps and false paths the next agent might stumble into>
+- Do NOT revert the `Session` interface change — it's required for T04.
+- Do NOT run `npm run db:reset` in this branch; dev data is still needed for manual UAT.
+```
+
+## Step 4: Sanity check
+
+Read `STATE.md` + `continue.md` + the most recent summary as if you were a fresh agent. Ask:
+1. Do I know what to do next?
+2. Do I know why?
+3. Do I know what not to do?
+
+If any answer is no, the handoff is incomplete. Fix it before stopping.
+
+## Step 5: Stop cleanly
+
+- Do not leave in-flight `async_bash` or `bg_shell` jobs. Cancel or wait for them.
+- Do not leave uncommitted changes without flagging them in `continue.md` — note which files are modified and why.
+- Do not push mid-task commits to remote unless that was the plan — they create noise for reviewers.
+
+</process>
+
+<anti_patterns>
+
+- **Chat-log handoffs.** "First I did X, then Y, then Z…" The next agent doesn't need the journey.
+- **`continue.md` that summarizes the whole slice.** That's what `S##-SUMMARY.md` is for, at slice completion.
+- **No "Next action".** A handoff without a concrete next action is a journal entry.
+- **Implicit assumptions.** "Obviously the next thing is…" — write it down.
+- **Leaving background processes running.** They'll be orphaned when the session ends.
+- **Handoff without updating summaries.** `continue.md` should be thin because the summaries carry the weight.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] `continue.md` exists in the active slice directory.
+- [ ] The "Next action" is concrete and executable without this session's context.
+- [ ] Completed tasks were marked done via `gsd_*` tools, not by hand-edited checkboxes.
+- [ ] `KNOWLEDGE.md` and `DECISIONS.md` have been updated if anything notable was learned.
+- [ ] Background processes are not orphaned.
+- [ ] A cold-read of `STATE.md` + `continue.md` + latest summary would produce the right next action.
+
+</success_criteria>

package/src/resources/skills/observability/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: observability
+description: Add agent-first observability to code — structured logs, health endpoints, failure-state persistence, and explicit failure modes — so the next agent hitting a problem at 3am has the signals it needs to diagnose. Use when asked to "add logging", "add observability", "add metrics", "debug later", "make this observable", or when building/refactoring a subsystem that will run unattended (auto-mode engine, background jobs, servers, watchers). Operationalizes VISION.md's "agent-first observability" principle.
+---
+
+<objective>
+Instrument code so that a cold-start agent can understand what happened by reading signals, not by rerunning with extra logging. The deliverable is a set of specific instrumentation additions: structured logs at decision points, health/status surfaces for long-running processes, persisted failure state, and explicit failure modes that don't get swallowed.
+</objective>
+
+<context>
+GSD-2's `VISION.md` lists "agent-first observability" as a principle, and the system prompt calls it out: "A future version of you will land in this codebase with no memory… you add observability because you're the one who'll need it at 3am." GSD-2 already exemplifies this — `activity/*.jsonl`, `journal/*.jsonl`, `metrics.json`, `doctor-history.jsonl` — but new code doesn't get that treatment automatically.
+
+This skill is the thinking process for adding it. Not "add logs everywhere" — add the *right* signals at the *right* decision points.
+
+Invocation points:
+- Building auto-mode-style code (loops, dispatch, guards, retries)
+- Adding a background job, watcher, or scheduled task
+- Writing a server or long-running process
+- Refactoring a subsystem that has been hard to debug
+- Addressing a production bug where "we had no visibility" surfaced
+</context>
+
+<core_principle>
+**LOG DECISIONS, NOT ACTIVITY.** "Entering function X" is noise. "Dispatched unit `slice/S02` after guard check passed because `status=pending`" is signal. Every log line should answer a question a future debugger will ask.
+
+**FAIL LOUDLY AND PERSIST THE REASON.** Silent `try/catch` that returns `undefined` is an anti-pattern. If something fails, the failure state needs to be somewhere a fresh agent can find it — a JSONL, a status file, a health endpoint.
+
+**OBSERVABILITY IS NOT FREE.** Every log allocation, every metric, every health check costs CPU and disk. Add only what you would actually read.
+</core_principle>
+
+<process>
+
+## Step 1: Map the failure modes
+
+Before instrumenting, list what can go wrong:
+
+1. **What inputs could be invalid?** External API responses, user-submitted data, filesystem state, env vars.
+2. **What external dependencies could fail?** Network, DB, child processes, filesystem permissions.
+3. **What internal invariants could break?** State transitions, lock acquisition, concurrency assumptions.
+4. **What silent corruption is possible?** Truncated writes, partial transactions, stale caches.
+
+This map tells you where to instrument. Don't instrument uniformly — instrument at the decision points where these failures would manifest.
+
+## Step 2: Structured logs at decision points
+
+For each decision the code makes that could plausibly go wrong later:
+
+- **What decision?** ("Dispatching unit X", "Retrying with backoff", "Skipping validation because flag set")
+- **Why?** ("status=pending", "previous attempt exit=1", "--dev flag set")
+- **What would a future debugger want to know?** (The values that drove the choice.)
+
+Format:
+
+```ts
+log.info({
+  event: "unit-dispatched",
+  unitType: "slice",
+  unitId: "S02",
+  reason: "pending",
+  attempt: 1,
+  flowId,
+});
+```
+
+Use the project's existing logger if one exists. In gsd-2, follow the patterns in `src/resources/extensions/gsd/activity-log.ts` and `src/resources/extensions/gsd/journal.ts` — structured JSONL, one event per line, with `ts`, `event`, and domain-specific fields.
+
+Avoid:
+- `console.log("here")` — what does "here" mean in six months?
+- Logging secrets, tokens, or PII — ever.
+- Formatting structured data into a prose string — it can't be grepped or filtered.
+
+## Step 3: Persist failure state
+
+When something fails in a way the caller can't immediately handle, write the failure state to disk:
+
+```ts
+await writeAtomically(
+  resolve(".gsd/runtime/last-error.json"),
+  JSON.stringify({
+    ts: new Date().toISOString(),
+    phase: "execute",
+    unitId,
+    error: { message, stack, code },
+    retryCount,
+  })
+);
+```
+
+A fresh agent reading `.gsd/runtime/` sees what happened last, what was retried, and where the process stopped. Pattern exists already in gsd-2 — reuse the `atomic-write.ts` helpers and the `.gsd/runtime/` and `.gsd/forensics/` directories.
+
+## Step 4: Health and status surfaces
+
+For long-running processes:
+
+- **Health endpoint** (HTTP server) or **status file** (CLI tool). Cheap to call, no side effects. Returns current state: `{status: "healthy" | "degraded" | "down", ...diagnostics}`.
+- **Digest view** — a small representation of recent work. In gsd-2, this is `STATE.md` and the health widget. In a server, it's `/internal/status` with last 10 request summaries.
+- **Minimal metrics** — counters for the 3–5 things that matter (requests, errors, active jobs). Not everything — just what drives alerts.
+
+Don't build a metrics empire. Build exactly what you'd check at 3am.
+
+## Step 5: Explicit failure modes
+
+Replace silent handling with explicit:
+
+```ts
+// Bad
+try {
+  return await db.getUser(id);
+} catch {
+  return null;
+}
+
+// Good
+try {
+  return await db.getUser(id);
+} catch (err) {
+  log.error({ event: "db-getuser-failed", userId: id, err: serializeError(err) });
+  throw new DatabaseError("Failed to load user", { cause: err, userId: id });
+}
+```
+
+The caller now knows the failure happened, gets an error type it can branch on, and a log line exists for forensics.
+
+## Step 6: Remove the scaffolding
+
+Before shipping, cull the ad-hoc instrumentation you used while debugging. Keep only:
+- Decision-point logs that a future agent would use
+- Persistent failure state
+- Health/status surfaces
+- Explicit failure modes
+
+Drop:
+- Temporary `console.log` debug lines
+- Spammy per-iteration logs that no one will read
+- Metrics that were "might be useful someday"
+
+The system prompt says it plainly: "Remove noisy one-off instrumentation before finishing unless it provides durable diagnostic value."
+
+## Step 7: Verify the signals work
+
+Pick one plausible failure mode from Step 1 and simulate it (inject an error, point at a missing file, break a dependency). Confirm:
+
+1. The failure produced a log line a cold-start agent could understand.
+2. The failure state persisted somewhere durable.
+3. The health surface reflects the degraded state.
+4. Nothing was swallowed silently.
+
+If any signal is missing, add it — that's the gap this skill exists to catch.
+
+</process>
+
+<anti_patterns>
+
+- **Uniform logging.** Logging every function entry/exit buries signal in noise.
+- **Prose logs.** `"Processing user 42 now"` vs `{event: "user-process-start", userId: 42}` — the latter is queryable, the former is not.
+- **Silent swallowing.** `catch {}` or `catch (err) { /* ignore */ }` without a log is a deferred production incident.
+- **Metrics empire.** 200 Prometheus metrics nobody reads. Ship 5 that drive alerts.
+- **Logging secrets.** API keys, tokens, passwords, full request bodies with PII — never.
+- **"I'll add logging when it breaks."** By then you don't have the signal. Instrument now.
+- **Over-instrumenting hot paths.** Logging inside a tight loop kills performance. Sample or aggregate.
+
+</anti_patterns>
+
+<success_criteria>
+
+- [ ] Failure modes were listed before instrumenting.
+- [ ] Logs are at decision points, structured, and contain the driving values.
+- [ ] Failure state is persisted to a known location (`.gsd/runtime/`, `/var/log/`, a status file).
+- [ ] Long-running processes expose a health or status surface.
+- [ ] No silent `try/catch` swallowing errors.
+- [ ] Ad-hoc debug instrumentation was removed.
+- [ ] One plausible failure was simulated and the signals were confirmed to reach a fresh reader.
+
+</success_criteria>