pod-telemetry

Companion to pod-dispatch (atomic commit discipline). This skill measures which pod prompt templates actually ship commits so the loop itself comes under PID control. Robert's call: "if we're using pods then the loop itself must be improving itself with PID."

Every pod dispatch logs a start row when launched and an end row when done. state/lint/pod-trends.ts joins the pair by pod_id and prints a per-template_name leaderboard sorted by commit_rate. Templates that produce commits float up; templates that burn tokens without shipping sink.

Template naming convention

<scope>-<verb>. The scope is what directory or concern the pod owns, the verb is what it does. Lowercase, hyphen-separated, under 32 chars.

Good:

• sync-heal - drop+repush manifest entries on gateway drift
• skill-graduate - promote a prose skill to a sidecar script
• loader-self-write - regenerate <name>/AGENTS.md from the full page
• directive-tick - one tick of a running /snappy-go agent
• pid-regen - produce a regen brief for an eval-declining skill
• friction-heal - close an open P0/P1 friction

Bad:

• fix-stuff - no scope
• pod-a - letter suffix is a run id, not a template
• do-the-thing - scope+verb missing

Mandatory fields

On start:

On end:

Usage

import { logPodStart, logPodEnd, podId, hashPrompt } from "../lib/pods.ts";

const template_name = "sync-heal";
const prompt = "Resolve the 4 gateway-drift-batch P1 frictions by dropping manifest entries and re-pushing.";
const pod_id = podId(template_name);
const t0 = Date.now();

logPodStart({
  pod_id,
  template_name,
  prompt_hash: hashPrompt(prompt),
  scope: "state/log/frictions.ndjson",
});

const commitsBefore = gitRevCount();
// ... dispatch the pod ...
const commitsAfter = gitRevCount();

logPodEnd({
  pod_id,
  commits: commitsAfter - commitsBefore,
  lint_delta: lintAfter - lintBefore,
  eval_delta: evalAfter - evalBefore,
  wall_ms: Date.now() - t0,
  status: "success",
});

Relationship to pod-dispatch

A well-run pod obeys both: it commits atomically (pod-dispatch) AND it logs start+end telemetry (pod-telemetry). The two skills are orthogonal.

Eval

Shape-gate. After a pod dispatch:

• state/log/pods.ndjson gained exactly one phase:"start" row matching

pod_id, with non-empty template_name, prompt_hash, scope.

• state/log/pods.ndjson gained exactly one phase:"end" row matching

pod_id, with numeric commits, lint_delta, eval_delta, wall_ms and one of the allowed status values.

• npx tsx state/lint/pod-trends.ts runs clean (exit 0) and lists the

template_name in its table.

Score = 1 if all three pass; else 0. The pod-telemetry library (state/lib/pods.ts) writes state/log/pods.ndjson rows directly; the eval row in state/log/evals.ndjson (with skill: "pod-telemetry", verb: "log") is appended by the caller after endPod() returns, not by the library itself.

Why this matters

Fan-out without measurement is lottery-ticket agent work. Four pods get launched; two commit, two burn tokens - and next time we use the same four templates because nobody tracked which template carried which pod. The state/lib/pods.ts + state/lint/pod-trends.ts pair closes that loop: templates with low commit_rate get deprecated, templates with high commit_rate get reused + refined.

Backfill

Historical pods (before this skill existed) can be backfilled by appending rows to state/log/pods.ndjson with backfilled: true in the extra fields. Best-effort commits, wall_ms, and status are fine; the pod_trends aggregator treats backfilled rows the same as live rows.

Gotchas

• Never reuse a pod_id across runs - the aggregator joins start+end on pod_id.
• commits is pod-authored commits, not total repo commits - snapshot HEAD before/after.
• status: "noop" is valid - pods that detect "nothing to do" MUST log it so commit_rate isn't polluted by false failures.
• template_name stays stable across runs; pod_id rotates. Mixing them breaks aggregation.

Rubric

criteria:
  - name: start_log_correctness
    kind: deterministic
    check: "The `state/log/pods.ndjson` file contains exactly one `phase:\"start\"` row for the `pod_id` with non-empty `template_name`, `prompt_hash`, and `scope` fields."
  - name: end_log_correctness
    kind: deterministic
    check: "The `state/log/pods.ndjson` file contains exactly one `phase:\"end\"` row for the `pod_id` with numeric `commits`, `lint_delta`, `eval_delta`, `wall_ms` fields, and the `status` field is one of `success`, `fail`, `timeout`, `partial`, or `noop`."
  - name: pod_trends_lint_clean
    kind: deterministic
    check: "Executing `npx tsx state/lint/pod-trends.ts` exits with code 0 and lists the `template_name` in its output table."
  - name: template_naming_convention
    kind: judge
    check: "The `template_name` follows the `<scope>-<verb>` convention, is lowercase, hyphen-separated, and under 32 characters."

pod-telemetry - loader

Per-turn rules. Full reference: state/skills/pod-telemetry/SKILL.md. Do not skip these.

Critical Rules

• EVERY pod dispatch MUST log a phase:"start" row AND a phase:"end" row to state/log/pods.ndjson - no exceptions
• template_name MUST follow <scope>-<verb> (e.g. sync-heal, skill-graduate, directive-tick); letter suffixes like pod-a are run ids, not templates
• pod_id is unique per run (use podId(template) from state/lib/pods.ts); template_name is stable across runs - never mix them
• status: "noop" is valid and required when a pod correctly detects nothing to do; do NOT log "fail" just because commits:0

Commands

| ui dashboard | state/skills/pod-telemetry/resources/ui.openui | |library: state/lib/pods.ts - logPodStart(), logPodEnd(), podId(), hashPrompt() |aggregator: npx tsx state/lint/pod-trends.ts |log: state/log/pods.ndjson |eval log: state/log/evals.ndjson (skill: "pod-telemetry", verb: "log")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/pod-telemetry/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Forgetting the end row - pod_id appears only in start, aggregator counts it as 0 runs
• Passing commits as total repo count - use a before/after snapshot of git rev-list --count HEAD
• Free-form template_name values (e.g. "misc", "work") make the leaderboard useless; use real scope-verb slugs

Self-Test

An agent reading this should correctly:

1. [ ] Call logPodStart before launching a pod and logPodEnd when it returns?
2. [ ] Use <scope>-<verb> for template_name (not letter suffixes)?
3. [ ] Log status: "noop" when a pod correctly short-circuits on "nothing to do"?
4. [ ] Run npx tsx state/lint/pod-trends.ts to see which templates ship work?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] pod-telemetry: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] pod-telemetry: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.