Spec Rot: Why Your AI Agent's Task Spec Becomes a Liability Over Time

Your codebase has technical debt. Your AI agent has spec rot.

The task spec that launched your agent on day 1 was accurate then. By day 30, reality has moved on:

• New tools were added
• Scope quietly expanded
• Constraints changed
• Edge cases were discovered — and hardcoded around, not documented

But the spec? Still frozen.

What Spec Rot Looks Like

Spec rot is invisible until it isn't. Symptoms:

1. The agent does the right thing for the wrong reason — it's working around a stale rule, not following a current one
2. Edge case accumulation — you've added 12 "except when..." clauses to the task spec without removing the original rule they contradict
3. Scope creep without documentation — the agent now does 3 things, but the spec only describes 1
4. Stale constraints — the agent is avoiding an API that you've since fully integrated

The Fix: Treat Task Specs Like Living Docs

Task specs aren't set-and-forget configuration. They're agreements between you and your agent — and agreements need maintenance.

Three practices that eliminate spec rot:

1. Version Your Task Specs

{
  "spec_version": "1.4",
  "last_reviewed": "2026-03-08",
  "task": "Monitor Coinbase Advanced for arbitrage windows",
  "scope": ["read price feeds", "calculate spread", "flag to outbox.json"],
  "never": ["execute trades without approval"],
  "done_when": "spread analysis written to outbox.json",
  "changelog": [
    "1.4: Added never-trade constraint after near-miss on 2026-03-01",
    "1.3: Expanded scope to include Base chain",
    "1.0: Initial spec"
  ]
}

The changelog is the most important field. It tells future-you why the spec looks the way it does.

2. Review Weekly

10-minute Sunday ritual:

• Does the task still match what the agent actually does?
• Are there constraints we're enforcing that no longer apply?
• Are there edge cases we've been working around that need to be formalized?
• Is the scope still bounded, or has it expanded without documentation?

3. Retire Stale Specs

A spec that nobody maintains is worse than no spec. It gives false confidence while the agent operates on reality instead of documentation.

If a spec hasn't been reviewed in 30 days, mark it status: stale and trigger a review before the next run.

The Audit Question

Here's the one question that surfaces spec rot immediately:

"If a new agent read this spec cold and ran it today, what would go wrong?"

Walk through it. Every "that wouldn't work because..." is a spec rot instance.

Real Numbers

After adding weekly spec reviews to our 5-agent system:

• Task spec version conflicts: 12 per month → 0
• Scope creep incidents: 4 per month → 0
• "The agent did the right thing, wrong context" errors: -71%

The reviews take 10 minutes. The compound benefit is enormous.

---

If you're running AI agents in production, the full task spec template (with versioning, changelog, and weekly review checklist) is in the Ask Patrick library: askpatrick.co/library