stats

Read-only, agent-callable observability over the ledgers dwarves-kit and its
neighbors (tide, tg-cleanup, learned-ledger) already write. The tool dir is
~/workspace/<owner>/dwarves-kit/lib/stats (run uv run stats <cmd>
there). Everything is read-only: the CLI never writes back to a source ledger; there
is no path through this skill that mutates anything.

Scope and triggers

Covers the ledgers stats reads: the dwarves-kit gate/proof/telemetry corpus, tide file-move state, tg-cleanup snapshots, the learning ledger. Additional trigger phrases: "understanding debt", "telemetry", "how much am I spending on tokens", "kit runs", "kit lane telemetry", "ledger status", "render the ledger", "ledger dashboard", "share this as an artifact" (mid-ledger-conversation), "is my debt over threshold", "propose a backlog row from the ledger state".

Drives the read-only stats CLI (dwarves-kit/lib/stats) and renders the result as EITHER an in-terminal reply (bot-reply-formatting, tables + bar-fills) or a shareable web Artifact, both from the same one query; stats anomalies is the feedback-loop path, PROPOSE-only (stages a cc-backlog candidate, never files a board row). READ-ONLY by hard contract over every source ledger, the CLI never writes back to a source ledger; the one exception is stats anomalies --propose, whose ONLY write is the gitignored cc-backlog staging buffer.

For ad-hoc SQL exploration, drive stats query/stats show directly; this skill is the rendered-answer path. There is no persistent TUI/app or daemon here, only an on-demand agent-driven query + render + propose.

One data path: always query via the stats CLI

Never re-derive a ledger reading by grepping ~/.local/state/dwarves-kit/logs/ or
tide's sqlite or tg-cleanup's json yourself , that is a second, divergent data
source and breaks the whole point of the lens (the understanding-gate work already reuses
lane-telemetry for the kit read; re-implementing it here would drift). Always go through stats.

Which command answers which question

The operator wants	Command
"show me the ledger state" / "kit runs" / "kit lane telemetry"	stats render kit_runs --surface terminal
"my debt" / "understanding debt"	stats anomalies (checks SUM(kit_runs.gates_ovr) against threshold; this is the current debt signal, superseding a raw grep over | DEBT | lines). For the raw numbers behind it, stats query "SELECT rid, gates_ovr FROM kit_runs WHERE gates_ovr > 0" --surface terminal
"any ledger anomalies" / "should I propose anything"	stats anomalies (report only) or stats anomalies --propose (stage a candidate row per fired anomaly into the cc-backlog staging buffer; never files a board row)
"telemetry" (tide moves)	stats render tide_moves --surface terminal
"token cost" / "how much am I spending on tokens"	stats render tide_tier_b_calls --surface terminal (per-call cost/token rows); for a spike check specifically, stats anomalies
"ledger status" / a quick glance at everything	stats tables first (row counts per table), then render the table the operator actually cares about
"render the ledger" / "ledger dashboard" / "share this as an artifact"	the same render command with --surface artifact --out <tmp path>.html, then call the Artifact tool on that file
an ad-hoc cross-ledger question ("which runs correspond to which tide moves")	stats render --query "<read-only SQL JOIN>" --surface terminal

Full table list + schema: lib/stats/README.md. stats tables also
lists what's materialized right now.

Surface-selection rule (pick ONE per ask)

• Quick look, mid-conversation (the operator just wants an answer now) ->
  --surface terminal. This prints a bot-reply-formatting-shaped fenced code-block
  table (right-aligned numerics, a bar-fill column for any *_pct/*_rate/*ratio*
  column) , paste that output directly into your reply, do not re-summarize it into
  prose first.
• "Share this" / "send it to me" / "for review" -> --surface artifact --out <tmp-path>.html, then call the Artifact tool on the written file (self-contained
  HTML, CSP-safe, no external requests , the file already satisfies the Artifact tool's
  contract as-is).
• Both surfaces render from the exact same query result (one stats render
  invocation, one row set); there is no divergent second read between them.
• A wide result (many columns) reads badly as a phone-width code block , prefer
  --surface artifact for those rather than fighting the terminal table's width.

Examples

cd ~/workspace/<owner>/dwarves-kit/lib/stats

# Quick look: "show me the ledger state"
uv run stats render kit_runs --surface terminal --limit 10

# Share: "send me the token-cost breakdown as an artifact"
uv run stats render tide_tier_b_calls --surface artifact --title "Token cost" \
  --out /tmp/ledger-token-cost.html
# then: call the Artifact tool on /tmp/ledger-token-cost.html

# Ad-hoc cross-ledger question, terminal surface
uv run stats render --query \
  "SELECT k.repo, count(*) AS n FROM kit_runs k GROUP BY 1 ORDER BY n DESC" \
  --surface terminal --title "Runs per repo"

# Feedback loop: "any anomalies? propose a backlog row if so"
uv run stats anomalies --propose

If the db has never been built on this host, stats render (like show/query)
lazy-rebuilds from the source files first (existing lane-telemetry behavior, unchanged here); no extra
step needed.

Install

This skill's canonical source is this file (skills/stats/SKILL.md; relocated
from lib/stats/skill/ -- at the old subsystem-internal
path it never installed, because install.sh globs skills/*/SKILL.md only).
It now installs automatically on both install paths (bash installer + plugin),
same as get-api-docs and skill-review. No symlink step needed; edit the
in-repo file.

When NOT to use this skill

• Editing or mutating any ledger , there is no such path here, or anywhere in this
  tool (read-only by hard contract; stats anomalies --propose's only write is the
  gitignored cc-backlog staging buffer, never a ledger, never a board).
• Ad-hoc SQL you're going to iterate on yourself , just run stats query/ledger show directly; this skill is the rendered-answer path, not a SQL console.
• Filing a board row directly , stats anomalies --propose only STAGES a candidate;
  promoting it to _meta/BACKLOG.md still goes through the existing board promote
  human gate (ex add-backlog), same as any other cc-backlog candidate.
• A persistent dashboard or TUI , there isn't one; every render (or anomaly check) is
  one on-demand query, driven by the agent, per the ROADMAP's binding "consumer is the
  agent on-demand, not a human TUI" decision.

Known tradeoffs (read before trusting an anomaly at face value)

• stats anomalies' home field is a static per-detector guess, not derived from
  data; debt/misfire sums are GLOBAL across every repo in kit_runs, and ~44% of
  kit_runs rows carry repo = "?" (unattributed) as of this writing. Treat a fired
  anomaly's "home" as a starting guess for the operator to confirm, not a fact.
• A missing source (e.g. no tide state.sqlite on this host) reads identically to a
  present-but-empty one; stats tables/anomalies cannot currently tell you which.
  Full list + the other two (schema double-definition, lane-telemetry coupling):
  lib/stats/README.md "Known tradeoffs".