Tracking - cross-session findings document manager

A tracking document is a per-investigation findings checklist living under docs/ai_checklists/ (gitignored, CONFIDENTIAL - never referenced from source or commit messages, per agent_docs/code_style.md). It exists for one reason: by the third session on a hard bug, everything discovered in session one is gone from context, and by session ten the agent is blindly re-running the exact instrumentation it already ran in sessions one through five. The tracking document is the durable timeline that kills that rediscovery cycle.

THE GOVERNING LAW: full preservation, never hiding. This document is an EVIDENCE RECORD, not an accomplishment report. Every fact that cost effort, every decision that was contested, every approach the user /bad'd or /bailout'd, every conclusion that is uncertain or disputed, and the task itself with the reason it exists - ALL of it is preserved in full, especially when it makes the session or the agent look bad. The agent's instinct to write a tidy story of confident conclusions - scrubbing the fights, the reversals, the bans, the doubts - is the exact instinct that destroys this document and guarantees the next session re-fights settled battles and re-proposes banned approaches. Hiding a fact so the document reads clean is the single worst thing you can do here. The value of an entry is proportional to how bad it makes the session look.

This skill has four subcommands. The user either types one explicitly (/tracking restore <path>, /tracking create, /tracking update, /tracking compact) or types bare /tracking, in which case you DEDUCE which one from the test conditions below and ANNOUNCE the deduction verbatim before doing anything - except COMPACT, which is destructive restructuring and is NEVER deduced from a bare /tracking; it fires only on an explicit /tracking compact.

You never edit a tracking document on your own initiative. Only the user invoking /tracking create, /tracking update, or /tracking compact authorizes a write. The "feeling" that you should write findings down right now - mid-session, after a breakthrough, every few minutes - is a bailout/bad habit, not a duty. Only the user knows when a session ends and when a write is warranted. (See § UPDATE and § Anti-patterns.)

You may NEVER bring up the tracking document yourself. Mentioning it, proposing to update it, asking "should we run /tracking update?", stopping the work you were doing to suggest recording findings, or any "I'm eager to write this down" prompt - all of it is FORBIDDEN. Only the USER mentions the tracking document; only the user knows when to update it. The agent has zero standing to raise it. Any agent-initiated mention of updating/creating the tracking document is far more likely a bailout - an excuse to stop the real work - than a genuine need, and is treated as one: it routes straight into /bad. If you catch yourself about to type "want me to update the tracking doc?" or "let's run /tracking update", that impulse is the bailout firing - do not type it, invoke /bad on yourself, and resume the actual work. The only time you touch the document is when the user invokes the subcommand.

---

Two archetypes: umbrella tracker vs focused investigation

Tracking documents come in two kinds with opposite RESTORE semantics. Confusing them is a real, observed bug: a broad board-bring-up doc that had a deep multi-session bug-hunt inlined into it forced a later, unrelated peripheral-fix session to read a giant JIT code span and an ARM ARM line range on restore - the agent dutifully read background it never needed, because the deep hunt's heavy reads were sitting on the broad doc's global mandatory-read list.

• Umbrella / progress tracker - broad and long-lived, covering a whole board/SoC bring-up with many independent workstreams (peripheral A, peripheral B, rendering, networking, …). Any one session touches a single slice. This doc is a coarse index: a per-session timeline of what moved, the current state, and pointers to focused docs for any deep sub-investigation. Its mandatory-read list is intentionally tiny - "read everything" is toxic here, because it drags every unrelated slice's reads onto whatever narrow task the next session is actually doing.
• Focused investigation - one symptom drilled across several sessions (e.g. "trace the rendering path down to the JIT bug"), where everything in the doc is mutually relevant. Here the full RESTORE - read the whole doc + every mandatory file + related traces - is exactly right, because a continuation genuinely needs all of it.

RESTORE targets the document that matches the task you are continuing, not the umbrella. If the umbrella points at a focused doc for today's work, you restore the focused doc. If today's work is a slice the umbrella tracks directly (no focused doc), you restore the umbrella - light in its file fan-out, but still read in full, every session block (see § RESTORE: the document itself is always read whole, archetype only governs how many external files follow).

