Slopdocs: notes for the next clanker

As a fully-certified AI stan who uses AI almost religiously both at home and at work, I kept running into a frustrating papercut where I’d set an agent to go work on a task without much (or sometimes any) guidance and I’d tell it to go figure it out without me. This is fantastic for working on 14 tasks in parallel, but starts to become a real problem when you’re trying to figure out why one of your clankers made a certain decision or implemented something in a certain way.

A lot of agents now do pretty comprehensive planning before implementing features or making changes, but often that plan ends up in the ether and along with it, all of the context about the decision making and thinking that happened.

The stateless agent problem

Agents don’t remember anything, and sometimes they forget things you’ve told them in the very same session. Each session starts from a blank slate, and whatever you taught the last one lives in your head until you need to explain it again in the next session, the next morning, or the next branch.

You stop realizing how much mental baggage you’re carrying, and after a few weeks, you become the only reliable source of truth in the system. You end up acting as the human glue holding together a chain of sessions from the last few weeks.

Diffs don’t capture the thinking

Code goes into git, but the reasoning, thinking and exploration behind it rarely does. A diff tells the next reader what changed, but it doesn’t tell them what wasn’t tried, or why a weird-looking workaround was actually the best approach.

A few weeks later, the code looks normal and the alternatives look obvious. Someone, whether an agent or a human, refactors the weirdness away, and the original constraint resurfaces soon after. The reasoning for that weird choice had been written down in the original plan. It just wasn’t anywhere reachable by the next session.

Let the slop flow!

I stopped trying to tidy up all of the AI-generated slop documentation and started letting it hang out. Initially I didn’t have any kind of methodology or system in place (which was about as disastrous as you imagine), but I quickly adopted a “slopdocs” convention where I (read: the robot) tidied away all of the messy documentation in a slopdocs directory.

My approach uses three folders:

slopdocs/
├── features/
├── bugs/
└── plans/

Files in bugs/ and plans/ get a date prefix so they act as point-in-time snapshots, while features get one living document that gets updated over time. None of it is intended for humans to consume.

I wrote the full convention up at slopdocs.dev. It includes an agent skill that drops into any codebase in a few seconds. The skill teaches your agent the directory structure and, more importantly, when to skip writing a document. If you save every output, the folder becomes a garbage dump and your agent stops being able to wrangle it.

It plays nicely alongside skills that handle the actual writing, like superpowers. Slopdocs just decides where the output goes. My agent now reads the existing slopdocs before touching an area, and the plethora of documentation becomes a shared history at a repository level.