Tracking

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, 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. A memory line can also pre-authorize one compaction (see § Automatic compaction). That line is the user's instruction, given ahead of time. 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. The one exception is the memory-gated chain after a RESTORE (see § Automatic compaction), where the memory line is the standing authorization. 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. For a debugging / device investigation, ls the tracing directory of the device (cerf/tracing/<bundle>/) and judge each file against the CURRENT goal. Do not read the directory by default. Judge from the filename and the hook targets, not from a full read. For each file, state a 0-100% figure for how much it serves the NEXT target the document names. Read a file only when you can name the thing in that target it serves. Zero files read is a good outcome. It needs no apology. A device carries probes from investigations that closed long ago. Those probes buy nothing in an unrelated task, and they cost the whole read. The mandatory list stays the floor. This directory is a candidate pool, never a second floor.

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 <X> session blocks (Session #1 … Session #<X>), every section
• Mandatory reads (from the document's section): <file>, <file>, … (M files, all read)
• Tracing dir cerf/tracing/<bundle>/: <N> files listed, <K> read - <file> <%> (serves: <what>), … - or "0 read, nothing served the current target"
• Live doc size: <L> lines. <the compaction line for that count, if any>
• Pre-compact archive: docs/ai_checklists/pre-compact/<name>.md (Sessions #1-#<K> 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>
• Stats: <W> weeks in, <N> sessions, <B> bans earned, <S> archived.

Compaction recommendation (part of the sign-off)

Count the lines of the live document (wc -l), then add the matching line to the sign-off. Under 2000 lines, add nothing.

Use the highest tier the count reaches. This line sits inside a user-invoked RESTORE, so it is not the forbidden agent-initiated mention of the document. Never run /tracking compact off the back of it, unless § Automatic compaction says you must. The recommendation goes in the sign-off, and the user decides.

Automatic compaction (memory-gated)

User memory carries the switch, and it reads exactly:

/tracking skill AUTOMATIC compact on restore is ENABLED

Read memory for that line on every RESTORE. The line is a standing authorization from the user. It lifts the explicit-only rule for this one path, and for nothing else.

• Line present, and the live document is at 2750 lines or more: chain /tracking compact yourself, straight after the RESTORE sign-off. Do not ask, and do not propose. The memory entry is already the answer.
• Line present, under 2750 lines: do nothing beyond the suffix below.
• Line absent, or it says DISABLED: never chain. The user decides, as everywhere else.

Write or remove that memory line only when the user asks to enable or disable the switch. Every other rule about user memory still holds.

Close the tier line with the state of the switch:

When one more session block carries the document past 2750, write (autocompact probably next session) in place of the band word. Judge that from the size of the recent blocks.

Session stats (part of the RESTORE and UPDATE sign-offs)

Close both sign-offs with one stats line. Every number comes from the document and its archive:

• Stats: <W> weeks in, <N> sessions, <B> bans earned, <S> archived.

• weeks - from the Session #1 timestamp to today's real date, taken from a tool.
• sessions - the highest Session #N in the document.
• bans - the entries under TASK & WHY → BANNED APPROACHES.
• archived - the size of the pre-compact file, or "no archive" when the document was never compacted.

The block count is not decorative: stating "all <X> session blocks (Session #1 … Session #<X>)" 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 must NOT sign the checkmark unless every session block, every mandatory-list file, AND every trace file you judged worth reading 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

• Never auto-edit, and never propose an edit. Your urge to record findings mid-session, right after a breakthrough, or "every few minutes" is a bailout/bad habit - it produces a schizophrenic document of "BREAKTHROUGH! → RETRACTION! → SHOCK! ROOT CAUSE FOUND! → RETRACTION!" entries that mislead the next agent. We have tested this; it rots the document. You do NOT write without the user's /tracking update, and you do NOT even suggest one - proposing an update, asking "should I record this?", or stopping work to raise the document is itself the bailout and routes to /bad (see the intro and § Anti-patterns). Only the user knows when the findings have settled enough to commit, and only the user raises it.
• An UPDATE appends a new per-session block at the END of the document - it does not rewrite or "tidy" earlier session blocks. Prior sessions are the timeline; they stay as written. (Correcting a prior session's conclusion is done by recording the correction in the NEW block's "Do not repeat / do not rediscover" section - "Session #3 disproved Session #1's theory that X" - not by editing Session #1.)
• The ONE part of an UPDATE that edits outside the new block is the global "Files mandatory to read" section: add this session's new must-read files, and demote entries for any work resolved this session (see § Document structure → Hygiene/Demotion). This keeps the list scoped to what a future continuation needs and is the only sanctioned edit to existing content.
• Prune the floor with what the RESTORE actually bought. Drop from Files mandatory to read every entry that this restore read and that served nothing. Leave an entry in place when the NEXT target still needs it. A file that costs a read and serves nothing is not a floor entry. It is a tax on every restore that follows. State the judgment in the sign-off.
• The new block carries Session #X (increment from the highest existing session number in the document) and a real timestamp obtained from a tool (date via Bash / Get-Date via PowerShell) - never a guessed or invented time. Agents chronically skip the timestamp, which turns a 50-block single-day document into an unreadable mess with no timeline. Get the real time.
• Fill the mandatory CODE STATE / KNOWN DEFECTS / COMMIT-BLOCKERS sub-section FIRST, before the success story. Any /verify verdict from this session (especially CRITICAL PROBLEM FOUND), any un-committable state, any regression the session caused goes there verbatim with file:line. This is the highest-value part of the update and the one agents drop because it contradicts the accomplishment narrative - see § Document structure → The most-critical-data rule. If you ran /verify this session and its verdict is not in this block, the UPDATE is incomplete.
• After CODE STATE, fill the DISPUTED / CORRECTED / REVERSED, the /bad, and the WHAT THIS SESSION ACTUALLY DID sub-sections (see § Document structure) - mandatory whenever they apply. These are the records agents scrub to make a session read clean, and their omission is what sends the next session to re-fight settled battles and re-propose banned approaches. Mirror any new ban into the global TASK & WHY → BANNED APPROACHES, and sharpen the WHY if this session clarified it. Then verify the whole UPDATE against § Preservation-not-hiding - the three completion tests - before declaring it done.
• If reaching the investigated state involves ANY on-screen sequence or user interaction, the block MUST carry the UI / INTERACTION GATES sub-section (see § Document structure) - current and complete. The boot/UI sequence with verbatim on-screen text samples, every [USER-GATED] step the agent cannot perform itself, and the known-good/known-bad boundary. If a prior block already holds the map and nothing changed, restate it or point at that block explicitly; if this session moved the boundary (a step got cleared, the symptom moved), the map is updated to say so. An UPDATE on a GUI-reachable investigation that leaves the next session unable to state "how does the user reach the symptom, and at which step does the agent have to hand over to the user" is incomplete - it is the exact omission that sends the next agent to re-crack a step already known to pass (see § The UI / INTERACTION GATES rule).
• Write the TASK & WHY ban/forbidden-conclusion ITSELF as ONE LINE - the rule + ×N count + (S#) - and leave the full rationale in this session's block, never inline in TASK & WHY. This is the bloat-prevention rule: a ban whose back-story is re-narrated as a multi-paragraph essay in the global section makes TASK & WHY grow without bound (it is append-only-clarify, so the essay never leaves on its own). The session block is where the evidence belongs; the global ban is a pointer to it. Shape: ❌ <one-line rule> - /bad'd ×2 (S3, S7), see S7. The full "why it was banned, what we tried, how it failed" stays in the S7 block.

Sign-off (mandatory, verbatim shape)

✅ /tracking update complete. Session #<X> appended.

• Restore value: earned its read - <file>, <file>. Served nothing - <file>, <file>.
• Dropped from mandatory-read: <file>, … - or "nothing dropped"
• Stats: <W> weeks in, <N> sessions, <B> bans earned, <S> archived. (see § Session stats)

The served-nothing half is the point of the line. A file named there is a file the next RESTORE does not read.

---

COMPACT

The user wants to shrink a tracking document that has grown too big to read in one call - the classic symptom is an umbrella tracker whose per-session blocks have piled up (or a long focused hunt) until a single RESTORE read no longer fits comfortably and leaves no window for several more sessions of work. COMPACT trades the narrative bulk of old sessions for one-liners + a pointer, while preserving every piece of critical data in full inside the live document.

Test

The user explicitly typed /tracking compact (optionally with a path), or a RESTORE chained it under § Automatic compaction. COMPACT is NEVER deduced from a bare /tracking and the agent NEVER proposes it (see § Deduction and § Anti-patterns). If no path is given and exactly one tracking document is live in this session, that is the target; if it's ambiguous, STOP and ask which document.

The pre-compact file - the single, ever-growing full reference

Every tracking document has at most ONE archive: docs/ai_checklists/pre-compact/<original_file_name>.md (same base name, same .md, NO numbering). It is the complete, never-lossy history - a reader who needs the full uncompacted detail opens this one file, always.

• First compaction writes it as a full copy of the current live document.
• Every later compaction APPENDS to its bottom only the session blocks added to the live document since the last compaction (the diff). It is append-only and only ever grows; you never rewrite or re-copy what is already in it.

So the pre-compact file accumulates the full text of every session ever written, in order, forever; the live document is the shrunk working copy that points at it. The compacted live document ALWAYS carries a pointer to this file (see the COMPACTION LOG step).

This file is the searchable long-term memory of the investigation. Every later session MUST grep it for grounding that the live doc no longer carries. § The pre-compact archive governs that use. Compaction is safe only because that obligation holds.

The governing law: never LOSE a fact - but bound every entry to its actionable form + a pointer

Compaction is a length operation, not a forgetting operation. The pre-compact file guarantees nothing is ever truly lost. No section is exempt from compaction: a section left in full-prose essay form (TASK & WHY bans, CARRIED-FORWARD, the log) accretes forever and becomes the bulk of the document, which collapsing session blocks alone cannot bound. The rule:

Nothing critical is ever DROPPED or SOFTENED from the live document - but nothing is kept in essay form either. Every critical item is reduced to its bounded actionable form (the rule / the map / the fact) + a see S# pointer; the full prose lives in the archive. This is the same move the session-digest makes (collapse the narration, keep a terse actionable line), applied to EVERY section so the whole document is bounded, not just the session tail.

The distinction that makes this safe - applied per item type:

• A ban / forbidden-conclusion has two parts: the RULE and the JUSTIFICATION ESSAY. The rule - what is forbidden, its running ×N count, and which session earned it - is immutable: never dropped, never softened, never de-counted, stays exactly as loud. The multi-paragraph essay re-narrating the investigation that produced it compresses to a one-line rule + see S#; the essay is in that session's block (digested) and verbatim in the archive. Compressing the essay is NOT softening the ban - the ban is just as binding at one line as at thirteen.
• A DO NOT REDISCOVER map keeps its full reusable detail - address / module / when / how / chain-order. A UI / INTERACTION GATES map is a map of the same rank and follows the same rule - screen order, verbatim text samples, [USER-GATED] markers, known-good boundary all stay in full while the investigation is live. A map is already the bounded actionable form (it has no "essay" to shed); collapsing it to a label re-creates the rediscovery cost it exists to prevent, so a live map stays in full. But a map for an axis that is superseded / refuted / resolved (the block itself says "DEAD" / "lives only in the archive") is no longer live - it DROPS from the live doc entirely (it is in the archive).
• A live CODE STATE defect / unresolved DISPUTED item stays in full (with the user's position at equal-or-greater prominence) until it is resolved; once resolved it drops to a digest line.
• The COMPACTION LOG is pure meta - it narrates the compaction operation, carries no investigation data, and is fully recoverable from the digest + archive. It compresses hardest: the pointer + its grep directive + one current-state line, with prior per-compaction narration dropped.

When in doubt whether something is "live," keep it - a slightly-too-long doc that kept a live map beats a tidy one that dropped it. But "live" is the test, not "exists": a refuted map, a resolved defect, and a ban's back-story are all kept in the archive, not the live doc.

Two numbers govern the finished size: ~700 lines is the TARGET, ~1500 lines is the HARD limit. Aim for 700. That size reads in one call and leaves headroom for several more sessions. Never finish with more than 1500 lines, because a document past that costs a whole read before any work starts. Collapsed session blocks alone do not make a compaction "done". It is done when the WHOLE document is inside the limit. On a long hunt that means you compress the bans, the carried-forward maps, and the log, not just the sessions.

Decide how far to go yourself. If the ordinary passes leave the document at more than 1500 lines, continue down the ladder in step 9. Collapse a wider window, merge digest ranges, and drop what has become least important. Do not stop to ask which items can go. You have just read the whole document, so you know which threads are dead and which are load-bearing. The archive holds every word either way. A question here hands off a judgment you are better placed to make. The document also stays oversized until the answer arrives.

So the procedure for each old block is: hoist first, then collapse. Pull any still-live critical item out of the block (into the carried-forward section below, tagged with its origin session), THEN reduce what remains to one line - and separately run the global-section passes (steps 7-8 below, then enforce the step-9 ceiling) over the bans, carried-forward maps, and the log.

Procedure

1. Resolve the path (explicit, or the single live document; ambiguous → ask). Read the document in full FIRST if it is not already fully in your context this session - you cannot safely collapse blocks you have not read, and you must know which blocks carry live critical data.

2. Update the single pre-compact archive at docs/ai_checklists/pre-compact/<original_file_name>.md (same base name as the live doc, no numbering; docs/ai_checklists/ and therefore pre-compact/ is gitignored and confidential - same as every tracking doc):

   • If the file does NOT exist → first compaction: copy the entire current live document into it, byte-for-byte. This is the full baseline (Sessions #1…#N).
   • If the file EXISTS → append the diff: find its highest Session #X heading with a tool (do not eyeball it), then append - verbatim, to the bottom, in order - every live-document session block whose number is greater than that X. Those are exactly the blocks added since the last compaction. Append nothing already present; never rewrite or re-copy existing content; never edit blocks already in the file.
   • Either way the pre-compact file is append-only and only grows; it is the single complete reference for the full uncompacted history.

3. Add / refresh the COMPACTION LOG global section in the live document (place it directly under TASK & WHY, above Files mandatory to read). It is pure meta - the pointer to the full reference plus the current state - and is kept SMALL and bounded, never a growing per-compaction narration:

   ## COMPACTION LOG
   This is a COMPACTED document. FULL uncompacted history (every session, verbatim):
   docs/ai_checklists/pre-compact/<original_file_name>.md
   GREP that file before you re-derive ANY fact this document does not carry. A digest
   one-liner or a `see S#` pointer means the full record is in that file, not that it is lost.
   State: Sessions #1-#<K> are one-lined in COMPACTED SESSION DIGEST; #<K+1>-#<N> kept full. Last compacted <timestamp>.

   Overwrite the State: line each compaction - do NOT append a new paragraph per compaction. The blow-by-blow of what each past compaction collapsed/hoisted carries no future value (it is recoverable from the digest + archive); the log must stay at exactly this fixed shape - pointer + grep directive + one State: line - no matter how many compactions have run. If this section currently holds per-compaction narration paragraphs, delete them down to the pointer + State: line. Timestamp comes from a tool (date / Get-Date), never guessed.

4. Hoist live critical data out of the blocks you are about to collapse into a CARRIED-FORWARD CRITICAL DATA global section (place it directly under Files mandatory to read). Each hoisted item keeps its full content and is tagged with its origin, e.g. (orig Session #3). This section holds ONLY items pulled from collapsed blocks - do-not-rediscover maps, UI / interaction gate maps, still-open defects, unresolved disputes, active bans not already in TASK & WHY. Recent full blocks keep their own critical data in place; do not duplicate it here. (Carried-forward items accumulate across compactions; never drop one because its origin session got collapsed - drop it only when the work it records is actually resolved.)

5. Decide the keep-window: the most recent 5-10 session blocks stay FULL, untouched. Pick the number that lands the live document inside a single comfortable read with headroom. If even 5 full recent blocks + the preserved globals still overflow, keep 5 and accept a longer file rather than collapsing a recent block - recency is where active work lives.

6. Collapse every older block to one line under a COMPACTED SESSION DIGEST section (place it just above the first surviving full block), chronological, one line per session. (On a re-compaction, extend the existing digest with the newly-collapsed sessions; keep prior digest lines.)

   ## COMPACTED SESSION DIGEST
   Full text of every session below is in the pre-compact file (see COMPACTION LOG).
   - Session #1 - <timestamp> - <terse what-it-established, ≤1 line>
   - Session #2 - <timestamp> - <terse>

   Keep each one-liner factual and specific - "established X, disproved Y" - not "did some work." No per-line path is needed; the single pre-compact file named in COMPACTION LOG holds them all.

7. Compress the TASK & WHY bans & forbidden-conclusions to one line each. For every BANNED APPROACH and FORBIDDEN CONCLUSION, keep the RULE verbatim - what is forbidden + the running ×N count + the (S#) that earned it - and collapse any multi-paragraph justification essay to a see S# pointer. Shape: ❌ <one-line rule> - /bad'd ×3 (S1, S2, S5), see S5. Drop NO ban, change NO count, soften NO wording of the rule itself; only the back-story prose leaves (it is in that session's block + the archive). A 13-line ban becomes one line; a ban already one line stays. TASK & WHY's task + WHY paragraphs are untouched - only the ban/forbidden lists compress.

8. Prune CARRIED-FORWARD CRITICAL DATA and Files mandatory to read of dead weight. From CARRIED-FORWARD, DROP every item whose work is resolved/committed or whose axis is superseded/refuted (the entry or its session says "DEAD" / "REFUTED" / "lives only in the archive" / "in-code + archived") - those are history, preserved in the archive, not a standing obligation. KEEP every genuinely-live reusable map in full detail (the DO NOT REDISCOVER map rule governs - never collapse a live map to a label). From Files mandatory to read, remove must-reads for any path fully closed this hunt.

9. Enforce the ceiling: count with a tool, then descend the ladder until it fits. Count the lines of the live document (wc -l). At 700 lines or fewer, you are done. At more than 1500 lines, you are not finished, however much you already collapsed. Between the two, continue down the ladder while anything on it is spent.

   Work the ladder top-down. Stop at the first rung that brings the count inside the limit. Each rung sheds something less important than the rung below it. Everything you shed stays verbatim in the pre-compact archive.

   1. Merge digest one-liners into era lines. A run of sessions that closed one finished chapter becomes a single line. That line names the range and what the era established: Sessions #1-#40 - board bring-up: INTC/LCD/timer/DMA landed + committed; all resolved. This is the largest and cheapest win on a long hunt. Dozens of lines become one, and no live fact is touched.
   2. Shrink the keep-window. Take the full blocks from 10 toward 5. If the count demands it, go to 3. Released blocks are digested, not deleted.
   3. Strip the least valuable sub-sections from surviving blocks. The optional accomplishment summary goes first, because it is already the least important part of a block. CODE STATE, DISPUTED, bans and maps stay.
   4. Drop carried-forward maps whose code is committed and in-tree. The code is the map now, so the entry only duplicates it.
   5. Reduce the coldest live maps to pointer stubs. Rank the remaining maps by how active their axis still is. Turn the coldest into one line that names the map and where to re-read it: <subsystem> master-map + call chain - see S<n> in the pre-compact archive. A stub with a real destination is not the forbidden tombstone. The map survives whole in the archive, and the stub says exactly where to find it.

   Re-count after each rung. Rungs 1 and 2 carry almost every document on their own. Treat rung 5 as a last resort, not a routine move. Four things never go at any rung, because a document without them cannot start a session:

   • the task
   • the WHY
   • every ban, with its rule and its count
   • every open defect or unresolved dispute

10. Verify, then sign off. Re-read the live document top to bottom and confirm it passes the three completion tests (§ Preservation-not-hiding) PLUS the compaction-specific checks below. Then sign off (shape in § Sign-off).

Compaction-specific completion checks (all mandatory)

• Pre-compact is complete. After the write, the pre-compact file contains the full verbatim text of EVERY session in the live doc up to the latest - first compaction by full copy, later ones by appended diff. Confirm its highest Session #X equals the live doc's highest. A gap means the diff append missed a block.
• No-map-lost. Every DO NOT REDISCOVER map AND every UI / INTERACTION GATES map that existed before compaction is still present in the live doc - either inside a surviving full block or hoisted verbatim into CARRIED-FORWARD CRITICAL DATA. A map that is now only a digest one-liner is a FAILED compaction.
• No-ban-lost. Every BANNED APPROACH and FORBIDDEN CONCLUSION that existed before compaction is still present in TASK & WHY with its ×N count and (S#) intact. Compaction may compress a ban's justification essay to a see S# pointer (step 7) but NEVER drops a ban, changes a count, or softens the rule wording. A ban that vanished or lost its count is a FAILED compaction.
• No-live-defect-lost. Every open defect / un-committable state / unresolved /verify verdict is still stated in full (surviving block or carried-forward), not reduced to a digest line.
• No-live-map-lost. Every live DO NOT REDISCOVER map kept its full reusable detail (address/module/when/how/chain-order), and every live UI / INTERACTION GATES map kept its screen order, verbatim on-screen text samples, [USER-GATED] markers, and known-good boundary. Only superseded/refuted/resolved maps were dropped (step 8), and those are in the archive. A live map reduced to a label is a FAILED compaction.
• Ceiling met. The live document is at 1500 lines or fewer, counted with a tool. There is no exception and no deferral to the user. 700 lines is the target you aimed for and normally reached. If the sessions were collapsed but the document still sits over the limit, the compaction FAILED. Two things cause that: globals that stay as essays, and a question to the user in place of the ladder.
• Cold-start still holds. A fresh session that reads ONLY the compacted live doc can still state the task, the WHY, and the bans with their counts. It can also reuse every live recorded map. On a GUI-reachable investigation it can still walk the UI path to the symptom: screen order, user gates, known-good boundary. If any of that fails, you collapsed something you had to keep. Restore it from the pre-compact file you just wrote.

Sign-off (mandatory, verbatim shape)

✅ /tracking compact complete.

• Pre-compact archive: docs/ai_checklists/pre-compact/<name>.md - <created as full copy | appended Sessions #<A>-#<B>>; now holds Sessions #1-#<N> in full.
• Compaction-log refreshed to pointer + State line (meta-history dropped).
• Collapsed Sessions #1-#<K> to digest one-liners; kept Sessions #<K+1>-#<N> in full.
• Bans compressed to rule + count + see S# (<B> bans, all counts intact). CARRIED-FORWARD pruned of <D> superseded/resolved items. Mandatory-read pruned of <R> closed paths.
• Carried forward in full: <M live do-not-rediscover maps>, <P open defects/disputes>, all bans - nothing live dropped.
• Live doc length: ~<lines> (was ~<lines>) - target ~700, hard limit ~1500. Ladder rungs applied: <none needed | 1-5>.

If any compaction-specific check fails, you must NOT sign off. Recover the dropped item from the pre-compact file into the live doc, then re-verify.

---

The pre-compact archive - history you SEARCH, never history you forget

docs/ai_checklists/pre-compact/<name>.md is the long-term memory of the investigation, and the richest source of grounding you have. The live document is a lossy summary. Compaction collapsed whole sessions to one line each. It compressed the rationale of every ban to see S#. It dropped every map whose axis was superseded. All of that text went into the archive, verbatim and in full. The archive holds the exact register dumps, the exact hook fires, the exact addresses, and the exact reasons an approach failed. This is the concept of the pre-compact file: a dump of the prior work, kept so that a recurring question gets an ANSWER instead of a new investigation.

The observed failure: an agent restores a compacted document and hits a question the live doc does not answer. It reads the digest one-liner "Session #4 - mapped the mmc polling path" as all that survives. It then spends the session on a chain that the archive already records hop by hop, three hundred lines in. The agent never opened that file. The digest line was never the record. It was a POINTER at the record, and the agent read it as a tombstone.

The obligation

If the current task needs grounding that the live document does not carry, you MUST grep the pre-compact archive BEFORE you derive that grounding yourself. This is not optional and not a judgment call. It is a mandatory prior step, of the same rank as a datasheet read before you write a register handler. When you derive from scratch what the archive already holds, you spend the money of the user a second time.

Grep the archive on ANY of these signals. The list gives examples and is not complete:

• The live doc points at a session by number (see S4, (orig Session #7), a digest one-liner), and you need what that session found.
• A ban says see S#. You must know what was tried and how it failed before you plan an alternative. An alternative that is the banned approach under a new label is still banned.
• You are about to decompile a chain, install a hook, or run a probe, and the work feels like something a prior session already did. That feeling is the trigger. Grep first.
• The question in front of you looks like one that recurs: "why does X fire before Y", "what does this register hold at boot", "which module owns this", "did we already try Z".
• A symptom in front of you resembles one that the digest names, even loosely.
• You are about to write "I could not find any record of…" or "this was never investigated". Do not write either sentence until you grep the archive for it.
• The user says "we already did this" or "didn't we solve this?". The memory of the user covers the archive. Yours covers only the live doc. Grep before you contradict the user.

How to grep it

Do NOT read the archive from top to bottom. It is unbounded by design and only grows, and that full read is the cost that compaction removed. Grep it. Then read the full session block around the hit.

• Grep for the concrete tokens of your question: the symbol name, the address, the register, the module, the on-screen text, the error string, the peripheral name. Try more than one spelling. A prior session can use a different name for a thing it did not yet understand.
• If the live doc points you at a session number, grep for that heading (Session #4). Read the whole block, not the matched line.
• If a grep returns nothing, say so ("grepped the archive for <tokens>, no hits"). Do not continue in silence, as if you never looked. An empty search is a real result, and it is what permits you to derive the fact yourself.
• What you find in the archive is evidence of the same rank as the live doc. A map, a hook fire, or a log line from a collapsed session is as usable today as on the day someone wrote it. It is not stale because it was compacted. Compaction is a length operation, never a truth operation (§ COMPACT).

The boundary - read, never write

The archive is read-only to you, always. Every rule in this skill against edits to a tracking document applies to the archive. Step 2 of an explicit /tracking compact is the only writer. Do not append to it. Do not correct it. Do not "tidy" a stale entry you find during a grep. Do not move a finding out of it into the live doc on your own initiative. If a grep finds something you think the live document must carry, that belief is not yours to act on and not yours to speak. To raise it is the same forbidden agent-initiated mention as a proposal to update, and it routes to /bad. Use what you found, continue the work, and let the user decide.

---