Insights harvest — when the advice is already in your repo

Claude Code will read your own usage back to you and tell you what to fix. The first time I ran it across months of sessions, it handed me a list of things I should build.

Most of them I had already built.

Not approximately. There was a documented skill, in a folder, with a name, doing the exact thing being recommended. The report could not see any of it, because it reads transcripts rather than the repository, so from where it sat the absence of a practice and the presence of an unused practice look identical.

That is the whole finding, and it generalizes well past this one tool. The gap between the advice you receive and the improvement you get is almost never invention. It is enforcement.

Grade the advice against what exists

So the harvest is not "implement the suggestions." It is a grading pass, one line per recommendation, into three buckets.

Already. The thing exists and is used. Cite where it lives and move on. This is the largest bucket every time and it is not a waste, because knowing which of your practices are invisible from the outside is itself worth having.

Partial. The thing exists and is not reliably used. This is the interesting bucket, and it is where nearly all the real value sits. A rule written down and skipped is worse than no rule, because it creates the feeling of having addressed something.

Gap. The thing genuinely does not exist. Rare, and these become real work.

The grading takes an hour and converts an impressive-looking list into a short, honest one.

Partial is a mechanism problem

When something lands in Partial, the instinct is to write the rule more clearly, or more emphatically, or in a more prominent file. I have done all three. It does not work, and I can say precisely why it does not work.

I had a rule against authoring file content through shell heredocs, because they silently mangle regex escapes and Windows paths. The rule was correct, it was written down, and the corruption kept happening for weeks after it was written. The reason turned out to be structural: my sessions were being handed standing instructions that said the opposite, to prefer shell tools over file tools. Every turn, the environment argued against the rule. No amount of rewriting the rule was going to win that argument.

The fix was not better prose. It was naming which instruction wins when the two conflict, and then a commit hook that denies the specific shape.

That is what Partial almost always means. Not that the rule was unclear, but that following it was more expensive than not following it, and nothing made the cheap path harder.

File it as an artifact or it did not happen

A harvest that ends in a summary produces nothing. Each surviving item becomes one of three durable things, and if it cannot become one of them it was not a real finding.

A rule in the file the agent actually reads, written as the failure it prevents, with the date it cost something.

A gate that denies the bad shape at commit or in CI, which is the only form that survives inattention.

A goal with a verifier, for anything too large to be either.

Then the outcome gets tracked, because the second harvest is the one that tells you the truth. If an item graded Partial in one pass and Partial again in the next, the mechanism you added did not work, and that is much more useful to know than the original recommendation was.

The part I got wrong

I used to publish these reports. It felt like transparency and it read as content, and for a while I thought that was the point of running them.

It was not. The reports contain the shape of how I work, including the parts that are somebody else's business, and the value to me was never in the publishing. I retired that in August and put a gate on it so a future session cannot helpfully restore it. The reports are archived privately now and the harvest is the only output that leaves the room.

If you take one thing: the artifact is the change to the system, not the document about the change to the system.

Why this matters if you build with AI agents

You will be given a great deal of advice by tools that cannot see your codebase, and it will be well-written, plausible, and frequently redundant. Acting on it directly means rebuilding things you own and mistaking motion for improvement.

Grading it first costs an hour and changes the question from "what should I add" to "what do I already have that is not being used, and what would make using it the path of least resistance." That second question is harder, less satisfying, and the only one that compounds.