kodus-trace

name	kodus-trace
description	Use when about to edit files in an area you have not touched yet, or when the user asks why code is the way it is. Reads the decisions already recorded for those paths via `kodus trace <paths>`, so deliberate tradeoffs are not undone and settled questions are not re-litigated.

Kodus Trace

Overview

Kodus Trace records the reasoning behind changes — architectural choices, conventions, tradeoffs, deliberate deferrals — and keys them to the paths they apply to. Diffs show what changed; trace explains why.

The record covers work done by anyone on the team, not just this session, so it is the fastest way to find out what a teammate decided about a module months ago.

When to use this

Call recall before editing, not after:

• Before your first edit in a directory you have not touched this session.
• When the user asks why something is the way it is.
• When you are about to "clean up" something that looks wrong — it may be a recorded tradeoff.
• When you are choosing between two approaches in an area someone else owns.

Do not call it for a file you already recalled this session, and do not call it in a repository where kodus trace status reports nothing captured.

Reading

Reading needs no subcommand. Paths are positional on the group itself:

kodus trace src/billing/invoice.ts
kodus trace src/billing src/payments
kodus trace src/billing --limit 10

A directory returns everything scoped under it. A file returns everything whose scope covers it, including decisions recorded against its directory.

Machine-readable output, for when you want to filter it yourself:

kodus trace src/billing --format json

If a path collides with a subcommand name (enable, status, ui, …), disambiguate it with --:

kodus trace -- status

Do not invent a recall subcommand — it does not exist, and reading needs no verb.

Reading the output

Each decision carries:

• type — architectural_decision, convention, tradeoff, implementation_detail, tooling, other.
• origin — human if the person asked for it, agent if the agent chose it unprompted, collaborative if it was settled between them.
• confidence — 0 to 1, as judged during distillation.
• scope — the paths it applies to.
• source — local (recorded on this machine) or branch (came with the repository, from a teammate).
• id — the handle for forget and pin.

A tradeoff with high confidence is the most important thing on the list: it is usually the reason the code looks the way it does. Treat one as a constraint on your change unless the user says otherwise, and say so out loud rather than silently working around it.

Treat origin: human as stronger than origin: agent. Low confidence is a hint, not a rule.

Correcting the record

When a decision is plainly wrong, or the user says it is:

kodus trace forget <id>

When a decision must never be dropped from the review context pack:

kodus trace pin <id>

Do not run either of these on your own judgement alone — confirm with the user first, because both are shared corrections.

What this skill does not do

• It does not write decisions. Capture happens through hooks installed by kodus trace enable, and distillation runs on git push.
• It does not search semantically. The lookup is path matching, so pass paths, not questions.
• It does not reach the network. Everything is read from the local store and the local object database.

If nothing comes back

An empty result is a normal answer, not an error, and it exits zero. It means either nothing has been recorded for those paths yet or capture is not enabled. Check with:

kodus trace status

If it reports no sessions, tell the user they can enable capture with kodus trace enable, then carry on with the task. Do not enable it for them without being asked.