en-debug

Helper resolution. All references/X and bin/Y paths in this skill resolve relative to $ENSEMBLE_ROOT — the install root (skill at $ENSEMBLE_ROOT/skills/<name>/, shared helpers at $ENSEMBLE_ROOT/{references,bin}/). Compute once at start: $ENSEMBLE_ROOT env var if set; otherwise $(realpath "$(dirname <this-SKILL.md>)/../.."). Fail loudly if $ENSEMBLE_ROOT/references/host-detect.md does not resolve — that indicates a partial install (run /en-setup to repair).

/en-debug

Telemetry-driven debugging. Takes an error message, trace ID, or log excerpt; reads logs from the project's configured source; correlates entries; surfaces a hypothesis pointing at specific source code.

Read-only by default. This skill never writes code, never commits, never pushes. Its output is a hypothesis the user (or a follow-up /en-build) acts on.

Argument shapes

Argument	Mode
<trace-id> (e.g., 4bf92f3577b34da6a3ce929d0e0e4736)	Trace mode — pull all log lines with this trace_id; reconstruct the request lifecycle
<request-id>	Request mode — same but keyed on request_id
"<error message>"	Error mode — full-text search recent logs for the message; cluster by trace
<file>:<line>	Location mode — read recent logs that emitted from this code path
(none)	Tail mode — read the last 200 log lines; ask the user which event is interesting

Process

1. Detect host. Source $ENSEMBLE_ROOT/references/host-detect.md.
2. Recursion guard. If ENSEMBLE_PEER_REVIEW=true, exit.
3. Read observability config from .ensemble/config.local.yaml observability: block.
   • log_source — stdout (read from stdin), file (read log_path), or command (run log_command).
   • If unconfigured, prompt the user for log location and exit.
4. Validate log_command is allowlisted if used. Default allowlist: docker, kubectl, journalctl, gh run view, gh run view --log, datadog-cli, aws logs, gcloud logging. Anything else requires explicit observability.allowed_log_commands entry.
5. Fetch logs. Per the configured source. Cap fetched lines at observability.max_log_lines (default 5000).
6. Parse logs. Per $ENSEMBLE_ROOT/references/observability-conventions.md — structured-JSON shape. If logs aren't structured JSON, surface a warning and fall back to plain-text correlation (less precise).
7. Correlate. Per the argument mode:
   • Trace mode — filter to entries where trace_id == arg; sort by timestamp; build a span timeline.
   • Request mode — same on request_id.
   • Error mode — full-text search msg/error.message; cluster matches by trace_id if present.
   • Location mode — match event field against the file path heuristically (e.g., event: auth.token_rotated ↔ src/auth/refresh.ts); fall back to span-name matching.
8. Identify the failing span. First entry with level: error or level: fatal in the correlated set is the source. Walk parent spans to find the entry point.
9. Map span → source. Per $ENSEMBLE_ROOT/references/observability-debug-mapping.md. Heuristic:
   • event field often matches a function name (auth.token_rotated → tokenRotated() in src/auth/).
   • error.stack (if present) gives the exact location.
   • Fallback: dispatch repo-research agent with the event name + error message; agent searches the codebase.
10. Surface a hypothesis. Format per $ENSEMBLE_ROOT/references/observability-hypothesis-format.md. Brief; cite the log line that anchors the conclusion.
11. Suggest next step. One of:
    • /en-build (write a fix, with the failing trace as a test fixture).
    • /en-resolve-pr (when the bug came from a reviewer comment).
    • /en-plan (when the fix is non-trivial).
    • /en-learn capture (when the bug exposes a recurring anti-pattern).

Output format

Hypothesis (confidence: 7/10)

  The error originates in src/auth/refresh.ts:42, where rotateRefreshToken
  fails to handle a null `user.email` returned by getUserById. The trace
  shows two earlier successful rotations on the same user_id; the third
  fired with a stale cache entry where the user's email had been removed.

Anchor log line:
  ts: 2026-05-04T10:13:42Z
  level: error
  event: auth.token_rotated
  error.type: TypeError
  error.message: "Cannot read property 'toLowerCase' of null"
  error.stack: "at Object.normalize (src/auth/refresh.ts:42:18) ..."
  trace_id: 4bf92f3577b34da6a3ce929d0e0e4736
  user_id: u_482

Span timeline (3 entries with this trace_id):
  10:13:41.881  service.boundary  POST /api/auth/refresh         info
  10:13:42.012  cache.user_lookup hit, stale=true                debug
  10:13:42.013  auth.token_rotated TypeError: ...                error  ← source

Suggested next step:
  /en-build — write a fix for src/auth/refresh.ts:42 that handles
  null user.email + invalidate cache on stale read. Use this trace
  as a test fixture (tests/fixtures/refresh-null-email-trace.json).

Confidence scoring

/en-debug rates its hypothesis 1–10:

• 9–10 — direct match: error.stack pinpoints the file:line, structured logs corroborate.
• 7–8 — strong correlation via trace + event-field, no stack but plausible from code-search.
• 5–6 — reasonable hypothesis from log-text matching; not anchored in code yet.
• 3–4 — wide net; multiple plausible sources; user should narrow further.
• 1–2 — couldn't correlate; logs may be insufficient or unstructured.

Below 5, recommend the user re-run with a more specific argument (trace ID > error message).

When the project's logs aren't structured

If the configured logs don't match $ENSEMBLE_ROOT/references/observability-conventions.md (no JSON, no trace_id, no event), /en-debug:

1. Surfaces a warning: "Logs aren't structured per $ENSEMBLE_ROOT/references/observability-conventions.md. Correlation will be less precise."
2. Falls back to grep-style full-text search on the error message.
3. Uses timestamp clustering (events within 500ms) instead of trace/request correlation.
4. Caps confidence at 6/10 — without structured fields, the hypothesis is fundamentally less reliable.
5. Suggests structured logging as a follow-up: "Consider adopting $ENSEMBLE_ROOT/references/observability-conventions.md so future debug sessions can be more precise."

What this skill never does

• Never writes code. Even when the hypothesis is high-confidence, fixing it is /en-build's job.
• Never invokes log commands outside the allowlist. Prompt-injection defense — a malicious log message can't trick the skill into running arbitrary shell.
• Never sends logs to external services. Correlation runs locally on what the configured source returned.
• Never reads production secrets if the log includes them. The hypothesis section quotes log fields verbatim except anything matching common secret patterns (per $ENSEMBLE_ROOT/references/secret-patterns.md); those are redacted to [REDACTED].
• Never auto-files a TD or learning without user confirmation.

Reference files

• $ENSEMBLE_ROOT/references/observability-conventions.md — log/trace shape contract
• $ENSEMBLE_ROOT/references/observability-debug-mapping.md — span-name → source-code heuristics
• $ENSEMBLE_ROOT/references/observability-hypothesis-format.md — output template
• $ENSEMBLE_ROOT/references/secret-patterns.md — redaction patterns for logged secrets
• $ENSEMBLE_ROOT/references/host-detect.md

Failure protocol

Failure	Behavior
observability: block missing in config	Prompt user; exit non-zero
log_command not in allowlist	Refuse; print allowlist; exit non-zero
log_path doesn't exist	Surface; exit non-zero
Logs are present but no entries match the trace ID	Surface "no matches"; suggest broader query
Correlation produces ambiguous result (multiple plausible sources)	Surface all candidates with confidences; ask user to disambiguate
repo-research agent fails	Continue with log-only hypothesis; mark confidence ≤ 6