From ensemble
Reproduce a bug from telemetry. Reads structured logs from the configured source, correlates by trace_id / request_id / event field, surfaces a hypothesis with file:line and confidence 1-10. Read-only. Pairs with /en-resolve-pr (when reviewer comments reference a runtime error) and /en-build (when a test or QA run fails with a real-world trace). Trigger phrases: 'debug this trace', 'reproduce this error', 'walk this log', 'why did this fail in prod'.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ensemble:en-debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **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-dete...
Helper resolution. All
references/Xandbin/Ypaths 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_ROOTenv var if set; otherwise$(realpath "$(dirname <this-SKILL.md>)/../.."). Fail loudly if$ENSEMBLE_ROOT/references/host-detect.mddoes not resolve — that indicates a partial install (run/en-setupto repair).
/en-debugTelemetry-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 | 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 |
$ENSEMBLE_ROOT/references/host-detect.md.ENSEMBLE_PEER_REVIEW=true, exit..ensemble/config.local.yaml observability: block.
log_source — stdout (read from stdin), file (read log_path), or command (run log_command).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.observability.max_log_lines (default 5000).$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).trace_id == arg; sort by timestamp; build a span timeline.request_id.msg/error.message; cluster matches by trace_id if present.event field against the file path heuristically (e.g., event: auth.token_rotated ↔ src/auth/refresh.ts); fall back to span-name matching.level: error or level: fatal in the correlated set is the source. Walk parent spans to find the entry point.$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.repo-research agent with the event name + error message; agent searches the codebase.$ENSEMBLE_ROOT/references/observability-hypothesis-format.md. Brief; cite the log line that anchors the conclusion./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).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).
/en-debug rates its hypothesis 1–10:
error.stack pinpoints the file:line, structured logs corroborate.Below 5, recommend the user re-run with a more specific argument (trace ID > error message).
If the configured logs don't match $ENSEMBLE_ROOT/references/observability-conventions.md (no JSON, no trace_id, no event), /en-debug:
$ENSEMBLE_ROOT/references/observability-conventions.md. Correlation will be less precise."$ENSEMBLE_ROOT/references/observability-conventions.md so future debug sessions can be more precise."/en-build's job.$ENSEMBLE_ROOT/references/secret-patterns.md); those are redacted to [REDACTED].$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 | 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 |
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub manok4/ensemble --plugin ensemble