story-doc-drift
Skill0 starsChanged 7 months agoMITView on GitHub
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.
In this repository26 other files it gives its agents.
- story-a11y-linterSkill
- story-agentic-aiSkill
- story-alternative-solutionsSkill
- story-auto-documentationSkill
- story-bias-auditSkill
- story-business-valueSkill
- story-edge-casesSkill
- story-failure-scenariosSkill
- story-feedback-sentimentSkill
- story-gherkinSkill
- story-implementationSkill
- story-investSkill
- story-kickoffSkill
- story-nonfunctionalSkill
- story-persona-empathySkill
- story-pii-scannerSkill
- story-qaSkill
- story-questionsSkill
- story-requirements-breakdownSkill
- story-securitySkill
- story-stakeholder-impactSkill
- story-summarySkill
- story-synthetic-dataSkill
- story-telemetry-predictorSkill
- story-user-journeySkill
- story-visual-regressionSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
If none of the above, ask the user to paste the story or point to a file.
- Distinctive: line 56
Consider both internal and external documentation.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
- Text passed as arguments to this skill or slash command.
- A file reference like
@path/to/story.md— read the file first. - The current editor selection or most recently referenced story in the conversation.
- 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:
- Scope Drift — features added beyond requirements; features removed or deferred; scope negotiation during implementation.
- Implementation Drift — different technical approach than planned; architecture changes; technology substitutions.
- Requirement Drift — acceptance criteria changes mid-sprint; stakeholder feedback adjustments; edge cases discovered.
- Technical Debt Drift — shortcuts for deadline; TODOs left in code; undocumented known limitations.
Documentation Artifacts:
- Developer — README, ADRs, API docs, code comments.
- User — guides, help-center articles, tooltips, FAQs.
- Operations — runbooks, deployment guides, monitoring docs, incident response.
- Process — the user story itself, acceptance criteria, test cases, release notes.
Drift Detection Methods:
- Code Analysis — compare tests to requirements; code comments vs. specs; API contracts; config changes.
- Manual Verification — demo walkthroughs; acceptance testing; documentation reviews; stakeholder sign-off.
- 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:
- Assume drift WILL happen — plan for detection, not just prevention.
- Focus on high-impact documentation first.
- Make verification lightweight and repeatable.
- Integrate checks into existing workflows (CI/CD, PR reviews).
- Identify ownership for each document.
- Consider both internal and external documentation.
- Plan for versioning and changelog updates.
- Think about search and discoverability.
- Include rollback documentation.
- 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

