Skip to main content
StackNext rebuilds a deterministic diagnostic report from the current sample. The same report is available in the dashboard, stacknext diagnose, JSON export, the read-only MCP tools and the Agent Skill. Diagnostics never call a model, run SQL, read source files or change your code.

​
The six rules

These are conservative heuristics. They do not prove an ORM bug, a causal bottleneck, a retry policy problem or a shared error cause. Read the evidence, verification steps and limitations on each finding.
A finding is evidence, never a confirmed root cause. Verify it in the trace before you change code.
Diagnostics findings view listing error and warning findings with route, rule, status and evidence Diagnostics findings view listing error and warning findings with route, rule, status and evidence

​
Read a finding

A finding contains:
  • a deterministic diag- id for the current sample;
  • the rule, category, severity and status;
  • the affected route, time window and trace count;
  • a fingerprint of the normalized evidence;
  • bounded evidence such as slow-span contributors, trace occurrences, error occurrences, query shapes or Next.js phases;
  • verification steps and limitations;
  • a reference to a related trace when one is available.
Statuses mean:
  • possible — the pattern is consistent with a problem.
  • observed — the evidence was measured directly.
  • insufficient-evidence — the sample cannot support a conclusion.
Severity is separate from status. A high-severity finding still needs verification, and a capped report (maxFindings) is not a complete inventory.

​
CLI

The report includes the sample window, counts, notes and limitations. A finding id is deterministic for its evidence but is not a durable database key.

​
Dashboard and MCP

The dashboard /diagnostics page lists findings and /diagnostics/:id shows one finding with its evidence and related trace. In MCP clients:
  • stacknext_list_diagnostics filters by category, severity, status, rule, route, trace id, time, query and pagination.
  • stacknext_get_diagnostic returns one finding plus bounded evidence and a related trace reference.
get_trace also returns diagnostic references, but they are pointers. Call stacknext_get_diagnostic for the evidence. The MCP server is read-only and cannot create, acknowledge or delete findings.

​
What diagnostics cannot do

  • Execute SQL or EXPLAIN, inspect source code or recommend indexes.
  • Detect long-term anomalies or alert.
  • Call an LLM or external service.
  • Turn not-observed coverage into proof that a feature is broken.
  • Establish causality or statistical significance.