Skip to main content

Drift capture

When implementation diverges from specification, the difference is captured as a drift document rather than silently ignoring the gap.

Drift lifecycle​

  1. Detection — Agent or engineer notices spec says X but implementation does Y
  2. Documentation — Create .context/drift/drift-{topic}.md describing the gap
  3. Resolution — Either update the spec to match reality, or fix the code to match spec
  4. Archival — Move resolved drift doc to .context/drift/archive/

Drift document format​

# Drift: {topic}

## Spec says
What the specification describes.

## Implementation does
What actually exists.

## Recommended resolution
Update spec / fix code / accept drift with rationale.

CI enforcement​

When a drift doc is archived, the archival PR must also include:

  • Updated spec (if spec was wrong)
  • Updated context files (if architecture changed)
  • Updated docs (if docs/ content needs updating)

What's next​