agentleFS
giulio333giulio333/ClaudeLens/.claude/skills/transcript-drift/SKILL.md

transcript-drift

Skill67 starsChanged 40 days agoMITView on GitHub

Check whether Claude Code's transcript format has moved ahead of what ClaudeLens reads, and turn what the check finds into triage or an issue. Use when asked to look for format drift, to see what the app is missing from transcripts, after a Claude Code upgrade, or when a session renders wrong and the format is suspected.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Real model turns, real tokens: Never run it as part of a check.

    line 84
  2. Very specific:

    Every drift finding on a _shape_ axis gets one verdict in scripts/transcript-manifest.mjs, then npm run census:accept to re-baseline.

    line 90
  3. Distinctive:

    Write what a real specimen would need to look like to settle it — that is the note's job.

    line 113

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Is the transcript format ahead of us?

ClaudeLens reads Claude Code's ~/.claude/projects/**/*.jsonl, and Claude Code keeps adding to what it writes there. Nothing announces it. A new row type, a new attachment subtype, a new content block simply doesn't appear in the app — #245 and #246 both sat unnoticed for months.

Stages 1 and 2 answer two different questions and do not overlap — run both. Stage 3 costs tokens and is only for a question the first two left open.

1. What we don't read

npm run census

Streams the whole corpus (~1s) and diffs the shapes it finds against the decisions in scripts/transcript-manifest.mjs. Exit 1 means drift. Read the report in five parts:

  • Drift — a shape with no manifest entry, absent from the baseline. This is the finding. Claude Code writes it and nobody has looked at it.
  • New fields — the same drift line counts these separately, as in 0 unknown shapes, 11 new fields. A key-path on a row we read or intend to read that the baseline has never seen. Read the warning below before re-baselining.
  • Known gaps — triaged candidate: decided, not yet read. A standing backlog, not news. Don't report these as new.
  • Looked at, not decided — triaged unknown: open questions someone already examined. Also not news, but each one names what would settle it, so this is where to look when you have a new specimen in hand.
  • In the manifest, absent from this corpus — either dropped upstream, or never exercised here. Stage 3 tells the two apart. Suppressed under --root, where a narrowed corpus makes it list most of the manifest and mean nothing.

The field axis is report-once. Shapes are diffed against the manifest, so an un-triaged shape returns every run until someone decides about it. Fields are diffed against the baseline only — there is no table they must appear in — so npm run census:accept makes a field finding disappear permanently, whether or not you understood it. That is deliberate: a hand table of every field would be a second copy of the format and wrong within a week. But it means the sequence matters. Look at the fields, write a FIELDS entry for any that carry something (that is what keeps them in the backlog where you can see them), and only then accept. Accepting first destroys the evidence.

2. What we read wrong

npm run census:replay

The census only sees the file. A field can be present, recognised, and still dropped — which is what #245/#246 were. This test runs the real reader: fixtures pin which content blocks survive parseContentArray, and a corpus sweep fails on any dropped block the manifest hasn't triaged.

The sweep is opt-in (that script sets CLAUDELENS_DRIFT_CORPUS=1) and npm test skips it: it reads the whole corpus, so its outcome depends on state the test did not create, and left unconditional it reddens npm test on an unrelated branch because this machine's transcripts happen to contain something new. The fixtures in the same file are unconditional — they are the regression gate.

A census with no drift and a red test here is the more serious result: it means we mishandle something we already know about.

3. Only if a shape is missing from the corpus

node scripts/transcript-exercise.mjs --list
node scripts/transcript-exercise.mjs --yes --only <keys> --census

The corpus covers the features this user happens to use. A feature nobody exercised writes no rows, so the census can't distinguish "Claude Code doesn't do this" from "we never tried". This drives claude -p against prompts chosen to provoke specific shapes, in a throwaway dir the census skips by name.

Real model turns, real tokens. Never run it as part of a check. Reach for it only when stage 1 or 2 left a specific question a generated transcript would settle, and say which scenarios you want to run and why before running them.

Triage

Every drift finding on a shape axis gets one verdict in scripts/transcript-manifest.mjs, then npm run census:accept to re-baseline. (Fields are the exception — FIELDS is the one table allowed to be incomplete; see the report-once warning above.) The verdict is the deliverable: an un-triaged shape comes back identically next run, and a tool that repeats itself gets ignored.

  • read('<module>') — a module consumes it. Only after it actually does.
  • ignored('<reason>') — deliberately not read. Harness bookkeeping, prompt scaffolding, anything carrying nothing a transcript view would show. The reason is the point: it's what stops the next person re-litigating it.
  • candidate('<what it would give us>') — not read, and it should be. Say what the app could do with it, not just what the field is.
  • unknown('<what you saw; what would settle it>') — looked at, and the rows didn't say enough.

Use unknown rather than guessing. Sometimes the only evidence is a shape's name and one row with an opaque payload — a single occurrence, a bare {type, uuid}, a field whose value tells you nothing. That is not ignored: every ignored entry in the manifest names what the thing is, and none of them says "it had no fields". It isn't candidate either, which claims the app could use it. unknown records that someone looked, which stops it being re-reported as fresh drift, and keeps it in its own report section as the open question it is. Write what a real specimen would need to look like to settle it — that is the note's job.

One thing no verdict expresses well: a shape read for one purpose and not another. agent-meta is read by teams-reader, but only for the in_process_teammate case — 1 of the 35 sidecars on disk — and by nothing for the other 34. It is filed as candidate with that stated in the note, because a single verdict per shape can't say it. If you hit the same thing, put it in the note rather than picking the least-wrong verdict silently.

Which table the entry goes in follows the axis the report named: a row type in ROW_TYPES, an attachment.type in ATTACHMENT_TYPES, a content block in CONTENT_BLOCKS, a system.subtype in SYSTEM_SUBTYPES, a field in FIELDS keyed by the dotted path exactly as printed.

To decide, read the actual rows before guessing:

grep -h '"<the-type>"' ~/.claude/projects/*/*.jsonl | head -3 | python3 -m json.tool

Judgement calls worth stating plainly: volume is not importance — total_tokens_reminder is 10k+ rows of nothing, continued-in is 6 rows and a missing edge between sessions. And a dropped content block is never ignored: parseContentArray discarding a block loses user-visible content, and if the block is a message's only content the whole turn vanishes.

Reporting

Say which of the three stages produced the finding, and give the count — "57 image blocks across the corpus, each a turn the transcript renders as nothing" lands; "unhandled content block" doesn't. Distinguish the backlog from new drift; the user knows about the backlog.

For anything worth filing, use the github-issue skill — it carries this repo's house rules. Don't fix and file in the same pass unless asked: triage is cheap and reversible, a reader change needs a test alongside it.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.