the slopdocs way

A small habit for the artifacts your agent leaves behind.

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

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/
├── 20260201-stale-session-cookie.md
├── 20260418-search-index-drift.md
└── 20260420-csv-export-utf8-bom.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/
├── 20260115-auth-implementation.md
├── 20260403-search-rewrite.md
└── 20260420-billing-migration.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. It teaches your agent the convention, when to create docs, and where to put them. It works alongside other skills like superpowers — those skills write the content, slopdocs decides where it lives.

Add to your opencode.json:

opencode.json

{
  "plugin": ["slopdocs@git+https://github.com/ryanskidmore/slopdocs.git"]
}

Restart OpenCode. The skill is loaded automatically when the agent writes or decides whether to create documentation.

Copy the skill into your project:

terminal

mkdir -p .claude/skills/slopdocs
curl -sL https://raw.githubusercontent.com/ryanskidmore/slopdocs/main/skills/slopdocs/SKILL.md \
  -o .claude/skills/slopdocs/SKILL.md

The skill will be available on the next session start.

Create a slopdocs/ directory at the root of your project and add this snippet to your AGENTS.md (or CLAUDE.md, .cursorrules, etc):

AGENTS.md

## Documentation (slopdocs)

This repo uses the slopdocs convention. Documentation lives
in `slopdocs/` at the project root:

- `slopdocs/features/<feature>.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-<feature>.md` — implementation
  plans. Write before starting non-trivial work; keep after
  shipping.
- `slopdocs/bugs/YYYYMMDD-<short-slug>.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.