tsuga

Turns a raw incident dump of Slack threads, incident reports, pull requests and Tsuga CLI output into a populated incident-history archive, one folder per incident, each with a SUMMARY.md carrying a validated diagnostic path and a metadata.json for snapshot filtering. Use when bootstrapping incident-history from scratch for a new deployment, refreshing an existing archive with new incidents, or reformatting an incident tracker's export into the shape an investigation runtime expects. Inputs are per-incident directories of raw material; outputs are the incident folders plus an inventory CSV. This is a one-shot build procedure, not an investigation skill.

Turns a live Tsuga account, a codebase list and ambient docs into a populated knowledge-company tree: company-level general and telemetry knowledge, per-team knowledge files, and per-service dossiers carrying ready-to-run `tsuga` commands discovered from live data rather than a prescribed list. Use when bootstrapping knowledge-company from scratch for a new company, refreshing it after a major service taxonomy change, or after a CLI change that invalidates the existing ready-to-run commands. Requires Tsuga CLI access and a populated incident-history archive to cross-link against. This is a one-shot build procedure, not an investigation skill.

Lints Tsuga skill bundles for the mechanical violations a human reviewer should not have to catch, and reports pass, warn or fail per check. Use when checking frontmatter and description length, SKILL.md body length, forbidden Tsuga CLI patterns, reference-directory depth, bundle size, the structure of generated incident-history or knowledge-company archives, sampled read-only command shape, or whether a skill tree is ready for review. A passing lint is necessary, not sufficient: it does not judge scope, narrative quality or whether the examples are useful.

Establishes what changed and what actually shipped, using the GitHub CLI for workflow runs, pull requests, commits, releases, deployments and issues, paired with local git for exact file diffs. Use to correlate an incident window with recent changes, find which pull requests touched a service path, verify whether a merged pull request reached an environment, inspect a commit or its diff, list releases and tags, check a workflow run or a failed job's logs, and establish what shipped before a regression started. Read-only by default: any mutation needs explicit confirmation.

Runs a full incident investigation: classifies the incident mode, anchors on the monitor that fired, spawns parallel telemetry, change-correlation, codebase-grep and challenger branches, holds hypotheses behind evidence gates, and publishes an investigation record and proofs dashboard. Use for active-incident investigation, post-incident RCA, or recurring-degradation triage, when a monitor fires, a customer reports slow, errored or missing telemetry, or an incident is declared. It enforces a strict time discipline so no evidence postdating the declaration reaches the verdict. For a quick single-service health check with no RCA, use tsuga-investigate-service-health instead.

Supplies per-technology reference pages for 47 technologies, fetched by exact path: an overview for every one, plus the exact Tsuga metric names, incident shapes, derived signals and log patterns where that technology has them. Use before composing any Tsuga aggregation, logs or traces query, and when an incident scope, error log or monitor name mentions a covered technology or a classic symptom such as OOMKilled, CrashLoopBackOff, connection pool, deadlock, queue lag, compaction, throttle, replication lag, cold start or 5xx. Covers databases, brokers, proxies and service mesh, the Kubernetes ecosystem, AWS and GCP services, and runtimes. Source-system metric names such as CloudWatch CPUUtilization do not work in Tsuga: use the `tsuga_metric_name` column of a bundle's metrics page.

Writes, reviews and debugs OpenTelemetry Collector configuration, enforcing processor ordering, receiver exposure and OTTL correctness, and gating every config change behind confirmation. Use when Collector YAML, Helm values, Kubernetes manifests, existing Collectors, OTLP exporters, receiver binding or exposure, pipeline topology, processors, OTTL expressions, transform, filter or routing processors, redaction, enrichment, batching, memory limiting, structured log parsing, Collector-to-Tsuga export problems, configuration review, rollout planning, or telemetry missing after a Collector rollout need attention. For application SDK code use otel-instrumentation instead.

Writes, fixes and audits application OpenTelemetry SDK setup, inferring the runtime, inspecting what is already wired, and gating every code change behind confirmation. Use when adding, fixing, generating or auditing OTel SDK setup in C++, .NET, Go, Java or JVM, Node.js or TypeScript, PHP, Python, Ruby, Rust, or an unknown runtime, and for automatic instrumentation, custom spans, metrics, logs, log correlation, resource attributes, propagation, messaging, local testing, redaction, instrumentation audits or SDK snippets. For Collector YAML and pipelines use otel-collector; to decide which signal to emit in the first place use signal-choice-advisor.

Decides how to model an observation before any code is written: which OpenTelemetry signal to emit, which instrument to pick, what to name it against the semantic conventions, where the attribute belongs, and whether a proposed metric dimension is low-cardinality enough to ship. Use when choosing between a metric, span, structured log or resource attribute, between Counter, Histogram, UpDownCounter and Observable Gauge, or when someone describes something they want to observe without having decided how to instrument it. Advisory only and it never writes code: route the SDK implementation to otel-instrumentation.

