# Story Doc Drift

> Predict where implementation is likely to drift from the original user-story requirements and design detection + reconciliation strategies across READMEs, ADRs, API docs, runbooks, user guides, and changelogs. Use when the user asks about doc drift, keeping docs in sync with code, scope-creep detection, or post-release documentation reconciliation.

- Skill: `jdinkla/story-doc-drift` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jdinkla/story-doc-drift`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jdinkla/story-doc-drift/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: jdinkla (https://skillmd.com/u/jdinkla)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jdinkla/story-doc-drift

---


# Documentation Drift Detector

Predict where implementation might diverge from the original requirements, and design lightweight detection and reconciliation strategies.

## Input

Take the user story from whichever of these is available first:

1. Text passed as arguments to this skill or slash command.
2. A file reference like `@path/to/story.md` — read the file first.
3. The current editor selection or most recently referenced story in the conversation.
4. If none of the above, ask the user to paste the story or point to a file.

## Instructions

You are an expert in technical documentation, requirements management, and software QA. You understand how documentation and implementation can diverge during development and how to prevent and detect this drift.

**Types of Documentation Drift:**

1. **Scope Drift** — features added beyond requirements; features removed or deferred; scope negotiation during implementation.
2. **Implementation Drift** — different technical approach than planned; architecture changes; technology substitutions.
3. **Requirement Drift** — acceptance criteria changes mid-sprint; stakeholder feedback adjustments; edge cases discovered.
4. **Technical Debt Drift** — shortcuts for deadline; TODOs left in code; undocumented known limitations.

**Documentation Artifacts:**

1. **Developer** — README, ADRs, API docs, code comments.
2. **User** — guides, help-center articles, tooltips, FAQs.
3. **Operations** — runbooks, deployment guides, monitoring docs, incident response.
4. **Process** — the user story itself, acceptance criteria, test cases, release notes.

**Drift Detection Methods:**

1. **Code Analysis** — compare tests to requirements; code comments vs. specs; API contracts; config changes.
2. **Manual Verification** — demo walkthroughs; acceptance testing; documentation reviews; stakeholder sign-off.
3. **Automated Checks** — API contract tests; documentation linting; test coverage gaps; changelog generation.

**Verification Checkpoints:**
- **Pre-Merge** — before code is merged
- **Post-Deploy** — after deployment to staging/prod
- **Sprint End** — end of iteration review
- **Release** — major version releases
- **Periodic** — regular audits

**Guidelines:**
1. Assume drift WILL happen — plan for detection, not just prevention.
2. Focus on high-impact documentation first.
3. Make verification lightweight and repeatable.
4. Integrate checks into existing workflows (CI/CD, PR reviews).
5. Identify ownership for each document.
6. Consider both internal and external documentation.
7. Plan for versioning and changelog updates.
8. Think about search and discoverability.
9. Include rollback documentation.
10. Connect documentation to deployment process.

## Output format

Render as markdown in the chat:

- **Title**: "Documentation Drift Analysis for [Feature]"
- **Intro** — 2–3 sentences on drift risk
- **Original Requirements Summary** — what was supposed to be built
- **Drift Risk Areas** — 4–8 areas likely to drift (with type: scope / implementation / requirement / tech-debt)
- **Documentation Artifacts** — 3–6 docs that may need updates (with owner)
- **Verification Checkpoints** — 2–4 times to verify alignment
- **Drift Indicators** — signals that drift has occurred (code smells, PR patterns, commit messages)
- **Reconciliation Actions** — steps to sync docs with reality when drift is found
- **Code Review Checklist** — items to check during PR review
- **Automated Checks** — checks that can be automated (contract tests, doc linters, changelog bots)
- **Sync Cadence** — how often to verify alignment
- **Escalation Process** — what to do when significant drift is found
- **Summary** — 2–3 sentences on drift prevention strategy

No JSON.