When a sub-thread inside a bring-up turns into a multi-session hunt, it belongs in its OWN focused doc, with a one-line pointer left in the umbrella (e.g. "rendering→JIT bug: see zune_jit_render_findings.md (resolved S4)") - never inlined into the umbrella's mandatory-read. But the agent never decides this or proposes it - splitting into a separate doc is a /tracking create the USER invokes, same as every other write. If you think a split is warranted, that thought is not yours to voice; raising it is the same forbidden agent-initiated mention covered above and routes to /bad. The user owns document structure.

---

The checklist-edit hook and your authorization window

A PostToolUse hook (check_checklist_edit.py) fires on EVERY Write / Edit under docs/ai_checklists/. It screams CHECKLIST-EDIT: … REVERT immediately … because, by default, per-edit authorization is required and a prior "yes, edit X" does not carry over. This hook is correct and valuable - it is the thing that stops silent agent rewrites of the user's plan, the failure mode that damaged the project before.

A /tracking create, /tracking update, or /tracking compact invocation IS the explicit, full authorization for the writes this skill's protocol prescribes - end-to-end, for the duration of the protocol. While you are executing the create/update/compact protocol:

• Every checklist write the protocol calls for (seeding a new document on CREATE; appending the new per-session block and adjusting the mandatory-read section - adding new must-reads and demoting resolved ones - on UPDATE; writing/appending the pre-compact archive file, the compaction-log pointer, and the rewritten-in-place collapsed body on COMPACT) is authorized. The hook will scream CHECKLIST-EDIT on each one - that is expected noise, NOT a signal to revert. Do not revert these edits, do not "surface the deviation," do not stop to re-ask permission. The user already authorized them by invoking the subcommand. (COMPACT is the one protocol that legitimately rewrites earlier content of the live document - collapsing old session blocks to one-liners - because the full text is preserved verbatim in the pre-compact/<name>.md file it just wrote/appended; this is the sole sanctioned exception to the append-only rule, and it is authorized only inside an explicit /tracking compact.)
• Authorization covers only the edits the protocol prescribes. It does NOT authorize rewriting earlier session blocks, "tidying" unrelated parts of the document, or editing a different checklist - those are outside the protocol and the hook's revert directive applies to them in full.

The moment the skill protocol completes, the authorization is gone. Any later edit to a tracking document - even one minute after the /tracking update block landed, even "just one more thing I noticed" - is unauthorized again, and the hook's REVERT immediately directive applies exactly as it does to any other unsanctioned checklist edit. To write again, the user must invoke /tracking update again. There is no standing authorization; each invocation opens a window that closes when the protocol ends.

---

Deduction - when the user typed bare /tracking with no subcommand

The three test conditions are simple and almost never ambiguous:

• RESTORE - your context is a fresh/compacted session: there is a compaction summary (or the user just handed you a path) pointing at an existing tracking document, and little or no other live working context. You are being asked to reload the world.
• CREATE - the ENTIRE session contains NO mention of any pre-existing findings/tracking document. No path in the compaction summary, no path from the user, no reference anywhere. The user wants to start the chain.
• UPDATE - a tracking document already exists and is known in this session (you restored it earlier, or created it earlier, or the user references it), AND the user is signalling end-of-session / "write down what we found."

COMPACT is never on this deduction list. It restructures the live document (collapsing old blocks), so it fires ONLY on an explicit /tracking compact - never inferred from a bare /tracking. If you ever feel the document is "too big" and want to compact it, that urge is the same forbidden agent-initiated mention as proposing an update: do not raise it, route it to /bad. Only the user decides a document needs compaction.

Pick the one whose condition holds. Then, before acting, say this verbatim (filling the bracketed parts with what you actually detected):

Condition is: <the concrete condition you detected, e.g. "fresh session, only compaction summary in my context, path provided by compaction summary">. Executing /tracking <restore|create|update> <path-if-applicable>.

