Agentic workflows breed a design doc per feature. Periodically fold them into one truth and delete the rest.
The team friction Agentic workflows — superpowers, feature-dev, and friends — drop a design doc for every feature into the repo. Useful in the moment, but they pile up. As the codebase evolves they go stale and start contradicting each other and the code. Now every agent that reads them inherits a heap of conflicting, half-true context, and the team can’t tell which doc still describes reality. The docs meant to give agents context start poisoning it.
The pattern The team treats these per-feature docs as temporary by design. Periodically — in a dedicated session — someone (with an agent) compacts the pile into a single, consistent interpretation, reconciles the contradictions against the current code, and deletes the original feature docs. One coherent account replaces a drift of stale ones. It’s documentation debt, paid down before it compounds.
Why it works with AI An agent’s output is only as good as the context it reads, and contradictory context is worse than none — it yields confident, wrong work. Compaction keeps the agent-facing knowledge base small, current, and non-conflicting, which is the condition agents perform best in. And the compaction itself is agent-friendly: summarising and reconciling many documents is squarely in its wheelhouse.
Watch-outs Compaction is a judgement call, not a merge script — the team owns deciding which version is true now. Do it on a cadence, before the pile gets unmanageable. And promote anything durable first — decisions to ADRs, lasting product knowledge to product memory — so you compact transient docs, not institutional memory.
Related Agent-written shared docs · Product memory · Consistent, excellent codebase · ADRs — record the why