EP 04

context.md Keeps Evolving


May 2026·4 min read·#documentation#architecture#logging

I didn't write a single line of code today.

And yet Pepper changed a lot.


The document is the system

context.md wasn't something you write once and lock in. When thinking shifts, the document changes first — and only then do you call Claude Code. That order matters. Do it the other way around and the code gets tangled.

Today alone, the version went from 0.4.0 to 0.9.0. Five bumps in a single day.


The scariest thing isn't getting an error

This was a few days ago. I was fixing the reporting feature when something else started acting wrong. I didn't know what I'd touched. I didn't know where it had broken. All I knew was: something doesn't work.

This is the biggest vulnerability for non-developers. An error fires and you can't read it — can't tell where it came from or why. You fix one thing at the edges, and something connected to it quietly breaks somewhere else. That accumulates. And at some point, the whole thing is a knot.

So getting an error without knowing it — that was the real fear. Not the error itself.


pepper_logs — Pepper's black box

Today I dealt with this head-on.

pepper_logs
. A single observation point for everything Pepper has ever done. User requests, background workers, LLM calls — all of it piles into one table.

What was requested. Did it succeed or fail. If it failed, why. If code generation failed in STATE B, all three attempts are there, error messages and all.

Later, when Pepper behaves strangely, I can say this to Claude Code:

"Find today's errors in pepper_logs."

That's it. I don't have to be able to read the errors myself. If the logs are there, Claude Code reads them. If the logs aren't there — neither of us knows anything.

It's like trying to find the cause of a plane crash without a black box.


STATE C issues need to arrive as instructions

Same thread of thinking — I revisited STATE C.

When Builder fails three times, a GitHub issue gets auto-generated. But what actually needs to be inside that issue for me to do something useful with it?

The code and errors from all three attempts, Pepper's analysis of why it failed, and — the instructions for Claude Code, already written out.

My job is one thing: attach context.md and throw the issue body at Claude Code. Not to understand the error myself — Pepper analyzes it and builds the bridge for me. That's the kind of vibe-coding that actually fits how I work.


Google I/O was today

Gemini 3.5 Flash released. Half the price of the previous generation, higher performance. Gemini 2.0 Flash shuts down June 1st — flagged it as an urgent migration item.

And Google announced Information Agents. Background agents running 24/7, triggering notifications when conditions are met. The

monitoring_tasks
+
proactive-worker
architecture I designed this morning — that's exactly it. Confirmation that the direction is right.


No code today. Pepper grew anyway.

Tomorrow is an implementation session.