Investigates where latency comes from: finds the peak window, ranks slow operations by percentile, separates sustained degradation from a transient spike, and attributes wall-clock time inside one trace. Use when asked about slow requests, high latency, latency spikes, p95 or p99 trace duration, slow spans, top slow operations, peak latency windows, span count by operation, downstream latency suspicion, which operations are slow for a service, or whether latency correlates with errors. Also covers per-trace drill-down (trace latency summary) and collapsing a large or repetitive trace (trace summarize). For error volume and error patterns, use tsuga-investigate-errors instead.

Audits Tsuga alerting configuration for coverage and routing gaps, separating exact service matches from glob, env, cluster and team-scoped coverage. Use when asked to check monitor coverage, services without monitors or SLOs, alerting gaps, notification routing, notification rules, silences, stale team references, PagerDuty or Slack destinations, teams without configured alerts, monitor ownership, monitor filters, log-error-pattern coverage, SLO alert coverage, active or inactive routing rules, coverage summaries or coverage percentages. This is a configuration audit, never live firing state. For reading or editing a single monitor, use tsuga-cli instead.

Audits the quality of telemetry Tsuga receives by reading the scheduled quality report first, then judging the defect classes no rule covers. Use when reviewing log structure, severity, or trace correlation; metric naming, units, temporality, instrument type, or cardinality; span naming, kind, status, links, or noisy spans; resource identity, source labels, or resource drift; quality-report rows and their examples; downstream metric usage; missing labels or malformed attributes; or a proposed metric rename or high-cardinality attribute drop. It assumes the telemetry arrives: if signals are missing, sparse or unlinked, use tsuga-debug-telemetry-ingestion first.

Designs, builds, validates and repairs Tsuga dashboards: picks widget types, verifies every query before embedding it, lays widgets out on the 12-column grid, and gates every mutation behind confirmation. Use when asked to create, update, delete or review a dashboard, add or fix a widget, correct a layout, build a monitoring view for a service, team, system, SLO, capacity, latency, throughput or error-rate question, or diagnose a widget that shows nothing. Also use to verify dashboard payloads, widget queries, graph schemas, normalizers, formulas, table grouping, time presets and layout rules. For ad-hoc querying without a dashboard, use tsuga-cli instead.

Drives the Tsuga CLI end to end: picks the command that answers a question, composes and corrects aggregation and search bodies, and carries the query-safety, output-parsing, ownership and evidence rules that `--help` and the product docs do not state. Use for Tsuga CLI commands and reading their output, TQL log, trace or RUM search, aggregation bodies, metric temporality math, resource lookup and CRUD planning, service ownership, quality reports, monitor or notification-rule context, retention and tag policies, ingestion keys, billing export and usage metering, Tsuga resources as Terraform, app URL shapes, translators from kubectl, aws, gcloud and az, docs lookup, and skeleton payloads. For authoring a dashboard use tsuga-build-dashboard, for alerting-coverage audits tsuga-audit-monitor-coverage, and for a full incident incident-investigation.

Compares a target group of spans against a baseline and returns the attribute values over-represented in the target, with support, lift and p-value. Use when the question is what distinguishes one group of spans from another: why these requests fail and those do not, what the slow requests have in common, what changed between two deployed versions, or which attribute explains a regression. Also use to investigate a version flagged as a faulty deployment, and to tune or read a contrast-set result. It ranks attributes, never volume or trend: for error counts use tsuga-investigate-errors and for latency distribution use tsuga-analyze-trace-latency.

Debugs telemetry that is not arriving: checks presence per signal, classifies the gap as service-not-visible, all-signals-missing, one-signal-missing, sparse, collector-path or propagation, and separates absence from breakage. Use when telemetry is missing, sparse, delayed or not visible in Tsuga, when verifying arrival after a deploy, when a service does not appear, when RUM events are absent from the Mobile tab, when OTLP endpoint, protocol or auth is suspect, when an exporter is aimed at the wrong intake, when a Collector accepts data that Tsuga never shows, or when spans on two sides of a call do not link. Use tsuga-audit-telemetry-quality instead once the data is arriving and the question is whether its shape is right.

Quantifies and explains a service's errors: confirms the count with an aggregation, clusters errors by structure, surfaces new and spiking patterns, and samples structure fields safely. Use when asked about service errors, error spikes, exception patterns, what is failing, new error patterns, anomalous error volume, dominant log error structures, service-specific error counts, error samples, error pattern increases, failed requests, exception clusters, affected files or targets, or whether log evidence supports an error hypothesis. For what separates failing spans from healthy ones use tsuga-contrast-sets, for latency use tsuga-analyze-trace-latency, and for a full multi-signal triage use tsuga-investigate-service-health.

Triages one named service across signals in parallel: registry snapshot, monitor inventory, error count, request rate, p95 latency, and error-pattern increases, then synthesizes them into a single verdict with evidence. Use during active incidents, on-call response, first-response triage, or any time someone asks what is wrong with a specific service, whether a service is healthy, or where to start on a degraded service. For a declared incident needing root-cause analysis, change correlation and a published investigation record, use incident-investigation instead.