# the slopdocs way _A small habit for the artifacts your agent leaves behind._ > **slop** _noun_ > > AI slop (also known as slop content or simply as slop) is digital > content made with generative artificial intelligence that is > perceived as lacking in effort, quality, or meaning. > > — [Wikipedia](https://en.wikipedia.org/wiki/AI_slop) Your agent just spent forty minutes churning through context. It weighed three approaches, ruled out two, and shipped the third. Somewhere in that session it produced a thousand-word plan explaining its reasoning. Then the conversation ended and the plan went into the void with it. Repeat this for a week, month, or year and it gets expensive. Every new session starts from zero. The agent re-derives the same constraints and re-litigates the same trade-offs, leaving you as the only continuity between runs. The human glue holding a chain of stateless workers together. Hear me out: **keep the slop.** Slop doesn't automatically have to be a bad thing, especially when you use it in the right way. ## The repo is the agent's memory Agents don't remember anything. Each session is a blank slate with no history of how the codebase got the way it is. Their only memory is whatever you've committed to disk and whatever you've told it. Code tells you _what_ the system does, but rarely _why_. It doesn't tell you which alternatives were ruled out, or why a weird-looking architectural choice was the right call. That gap is where slopdocs live. ## Three folders is all you need The system is super simple: you can drop it into any codebase in 30 seconds and agents will pick it up straight away. ``` slopdocs/ ├── features/ │ ├── auth.md │ ├── billing.md │ └── search.md ├── bugs/ │ ├── 20260201-stale-session-cookie.md │ ├── 20260418-search-index-drift.md │ └── 20260420-csv-export-utf8-bom.md └── plans/ ├── 20260115-auth-implementation.md ├── 20260403-search-rewrite.md └── 20260420-billing-migration.md ``` ### `slopdocs/features/.md` One file per feature. A comprehensive document describing how the feature works today. The data models, the key logic, and the design decisions. These are intended to be living documents, updated as the feature changes over time. ### `slopdocs/bugs/YYYYMMDD-.md` One file per bug report, prefixed with the date. The fix lives in your commit history. The bug doc lives here because the context is what's worth keeping: the five rabbit holes the agent went down before finding the root cause. ### `slopdocs/plans/YYYYMMDD-.md` One file per planning session, prefixed with the date. Implementation plans, generated before any code is written. Kept after shipping because reading the original plan is the fastest way to understand a feature six hours or six months later. The date prefix keeps things chronological and prevents naming collisions. Features get one living document, while bugs and plans are point-in-time snapshots. ## Not everything needs a doc If you generate a slopdoc for every single commit, the folder turns into a garbage dump and your agent will ignore it. You need a high signal-to-noise ratio to get the maximum value from your slopdocs. ### Write a slopdoc when - The agent spent a while thinking about it, or there was a genuine architectural fork in the road. - A bug had a non-obvious root cause that you'll probably run into again. - You're building a new feature. Just save the plan the agent generated anyway. - A decision is going to look weird in three months and someone will be tempted to "refactor" it. ### Skip the slopdoc when - The diff is the documentation. Renames, reformats, dependency bumps. - The change is trivial and easy to revert. - Writing the doc would take longer than writing the code. - You'd be repeating something already in another slopdoc. Link to it instead. A slopdoc is a note for the next agent, not a receipt for every keystroke. > Your agent's planning doc is the most valuable thing it produced > today. The code is the cheap part. ## Write for the next agent These aren't status updates for product managers, but rather they're notes from one engineer to another. It just so happens that one of those engineers is a ~~clanker~~ LLM. Keep it dense. State the decision first, then the reasoning. Document the alternatives you tried and why they failed. It's completely fine if a doc is just a messy list of bullet points. Accurate and ugly beats polished and outdated every time. Slopdocs aren't intended for human consumption, but rather purely for the next agent to find, read and understand so that it doesn't need to re-derive the same constraints and trade-offs every time. ## Adopting it The easiest way to get started is to install the [slopdocs skill](https://github.com/ryanskidmore/slopdocs). It teaches your agent the convention, when to create docs, and where to put them. It works alongside other skills like [superpowers](https://github.com/obra/superpowers) — those skills write the content, slopdocs decides where it lives. ### OpenCode Add to your `opencode.json`: ```json { "plugin": ["slopdocs@git+https://github.com/ryanskidmore/slopdocs.git"] } ``` ### Claude Code Copy the skill into your project: ```bash mkdir -p .claude/skills/slopdocs curl -sL https://raw.githubusercontent.com/ryanskidmore/slopdocs/main/skills/slopdocs/SKILL.md \ -o .claude/skills/slopdocs/SKILL.md ``` ### Manual Create a `slopdocs/` directory at the root of your project and add a snippet to your `AGENTS.md` (or `CLAUDE.md`, `.cursorrules`, etc): ````markdown ## Documentation (slopdocs) This repo uses the slopdocs convention. Documentation lives in `slopdocs/` at the project root: - `slopdocs/features/.md` — one living doc per feature describing how it works today: data models, key logic, design decisions. Update when the feature changes. - `slopdocs/plans/YYYYMMDD-.md` — implementation plans. Write before starting non-trivial work; keep after shipping. - `slopdocs/bugs/YYYYMMDD-.md` — bug investigations. The fix lives in the commit history; the doc preserves the context worth keeping. ### Audience: agents, not humans Slopdocs are notes from one agent to the next. Human-facing docs (`docs/`, `README.md`, wiki, docs site) are separate and have different goals. Don't write slopdocs into those locations. If asked for "docs" without specifying which kind, ask. ### When to write a slopdoc - Genuine architectural fork in the road. - Bug with a non-obvious root cause. - New feature — save the plan you already generated. - Decision that will look weird in three months. ### When to skip - The diff is the documentation (renames, reformats, bumps). - The change is trivial and easy to revert. - You'd be repeating another slopdoc. Link to it instead. ### How to write one Keep it dense. State the decision first, then the reasoning. Document alternatives you tried and why they failed. Write for the next agent, not for a human to skim. Read the relevant slopdocs before making changes. ### Working with other skills Use other skills (superpowers, etc.) to write the content. Save to `slopdocs/` paths with the conventions above instead of wherever those skills would normally save. ```` Start small: a feature doc here, a bug postmortem there. In a few months, you'll have a searchable archive of why your codebase looks the way it does. You won't want to run a project without it ever again. --- Source: