kit-debug-prod
Skill6 starsChanged 27 days agoMITView on GitHub
Investigate production bugs using logs, traces, error trackers, and metrics. Use when the user reports errors, user/session/trace IDs, timeframes, or status codes. Requires connected tools and/or a team `wire-observability.md`.
- Reads credentials
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- rules/AGENTS.mdAGENTS.md
- kit-audit-metricsSkill
- kit-audit-skillsSkill
- kit-capture-lessonSkill
- kit-challenge-designSkill
- kit-check-blastSkill
- kit-create-prSkill
- kit-debate-decision-treeSkill
- kit-decisionsSkill
- kit-evolveSkill
- kit-explainSkill
- kit-learn-repoSkill
- kit-minimizeSkill
- kit-optimize-contextSkill
- kit-planSkill
- kit-proveSkill
- kit-reviewSkill
- kit-strip-diffSkill
- kit-triage-commentsSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Before querying, look for team wiring next to this skill or in the consuming repo:
- Distinctive: line 19
If present, read it for: product/service log filters, cloud projects, trace attribute names, default error-tracker project, MCP endpoints, …
- Distinctive: line 21
If absent: ask which sources are available, or proceed only with tools already connected — and say what you could not check.
- Distinctive: line 34
Use what exists; skip the rest.
- Distinctive: line 69
Always apply the product/service filter from the team wiring file on every query.
- Distinctive: line 101
Prefer MCP OAuth over pasting tokens into commands.
- Distinctive: line 132
No employer-specific project IDs or hostnames in this skill file — those belong in the team wiring file.
- Very specific: line 133
If proof is incomplete, say unproven (pair with kit-prove when claiming a fix).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debug Prod
READ-ONLY unless the user explicitly asks to mutate (close issues, change flags, etc.).
Team wiring (wire-observability.md)
Before querying, look for team wiring next to this skill or in the consuming repo:
wire-observability.mdreferences/wire-observability.md- host-specific notes the user points to
If present, read it for: product/service log filters, cloud projects, trace attribute names, default error-tracker project, MCP endpoints, and credential locations (never paste secrets into chat).
If absent: ask which sources are available, or proceed only with tools already connected — and say what you could not check.
See references/wire-observability.example.md for a template.
Triggers
- Production bug / error, status codes (403, 500, …)
- User ID, session ID, trace ID, domain / tenant
- Timeframe (“last 2 hours”, “yesterday”)
- Links to logs, traces, or error-tracker issues
Data sources (adapters)
Use what exists; skip the rest. Prefer the team’s primary backend source + one corroborating source.
| Category | Typical tools | Use for |
| AI / LLM traces | Langfuse CLI, host traces UI | Tool calls, model I/O, AI pipeline errors |
| Backend logs | Cloud logging CLI (e.g. gcloud logging), Datadog, … | API errors, request logs |
| Distributed traces | Cloud Trace, Jaeger, Tempo, … | Latency, span waterfall |
| Error tracker | Sentry MCP/UI, similar | Unhandled exceptions, stack traces |
| Tickets | Jira / Linear MCP | Existing bugs, severity |
| Product analytics | Mixpanel / Amplitude MCP | Scope, feature usage around the incident |
| Metrics | Prometheus/Grafana MCP | Rates, saturation, alerts |
Names in this table are adapter examples. When you recommend one to a user, live-check it (kit-evidence). A row here is not that check.
Investigation flow
Always cross-reference ≥2 sources unless the user names a single tool only.
- Extract context — ids, timeframe, error pattern, environment (prod/staging).
- Query in parallel — traces/logs + error tracker (and others as relevant).
- Cross-reference — same user/tenant + overlapping timestamps.
- Quantify — isolated (1 user) vs widespread (many).
Cross-reference sketch
1. Traces → error → user_id, timestamp, message
2. Logs → same id/domain near that timestamp
3. Distributed trace → waterfall / latency (if perf-related)
4. Traces/logs → same error pattern for other users?
5. Error tracker → related frontend/unhandled exceptionsLogs (generic)
Always apply the product/service filter from the team wiring file on every query.
# Example shape (GCP); replace with your provider
gcloud logging read '<PRODUCT_FILTER> AND <YOUR_FILTERS>' \
--project=<CLOUD_PROJECT> \
--limit=50 \
--format=json \
--freshness=<TIME>Freshness examples: 4h, 24h, 48h, 7d. Re-auth if the CLI says credentials expired.
Patterns
| Signal | Likely direction |
| Auth / forbidden | Permission, session, token |
| Timeouts | Dependency / slow upstream |
| Quota / limit | Plan or rate limit |
| Client validation | Bad input / stale client |
| One user only | Config, cache, session, tenancy |
| Many users | Code bug or infra |
| One feature | Recent deploy / flag |
Error trackers
Unhandled exceptions usually land in the tracker; handled errors often appear only as HTTP failures in logs. Org/project slugs come from the team wiring file. On 403: ask for access — do not invent data.
Credentials
- Load secrets from env /
.envfiles the user already uses — never echo secret values into the transcript. - Prefer MCP OAuth over pasting tokens into commands.
Output
## Investigation Summary
**Context:** User / tenant, environment, timeframe
| Source | Finding |
|--------|---------|
| … | … |
**Root cause:** (High/Med/Low confidence) …
**Scope:** N users / isolated
**Immediate relief:** 1. … 2. …
**Suggested fix:** …
**Unproven / not checked:** …Troubleshooting
| Issue | Try |
| No log hits | Widen freshness; verify product filter |
| Auth expired | Re-login for that CLI/MCP |
| Huge CLI output | Write to a file, then grep |
| Tracker 403 | Request org/project access |
Constraints
- No employer-specific project IDs or hostnames in this skill file — those belong in the team wiring file.
- If proof is incomplete, say unproven (pair with
kit-provewhen claiming a fix).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

