add-observability

Files (3)

• SKILL.md
• boundary-recipes.md · references/
• logger-bootstrap.md · references/

SKILL.md (first lines)

> **Tool mapping (OpenCode):** This skill uses:
> - `question` tool for user prompts (not `AskUserQuestion`)
> - `task` tool for subagents (not `Agent` or `Task` subagent syntax)
> - `skill({ name: "..." })` to load other skills (not `Skill(skill="...", args="...")`)
> - `codegraph_explore`, `codegraph_search`, `codegraph_context` for codebase exploration (preferred)
> - `todowrite` for phase/progress tracking
> - `grep`, `glob`, `read`, `bash` as fallback when `.codegraph/` not initialized
>
> **Context rule:** This skill supersedes any prior skill instructions. Follow ONLY these instructions now. Read the user's goal and any mode/include/skip from the conversation context.

Read `mode=`, `include=`, `skip=` from conversation context. Default to production if not specified.

# Code Add Observability

Add evidence to integration boundaries *before* something goes silent. The output of this skill is read by `fix-bug` later — its first message reports endpoints, env vars, and **log/observation locations**. If the locations don't exist, `fix-bug` is reduced to hypothesis-testing.

A "boundary" is any place control or data leaves the local module: outbound HTTP, IPC send/receive, queue enqueue/handler, file write, env-var injection into a child process, hook invocation, webhook receiver, MCP tool entry, `spawn`/`exec`. Pure functions are not boundaries. Logs at non-boundaries are noise.

---

## Phase 1 — Scope

Use `todowrite` to mark this phase as in_progress.

Determine mode:

- **Targeted** — user named a feature, file, route, or integration. Scope = that surface plus its direct dispatch/receive sites.
- **Sweep** — invoked after a feature ships (often after feature addition). Scope = `git diff <base>..HEAD` filtered to source files.

If mode is ambiguous, ask once via `question` tool:

```
question({
  questions: [{
    header: "Scope mode",
    question: "Targeted (which file/feature?) or sweep over the current branch's diff?",
    options: [
      { label: "Targeted", description: "Name a specific file, route, or integration" },
      { label: "Sweep", description: "Sweep git diff of current branch" }
    ]
  }]
})
```

**Exit condition:** you can list the file paths in scope as a bulleted list before moving on.

---

## Phase 2 — Logger discovery

Use `todowrite` to mark this phase as in_progress.

Detect first; install last. Check in this order, stop at the first hit:

1. **Imported logger** — use `codegraph_search` or grep scoped files and shared `lib/`/`src/utils/` for `from ['"]pino`, `from ['"]winston`, `from ['"]electron-log`, `import debug from ['"]debug`, `from ['"]bunyan`, `from ['"]@logtape`, `loglevel`. If `.codegraph/` not initialized, fall back to `grep`.
2. **Project-local wrapper** — `logger.ts`, `log.ts`, `lib/logger.*`, `src/log/*`. If found, read its API and conform.
3. **Package manifest** — `package.json` `dependencies`/`devDependencies` for any of the above.
4. **None found** — load [`references/logger-bootstrap.md`](references/logger-bootstrap.md) and follow its decision tree (zero-dep fallback vs. propose installing `pino`).

**Before installing anything, ask the user.** Frame via `question` tool:

```
question({
  questions: [{
    header: "No logger detected",
    question: "Choose logging approach:",
    options: [
      { label: "Zero-dep console fallback", description: "console-based logger with LOG_LEVEL env gate (no install)" },
      { label: "Install pino", description: "Tiny, fast, structured (npm install required)" },
      { label: "Point to existing logger", description: "I'll tell you which logger I missed" }
    ]
  }]
})
```

**Exit condition:** you have a single `log.{debug,info,warn,error}` API to call, and you know its import path. Write that import path down — every recipe in Phase 4 reuses it.

---

## Phase 3 — Boundary enumeration

Use `todowrite` to mark this phase as in_progress.

**Thinking frame:** a boundary is any place control or data leaves this module's process or address space — outbound network, IPC, spawned process, file system, queue broker, hook handoff. If a future call site fits that test but isn't in the list below, treat it as a boundary anyway.

For each in-scope file, list every boundary call site as `path:line — <type>`. Use `codegraph_explore` first to identify the structure. If `.codegraph/` not initialized, fall back to `read` + `grep`.

Boundary types:

- **outbound-http** — `fetch`, `axios`, `got`, `undici.request`, route-internal `$fetch`
- **inbound-http** — route handlers, webhook receivers, server-fn entrypoints
- **ipc-send / ipc-recv** — Electron `ipcMain.handle`, `ipcRenderer.invoke`, `webContents.send`
- **spawn** — `spawn`, `exec`, `execFile`, `fork`, `pty.spawn`
- **env-injection** — places that build a `env: {…}` object passed to a spawn
- **file-write** — `fs.writeFile`, `fs.appendFile`, settings/config writers
- **queue** — `enqueue(`, `.add(`, `.publish(`, worker `process(`/`consume(`
- **hook** — hook scripts, framework lifecycle hooks invoked by external systems
- **mcp** — MCP server tool handlers
- **silent-failure** — `|| true`, empty `catch {}`, `>/dev/null 2>&1`, `.catch(() => {})` on the dispatch path

Show this list to the user and confirm before instrumenting. **Exit condition:** confirmed list. If >20 boundaries, group by file and ask via `question` tool which to prioritize — do not bulk-edit a sprawling list without acknowledgment.

---

## Phase 4 — Instrument

Use `todowrite` to mark this phase as in_progress.

**MANDATORY READ — [`references/boundary-recipes.md`](references/boundary-recipes.md)** before editing. It maps each boundary type to a precise instrumentation recipe (event name, fields, level, where the catch goes). Do NOT load it during Phase 1–3.

Apply recipes one boundary at a time. After each file, run type-check (`tsc --noEmit` or project equivalent) before moving to the next. Do not bulk-edit then verify at the end — a typo in the logger import propagates silently.

**If type-check fails:** revert that file's edits, re-read the failing import (logger path, type of `err` in catch, payload field shape), and reapply with a smaller diff — one boundary, not the whole file. Do not proceed to the next file with red type errors; cascading errors mask the real cause.

**Silent-failure handling** (the most error-prone case):

| Pattern | Replacement |
|---|---|
| `await foo() \|\| true` (in shell) | `await foo() \|\| { log.error({event:"foo.failed", err:$?}); true; }` — preserves swallow, adds evidence |

From Acauhi99/opencode-agent-system, MIT.

More from Acauhi99/opencode-agent-system