Obs Check — Observability Enforcement

Precedence in the overall system: SEC → TDD → ARCH/TYPE → OBS-1 (BLOCK) → OBS-2 through OBS-5.

---

Rules

OBS-1 — No Empty Catch Blocks

Severity: BLOCK | Languages: * | Source: CCC

What it prohibits: Catch blocks (or equivalent error handling constructs) that swallow errors without any logging, re-throwing, or recovery action.

Prohibited patterns:

// TypeScript/JavaScript
try { ... } catch (e) {}
try { ... } catch (e) { /* TODO */ }
try { ... } catch (e) { return null; }  // null return with no log

# Python
try: ...
except Exception: pass
except Exception: ...  # ellipsis

# Go (result ignored)
if err != nil { }  // empty block
_ = err  // explicitly discarded without log

// Rust
if let Err(_) = result { }  // empty block
let _ = result;  // discarded result without log

Exemptions:

• catch (e) { return defaultValue; } where defaultValue is semantically correct AND a comment explains the intentional fallback
• Top-level global error handlers that transform errors before logging elsewhere
• Legitimate _ discards in Go/Rust with a comment explaining why

Detection:

1. Grep for catch blocks with empty bodies or bodies containing only comments
2. Grep for Python except blocks containing only pass or ...
3. Grep for Go if err != nil with empty block body
4. Grep for Rust let _ = or if let Err(_) with empty block
5. For each match: check if the block contains at least one log, logger, console, fmt., panic, return Err, throw, or raise call

agent_action:

1. Cite: OBS-1 (BLOCK): Empty catch block at {file}:{line} — error '{exception_type}' is silently swallowed.
2. Show the catch block
3. Required action — choose the appropriate pattern:

   // Minimum: log + rethrow (preserve original error context)
   } catch (error) {
     logger.error({ err: error, context: 'operationName' }, 'Operation failed');
     throw error;  // or throw new AppError('descriptive message', { cause: error })
   }
   

4. If the error is intentionally recoverable: require a comment and log at WARN level
5. If --fix: add a structured log call and rethrow — DO NOT add return null as a default fix without explicit user confirmation

Bypass prohibition: "I'll add logging later", "it's a known ignorable error" → Refuse. Cite OBS-1. An ignorable error must be documented with a comment AND logged at DEBUG level so it can be correlated if it later causes issues.

---

OBS-2 — Structured Logging with Correlation IDs

Severity: WARN | Languages: * | Source: CCC

What it prohibits: Unstructured log statements (plain string concatenation) in production code paths, and log statements missing a correlation/request ID. Unstructured logs cannot be reliably parsed, queried, or correlated across distributed services.

Prohibited:

console.log("User " + userId + " not found");
console.error("Error: " + error.message);

Required:

logger.warn({ userId, requestId: ctx.requestId }, "User not found");
logger.error({ err: error, requestId: ctx.requestId, userId }, "User lookup failed");

Structured logging libraries by language:

Language	Recommended	Minimum
TypeScript/JavaScript	pino, winston (JSON mode)	console.log with JSON.stringify object
Python	structlog, loguru (structured)	logging.warning with extra={}
Go	slog (stdlib ≥1.21), zerolog, zap	log.Printf is insufficient
Rust	tracing crate with JSON subscriber	log crate (unstructured — insufficient)

Detection:

1. Grep for console.log(, console.error(, console.warn( in non-test source files
2. Grep for print(f", logging.info(" (bare string), log.Printf( in non-test files
3. For each match: check if the argument is a structured object (contains key-value pairs)
4. Check if any log call passes a requestId, correlationId, traceId, or ctx

agent_action:

1. Cite: OBS-2 (WARN): Unstructured log at {file}:{line}. Use structured logging with correlation ID.
2. Show the current log call
3. Propose the structured equivalent with correlation context
4. If --fix: convert console.log("message" + var) to logger.info({ var, requestId: ctx.requestId }, "message") — but only if a logger instance or ctx is already in scope

---

OBS-3 — HTTP Endpoints Must Be Traced

Severity: WARN | Languages: typescript, javascript, python, go | Source: CCC

What it prohibits: HTTP endpoint handlers that do not propagate or initiate a trace span. Without tracing, distributed request flows become impossible to debug when they span multiple services.

Required (one of these patterns must be present):

• OpenTelemetry span creation: tracer.startSpan(...), @trace, span = tracer.start_as_current_span(...)
• Framework middleware that auto-instruments (e.g., @opentelemetry/instrumentation-express) — if middleware is verified at the application level, per-handler tracing is not required
• Manual trace header propagation: reading and forwarding traceparent / X-Request-Id

Detection:

1. Identify HTTP handler functions (look for route registration patterns: app.get(, app.post(, @app.route(, func(w http.ResponseWriter, etc.)
2. For each handler: check if the handler body or its middleware chain contains a tracing call or the framework has a tracing middleware installed
3. Flag handlers with no trace context

agent_action:

1. Cite: OBS-3 (WARN): Endpoint '{method} {path}' at {file}:{line} has no trace span.
2. Check if a global tracing middleware is installed at the application root
3. If middleware handles it: mark as passing (document the middleware location)
4. If not: propose adding OpenTelemetry instrumentation
5. If --fix: add the minimal @opentelemetry/instrumentation-{framework} setup reference — do not add manual spans when auto-instrumentation is available

---

OBS-4 — Services Must Expose a Health Check Endpoint

Severity: WARN | Languages: typescript, javascript, python, go | Source: CCC

What it requires: HTTP services must expose at least one health check endpoint that returns a machine-readable status. Health checks are required by Kubernetes liveness/readiness probes, load balancers, and on-call tooling.

Acceptable patterns:

• GET /health → { "status": "ok" } (HTTP 200)
• GET /healthz → { "status": "ok" } (HTTP 200)
• GET /ready → status and dependency check (HTTP 200 / 503)
• GET /_health (common in internal APIs)

Detection:

1. Grep route definitions for /health, /healthz, /ready, /_health
2. If none found: flag as OBS-4

agent_action:

1. Cite: OBS-4 (WARN): No health check endpoint found in {file}. HTTP services must expose /health or /healthz.
2. Propose: add a minimal health handler:

   app.get('/health', (req, res) => res.json({ status: 'ok' }));
   

3. For services with dependencies (DB, cache): recommend a liveness vs readiness split
4. If --fix: add the minimal health endpoint stub

---

OBS-5 — Error Messages Must Be Actionable

Severity: INFO | Languages: * | Source: CCC

What it prohibits: Error messages thrown or returned to callers that contain no actionable information — messages that require reading source code to understand what went wrong and how to fix it.

Prohibited patterns:

throw new Error("Something went wrong");
throw new Error("Internal error");
throw new Error("Failed");
return { error: "Error occurred" };

Required patterns:

throw new Error(`User ${userId} not found in tenant ${tenantId}`);
throw new AppError("PAYMENT_DECLINED", {
  code: "INSUFFICIENT_FUNDS",
  hint: "Verify the card has available balance before retrying",
  requestId: ctx.requestId,
});

Detection:

1. Grep for throw new Error(" patterns where the message is ≤ 20 characters or matches generic phrases: "Something went wrong", "Internal error", "Failed", "Error occurred", "An error occurred"
2. Grep for returned error objects with only a generic message field

agent_action:

1. Report: OBS-5 (INFO): Vague error message at {file}:{line}: '{message}'.
2. Propose: include the relevant context: what operation failed, what values were involved, what the caller should do
3. If --fix: replace the vague message with a template that includes the key variables (file and line context); require human to fill in specific values

---

Report schema: see skills/conductor/shared-contracts.md.