// Reads a Drive trace.jsonl and renders a deterministic diagnostics report. Use when you want to measure a Drive run, read a trace, or produce a diagnostics report over an emitted Drive trace.
| name | drive-diagnose-run |
| description | Reads a Drive trace.jsonl and renders a deterministic diagnostics report. Use when you want to measure a Drive run, read a trace, or produce a diagnostics report over an emitted Drive trace. |
A deterministic, LLM-free tool that reads an emitted Drive trace.jsonl and renders a structured markdown diagnostics report. It is the read-side counterpart to the drive-record-traces skill, which owns the trace vocabulary and emission protocol.
skills-contrib/drive-record-traces/schema.ts (the single source of truth for the trace-event vocabulary).load.ts — JSONL loader: parses + validates each line; collects errors with line numbers instead of throwing.metrics.ts — diagnostic-metric functions over a TraceEvent[] (rework rate, brief reissues, spec amendments, plan amendments, I12 halts, tier mix, wall-clock, etc.). Metric names count instability: lower is better, 0 means the artefact held.scorecard.ts — the two-tier scorecard over a TraceEvent[]: a per-run Tier-1 correctness verdict (from the external correctness-recorded feed) and the Tier-2 token totals (from the per-run tokens-recorded feed). The headline of the report.assertions/ — one checker per Drive invariant (I1–I12), cascade-redesign rule, and brief-discipline anti-pattern; each returns pass | fail | not-checkable with evidence refs.report.ts — markdown dashboard renderer.posthoc.ts — best-effort reconstruction of trace events from a Cursor transcript JSONL.cli.ts — entry point.node skills-contrib/drive-diagnose-run/cli.ts <trace.jsonl> [--posthoc <transcript>] [--out <output.md>]
In this repo, the pnpm drive:diagnose shortcut is available:
pnpm drive:diagnose <trace.jsonl>
The report leads with the two-tier scorecard and these caveats:
correctness-recorded feed: mechanical gates + QA run + judge intent). With no correctness signal, the run verdict reads not computable and names the missing input — all-green metrics never imply "good". Tier 2 (tokens from the tokens-recorded feed, plus wall-clock and rework) is rendered only over runs that passed Tier 1; absent token figures render n/a (no signal).not-checkable with a one-line rationale — they count toward named coverage gaps, not pass/fail.origin: "native" events are author-asserted (the emitting skill or orchestrator appended them). They are not independently verified. Runs where the orchestrator hand-emitted the trace should be discounted to "reader works, not methodology works".Requires Node with native TypeScript execution (Node 24+) and the arktype package.
In this repo arktype is already available via the workspace root node_modules — no extra install needed.
In another repo, install it before running:
npm install arktype
A zero-dependency validator is a possible future improvement; for now arktype is the only external dep.
drive-diagnose-run imports schemas directly from the canonical skills-contrib/drive-record-traces/schema.ts, which is the single source of truth for the trace-event vocabulary and emission protocol. Schema changes go in drive-record-traces.
Spawns one Drive orchestrator run on a golden-case brief with a pinned model, accumulates per-run token usage, and writes a run manifest — the corpus generator the Drive LLM judge calibrates against. Use when you want to run a golden Drive brief end-to-end, produce a natively-instrumented run, accumulate token usage from the Cursor SDK, or validate the post-hoc trace parser against a transcript corpus. Live execution is gated behind --live + CURSOR_API_KEY; the default is a dry-run that makes no live call.
Upgrade Prisma Next in your app. Bumps every `@prisma-next/*` dependency from the version pinned in the lockfile to the requested target (or npm `latest`), applies any required code-translation steps from the per-transition upgrade instructions, validates with the project's own typecheck + tests, and commits each minor step on its own. Use when the user asks to "upgrade Prisma Next", "bump Prisma Next", "move to Prisma Next X.Y", or asks an agent to deal with an `@prisma-next/*` minor bump in their app.
Library skill that owns the Drive trace-event vocabulary and the JSONL emission protocol. Instrumented drive-* skills reference this skill by name from their "Emit" steps for payload schemas (events.md) and file-path resolution + append mechanics (emission.md), so the vocabulary lives in one canonical place rather than in project-local docs. Use when an instrumented Drive skill reaches an "Emit `<event>`" step and you need the payload schema or append mechanics to write the trace line; when adding or changing a trace event type; when instrumenting a new skill with an Emit step; or when computing metrics from an emitted trace.jsonl.
Upgrade Prisma Next in your extension. Bumps every `@prisma-next/*` dependency to the requested target (or npm `latest`), runs the per-transition upgrade instructions for the extension SPI (middleware lifecycle, codec / migration-tools / framework-components churn, seed-migration on-disk shape), verifies the pins are correctly exact via `prisma-next-check-pins`, runs the extension's own typecheck and tests, and commits each minor step on its own. Use when the user asks to "upgrade Prisma Next" in an extension package, or to update an extension's `@prisma-next/*` deps to a new minor.
Run a project-health rollup at one of three cadence points: session-bookend (start / end), per-slice-merge (after each slice's DoD), or trigger-fired (operator-requested or surfaced by drift signals). Surfaces progress, drift signals, dispatch throughput, calibration story, and recommended next pick. Atomic skill — primary output is the rollup. Downstream skill recommendations are surfaced; auto-invoke only in unattended mode with operator policy.
Close out a project: verify project DoD (incl. mandatory final retro per invariant I10), classify files under projects/<project>/ as long-lived methodology vs transient project artefacts, migrate long-lived into docs/, strip repo-wide references to projects/<project>/**, delete projects/<project>/, and open the close-out PR. Refuses to delete if DoD unmet or operator hasn't confirmed the classification. Atomic skill; invoked by drive-deliver-workflow once all slices are merged, or directly by the operator at end-of-project.