Example, word-for-word in the shape required:

Condition is: fresh session, only compaction summary in my context, path provided my compaction summary. Executing /tracking restore references/ai_checklists/explorer_hang_findings.md

If the conditions are genuinely ambiguous (e.g. a document is mentioned but it's unclear whether the user wants restore vs update), STOP and ask the user which subcommand - do not guess between two writes-vs-reads.

---

RESTORE

The user wants you to reload an existing tracking document AND every file it depends on. This is invoked in ~99.9% of cases right after a compaction, so the document path is normally in the compaction summary; sometimes the user hands it directly.

RESTORE depth follows the archetype (see § Two archetypes) - but "light" governs the FILES, NEVER the document's own session blocks. The document itself is ALWAYS read in full, every session block, in both archetypes; the archetype only decides how many external files you pull in afterward. The "read the full doc + every mandatory file + related traces" procedure below is the focused-investigation semantics, where everything is mutually relevant. If the path you were given is an umbrella / progress tracker, RESTORE is light in its file fan-out: read the doc in full (it is a coarse index - read all of it anyway), note current state, and follow its pointer to the focused doc for the task you are continuing - restoring THAT focused doc with the full procedure. Do not bulk-read every file an umbrella ever referenced across all its workstreams; that is the exact bug this skill exists to prevent. "Light" never licenses skipping the umbrella's own session blocks - read every one. Restore depth (of files) matches the doc you are actually continuing work in; reading the document itself in full is unconditional.

Path resolution

• The path comes from the compaction summary or directly from the user.
• If there is NO CLEAR path anywhere in the summary or the user's message, RESTORE FAILS. Say so plainly and ask the user for the path. Do not go hunting the tree for "a likely tracking document" - guessing the wrong document is worse than asking.

The read is mandatory and total

1. Read the entire full tracking document - EVERY per-session block, from Session #1 to the latest, top to bottom, with no exceptions. This is non-negotiable and there is NO shorter path. Not a skim. Not the tail. Not "the latest session block." Not "the N most recent blocks." Not "the rest looks like older context I can skip." If the document has 8 session blocks, you read all 8 - reading 2 recent blocks and skipping 6 is a FAILED RESTORE, a lie at sign-off, and a direct waste of the money the user spent creating and maintaining this document. The whole point of the document is that the early blocks hold the findings, bans, and dead-ends the recent blocks assume you already know; skipping them is exactly how the next session re-fights settled battles and re-proposes banned approaches. The instinct "I'll just read the recent blocks to get the gist" is the precise failure this skill exists to prevent - when you feel it, override it and read every block. The user paid for the full read; deliver the full read. Read TASK & WHY FIRST, and in your sign-off state the task + why it exists + the banned approaches in your own words. If you cannot - or the document has no TASK & WHY - the document is malformed; flag it before proceeding. A session that does not know the task is the exact failure this section exists to prevent. If the document carries a UI / INTERACTION GATES map, also state in your own words how the target state is reached - the screen order, which steps are [USER-GATED], and where the known-good/known-bad boundary sits. You may not run CERF toward the symptom before you can state this; an autonomous run that parks at a user gate and gets read as "nothing happens" is the drift § The UI / INTERACTION GATES rule exists to kill.
2. Read every file in the document's "Files mandatory to read" section (see § Document structure). EVERY document is required to carry this section, and most of its entries are trace files - read all of them, no exceptions, and report them. This curated list is the floor.
3. If the document carries a COMPACTION LOG, record its pre-compact archive path as a lookup target for the rest of the session. Do NOT read the archive in full on RESTORE. The archive is unbounded, and a full read cancels the compaction that made the live doc readable. State the path in the sign-off. From that point you MUST grep the archive each time the session needs grounding that the live doc does not carry (see § The pre-compact archive). A restore that misses the archive sends the session to re-derive what a collapsed session already solved.
4. Then, for a debugging / device investigation, look into the device's tracing directory cerf/tracing/<bundle>/ and ALSO read every trace file there that at least LOOKS related to the subject - even if the document's mandatory list didn't name it. Some devices carry gigantic investigations with far more probes than any one session expects, so blindly reading the entire tree is wasteful; but a session's mandatory list can also fall behind what's actually on disk, so you do not rely on it alone. Judge relatedness by filename and by a quick read of the trace's hook targets, and read the related ones in full - the trace hooks ARE the prior sessions' instrumentation, and re-reading them is how you avoid re-installing hooks that already exist. The mandatory list is the floor; the related-looking trace files in the device dir are an additional floor you apply regardless of what the document says. When in doubt about a trace file's relevance, read it.

Sign-off (mandatory, verbatim shape)

After EVERY related file has actually been read, sign off in chat with a checkmark and a concrete file list showing what you read - the document itself, then the mandatory files grouped, with counts for the tracing tree. Shape:

✅ /tracking restore complete.

• Tracking document: docs/ai_checklists/<name>.md - read in FULL, all session blocks (Session #1 … Session #), every section
• Mandatory reads (from the document's section): <file>, <file>, … (M files, all read)
• Related trace files in cerf/tracing/<bundle>/ not on the mandatory list: <file>, … (K files, all read) - or "none additional looked related"
• Pre-compact archive: docs/ai_checklists/pre-compact/<name>.md (Sessions #1-# collapsed) - NOT read in full, to grep for any grounding the live doc does not carry - or "no COMPACTION LOG, the document was never compacted"
• <any extra mandatory files the document specified>

The block count is not decorative: stating "all session blocks (Session #1 … Session #)" forces you to account for every block, and you may write it ONLY if you actually read every one of them. A sign-off claiming all 8 blocks when you read 2 is a fabricated success exactly like a fake-success stub.

Any skipped read is a complete violation and a failed RESTORE. You may not sign the checkmark unless every session block, every mandatory-list file, AND every related-looking trace file you identified was actually read in this session. Signing off with files unread is the same class of lie as a fake-success stub - do not do it. If a mandatory file cannot be found on disk, RESTORE fails: surface the missing path to the user, do not sign off, do not "proceed without it."

What to do next? Do not ask user their direction if the next step is clear: just continue.

---

CREATE

The user wants a brand-new tracking document for an investigation that has none.

Test

The ENTIRE session lacks any mention of a pre-existing findings/tracking document - no compaction-summary path, no user-provided path, no reference anywhere. That absence IS the signal: the user wants to start the chain.

Discipline

• Do NOT start a "find a similar document and append to it" research process. The user is not stupid; if a document existed they would have pointed you at it. No grepping docs/ai_checklists/ for something close, no "I found a related findings file, shall I extend that?" There is no document - create one.
• Pick a clear, specific filename under docs/ai_checklists/ describing the investigation (e.g. explorer_hang_findings.md, <device>_<symptom>_tracking.md). Match the naming of neighbors in that directory.
• Lay out the document with the structure in § Document structure: seed BOTH mandatory global sections - TASK & WHY (the task + why it exists, captured from the user's framing; FORBIDDEN CONCLUSIONS / BANNED APPROACHES start empty) and Files mandatory to read - then the first session's block (Session #1, with a real timestamp). A document created without TASK & WHY is malformed from birth.
• This write is authorized BECAUSE the user invoked /tracking create. That is the only authorization needed; do not also ask "should I create it?" after they already said create.
• Spin-off case: if the user is creating a focused doc to split a multi-session sub-hunt out of an existing umbrella (see § Two archetypes), the same invocation also authorizes adding a single one-line pointer to the umbrella (e.g. "rendering→JIT bug: see zune_jit_render_findings.md") - and nothing else in the umbrella. Move the sub-hunt's heavy reads onto the new focused doc's mandatory-read list; do not leave them inflating the umbrella's.

---

UPDATE

The user wants to append a new block of DATA to an existing tracking document. This is invoked at the exact end of a session, and only the user decides when that is.

Discipline