| name | observability-harness |
| description | Add local-first observability for coding agents. Use when a repo needs logging conventions, request or correlation IDs, diagnostics, scripts/logs, scripts/diagnose, debugging docs, metrics/tracing guidance, or smoke-test diagnostics. |
Observability Harness
Purpose
Make runtime behavior inspectable through local logs, diagnostics, and documented debugging paths before adding heavy external platforms.
Use chrome-devtools-runtime-debugger for browser console, network, DOM, accessibility, Lighthouse, responsive, or performance investigation.
Use sprint-contract-observability for process observability: sprint contracts, evaluator rubrics, and task traces.
Inspect First
- logging utilities, request middleware, error handling, health checks, dev scripts, local runtime docs, tests, and production monitoring notes
Procedure
-
Define observability basics.
- Structured logs where appropriate.
- Request or correlation IDs for request-based systems.
- Standard error shape and debugging fields.
-
Add local diagnostics.
- Create or update
scripts/logs.
- Create or update
scripts/diagnose when repeatable diagnostics exist.
- Link diagnostics from
scripts/healthcheck when helpful.
- Link browser runtime debugging to
docs/observability/browser-debugging.md when Chrome DevTools MCP is relevant.
-
Document behavior.
docs/observability/logging.mddocs/observability/debugging.md- Metrics/tracing notes only when the repo uses them.
- Link sprint contract and evaluator rubric docs when process observability is configured.
-
Keep it boring.
- Prefer grep-able local logs before introducing external services.
- Do not add observability vendors without explicit need.
Validation
- Run log and diagnostic scripts when feasible.
- Confirm docs include expected log fields and local commands.
- Confirm failures produce actionable diagnostics.
Completion Criteria
- Agents can inspect local runtime behavior and trace a failing request or workflow.
