---
title: "What a repo hygiene pass actually catches"
description: "Shorter context is one result. The harder work is checking that instructions, work items and tests still describe what an agent actually does."
date: 2026-09-15
canonical: https://ax1om.ai/blog/what-a-repo-hygiene-pass-catches
---

A repo hygiene pass checks whether an agent can find the current work, load only the context it needs, and produce evidence for what it says is done. Removing old files is only part of that work.

## Start with what loads before the task does

An instructions file tends to grow one useful sentence at a time. Eventually a session pays to read decisions, procedures and history that have nothing to do with its task.

Separate the material by when it is needed. Keep standing rules in a short entry file. Keep the current condition and work queue together. Follow references when a task needs them. Invoke reusable skills rather than loading every procedure at startup.

One internal ax1om hygiene audit recorded eager context falling from **14,787 to 4,726 tokens**, and session-start reads falling from **26,560 to 6,914 tokens**. Those are the AX-1075 measurements for one repo. They are not a multi-repo benchmark or a promise about a new installation.

A budget check helps prevent that improvement from eroding. Be explicit about its method: a character-count estimate is a useful limit, but it is not a measured tokenizer result.

## A passing test can miss the thing that matters

During review of the GTM Repo foundation, all 35 existing reader tests passed. A two-item HTML list still became an empty list. Table headers disappeared. Nested lists lost text and hierarchy.

The tests checked that a list or table node existed. They did not establish that the content survived.

The repair changed what the tests asked. Does the output contain both list items? Does the child remain inside its parent? Does the table retain its header and empty cells? Do equivalent Markdown and HTML produce the same document structure?

The same distinction applied to the work board. A validator accepted incomplete rows and empty completion evidence. A successful exit was not enough. Negative fixtures were needed to show that malformed work was refused.

## Fix the rule at the point where it can fail

A folder move changed the personal-skill path, but the ignore rule still named the old directory. The prose continued to say personal work was private. The mechanical protection no longer matched it.

That is why a hygiene pass follows the relationship, not just the file. When a folder moves, check its ignore rules and references. When a skill gains a dependency, check its connector note and verification date. When a task is marked done, check its evidence.

Use the same checks locally and in CI. Keep a failed check actionable: name the missing prerequisite and where to obtain it. A variable being present is only a local prerequisite check, not proof that a remote credential has the right permissions.

## Leave the next session a current condition

End with a short account of what changed, what was verified, and what remains open. Keep history available without making every session read it. Retire instructions deliberately and leave a pointer when someone might still follow an old path.

The [GTM Repo](/resources/gtm-repo) puts this foundation in one place: loading discipline, work-item and artifact checks, skill prerequisites, and document readers. Its page separates the implemented foundation from the ceremonies, mappings and vendor research still to come.

An archive is a snapshot. Keep the update procedure with it, preserve your own state, and review changes before replacing a customized copy.