trace-my-code

Files (21)

• README.md
• SKILL.md
• ARCHITECTURE.md · hooks/
• doc-drift.sh · hooks/
• doc-drift.yml.example · hooks/
• reuse-first-hooks.json · hooks/
• reuse-first-nudge.sh · hooks/
• trace-eval.sh · hooks/
• trace-stats-command.sh · hooks/
• install.md
• auto-update-contract.md · references/
• bootstrap.md · references/
• doc-splitting.md · references/
• multi-repo.md · references/
• obsidian-format.md · references/
• onboarding.md · references/
• reuse-first.md · references/
• routing-rule.md · references/
• adr-template.md · templates/
• architecture-template.md · templates/
• domain-template.md · templates/

SKILL.md (first lines)

# Trace My Code

**What it is:** an agentic loop that keeps a **trace of your system** — the
**domain flow** (what happens, in what order, under which conditions) layered over
the **code structure and patterns** (where it lives, how it's built, why) — as
curated, navigable Markdown. The trace is the context a coding agent reads instead
of re-deriving the system from raw files on every task.

Inspired by [Andrej Karpathy's "LLM Wiki" idea](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
— an LLM-compiled, interlinked **knowledge-graph wiki** kept current by an agent —
applied here to a codebase instead of a research corpus.

**Why it pays off:**

- **Feature development** — an agent plans a change from the trace (flow + files +
  gotchas) in a couple of reads instead of crawling dozens of files and guessing.
- **Pattern adherence** — the trace records established patterns and the _why_ (ADRs),
  so new code follows them instead of inventing a parallel approach.
- **Refactor / restructure** — knowing the real end-to-end flow and its invariants up
  front makes large refactors safe; you change with the contract in view.
- **Always current** — a drift check (git hook or CI) flags or refreshes the trace
  when the code it describes changes, so it never quietly rots into a lie.

**Proven across repos.** Bootstrapped on a ~100k-line Next.js app, the trace measures (via the
bundled `trace-eval`, below) **~22× smaller** per area than the code (~3.7k vs ~81k tokens —
fits in context where the code doesn't) at **98% citation accuracy** across 237 citations. On a
cold-vs-trace A/B — 5 planning tasks across that app **and** [honojs/hono](https://github.com/honojs/hono)
— the trace agent used **−64% input, −33% cost, −59% time** (medians), opened **~⅓ the files**,
for the *same correct plan*; in an opaque domain it also dodged a wrong-pattern rebuild the cold
agent shipped. In the same session an agent built, tested, and shipped a brand-new tool reading
**only** the trace to plan it (_"Phase 0 genuinely replaced crawling… the trace gave me everything"_),
passed 14/14 tests, and the pipeline caught a real bug a blind crawl ships. One-time cost; a crawl
is re-paid every task.

## Start here (onboarding router)

**Invoked without a clear task** — a bare `/trace` or `/trace-my-code`, "set this up", "where do
I start", or a fresh install? **Don't dump the modes and guess.** Follow
`references/onboarding.md`: read the repo's trace state in one pass (does `docs/DOMAIN.md` / any
`ARCHITECTURE.md` exist; the `trace-eval` grade, broken citations, open `_TODO_`s, `--gaps`;
whether the drift loop is wired; the routing rule), then **route**:

- **No trace** → guide first-run setup: bootstrap → **wire the loop** (recommend the CI Action;
  local pre-push fallback) → routing rule → grade.
- **Trace exists** → show the `trace-eval` report, then propose the **single highest-value next
  step** (fix broken citations / confirm `_TODO_`s worst-first / bootstrap the biggest gap / wire
  the loop / add the routing rule / else switch to reuse-first).

State is **derived from the repo each run, never stored** — the trace itself is the state. A
clear task (e.g. "document the auth module", "refresh the docs for X") skips the router and goes
straight to the matching mode below.

## The trace (what gets written)

1. **`docs/DOMAIN.md`** — the map: domains / bounded contexts, the aggregates and
   ubiquitous language, and how contexts connect.
2. **Per-area `ARCHITECTURE.md` / `DATA_FLOW.md`** (next to the code, from
   `templates/architecture-template.md`) — the flow, the **patterns & extension points**
   (the canonical example to copy + where to plug a new one in), the **invariants &
   absences** (limits, defaults, magic numbers, and what is _not_ enforced), the
   **external / out-of-repo** anchors, and the gotchas — with **symbol-anchored**
   citations.
3. **`docs/adrs/*.md`** — the _why_ behind non-trivial decisions.
4. A **routing rule** in the repo's `CLAUDE.md` / `AGENTS.md` telling agents to read
   the trace before touching an area (`references/routing-rule.md`).

Everything is plain Markdown, **stored hierarchically to mirror the codebase** and
**Obsidian-vault compatible** (YAML frontmatter + `[[wikilinks]]`), so `docs/` opens
as a visual, linked map — index -> context -> area -> decision. As the trace grows,
split oversized files behind an index (`references/doc-splitting.md`).

## Multi-repo / microservices

A trace is per-repo, but flows cross service boundaries. Each repo keeps its own trace
rooted at `docs/DOMAIN.md`; when service A calls service B, A's doc carries an **anchor
link to B's root trace doc** — a relative path when the repos sit side by side locally
(e.g. `[[../service-b/docs/DOMAIN.md]]`), or a URL otherwise. Following those anchors
lets an agent walk an **end-to-end cross-service flow** when the repos are checked out
together: no central index, just links between roots. See `references/multi-repo.md`.

## Modes

- **Mode 0 — bootstrap** (`references/bootstrap.md`): on a fresh repo, generate the
  initial trace (DOMAIN.md + per-area ARCHITECTURE.md skeletons + seed ADRs), grounded
  in code with `_TODO: confirm_` on anything unverified. A draft to curate — it kills
  the blank page. Then curate **worst-first**: `trace-eval` ranks the weak docs and names
  each missing criterion; `--gaps` lists significant dirs still to bootstrap.
- **Mode A — author / maintain**: write or update a doc/ADR from the **code + schema**, cite by
  symbol, link related nodes with `[[wikilinks]]`. Capture the _why_ in ADRs. **Harvest what was
  missing** (the `#`-key reflex, applied to architecture docs) — after each task, run this reflection
  and fold every hit into the right section of the area doc:
  - re-derived a pattern the trace should have named? → **Patterns & extension points**
  - hit a gotcha, ordering trap, or stale comment? → **Gotchas**
  - found an invariant, limit, or magic number? → **Invariants & absences** (cite its source)
  - learned a 3rd-party system from an import? → **External / out-of-repo**
  - a citation no longer resolved while you worked? → fix it in place

  This is the trace's _experience-truth_, kept current the way the drift hook keeps its _code-truth_
  current. `trace-eval`'s **what-to-curate** worklist (above) tells you which docs to harvest into first.
- **Mode B — auto-update on drift** (`references/auto-update-contract.md`): **bootstrap
  wires this on by default** (CI workflow if the repo has `.github/`, else a local pre-push
  hook). It finds **code** changes in a traced area and **rewrites** the affected docs —
  grounded, surgical — committing to the **working/PR branch** (PR branch in CI, current
  branch locally), **never directly to `main`**. Degrades to **flag** (warn-only) if no
  Claude credential is available, or set `TRACE_MY_CODE_MODE=flag` to opt out of auto-commits.
- **Mode C — reuse-first development** (`references/reuse-first.md`): before writing any
  new code, consult the trace, then climb the reuse ladder — **YAGNI → reuse → extend →
  stdlib → native → installed dep → one line → (only then) minimum new** — while holding
  the **safety floor** (validation, error handling, security, accessibility, and anything
  explicitly requested are never cut). This is the payoff mode — it's what stops an agent
  reinventing a helper/component/flow the repo already has, or over-building what a native
  feature already does.

## The Iron Law (Mode C)

```
NO NEW CODE WITHOUT A REUSE INVESTIGATION FIRST
```

From kgohil/trace-my-code, MIT.