Agent skill
skill-scope-drift
Scope drift detection — compares actual diff against stated intent to catch scope creep and missing requirements. Informational only, never blocks.
Install this agent skill to your Project
npx add-skill https://github.com/nyldn/claude-octopus/tree/main/skills/skill-scope-drift
SKILL.md
Scope Drift Detection
Compares the actual code diff against stated intent (TODOS.md, PR description, commit messages) to surface scope creep and missing requirements before the full code review runs.
This is informational only — it never blocks a review or merge. Some scope drift is intentional ("I saw a bug while working on the feature"). The goal is awareness, not enforcement.
When to Run
- Automatically as part of
/octo:deliverand/octo:review(Dev context only) - Manually via: "check scope drift", "scope check", "did I drift?"
- Skipped for Knowledge context reviews (no diff to compare)
How It Works
Step 1: Gather Stated Intent
Collect intent signals from multiple sources (any that exist):
# 1. TODOS.md / TODO.md in project root or .octo/
TODOS_FILE=""
for candidate in TODOS.md TODO.md .octo/TODOS.md; do
[[ -f "$candidate" ]] && TODOS_FILE="$candidate" && break
done
# 2. PR description (if on a branch with an open PR)
PR_BODY=""
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
if [[ -n "$CURRENT_BRANCH" && "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" ]]; then
if command -v gh &>/dev/null; then
PR_BODY=$(gh pr view "$CURRENT_BRANCH" --json body --jq '.body' 2>/dev/null || echo "")
fi
fi
# 3. Commit messages on this branch (since divergence from main/master)
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
COMMIT_MESSAGES=$(git log --oneline "${BASE_BRANCH}..HEAD" 2>/dev/null || echo "")
# 4. .octo/STATE.md context (if using Double Diamond workflow)
STATE_CONTEXT=""
if [[ -f ".octo/STATE.md" ]]; then
STATE_CONTEXT=$(cat .octo/STATE.md 2>/dev/null || echo "")
fi
Step 2: Gather Actual Diff
# Files changed on this branch vs base
DIFF_STAT=$(git diff --stat "${BASE_BRANCH}..HEAD" 2>/dev/null || git diff --stat HEAD~1 2>/dev/null || echo "")
DIFF_FILES=$(git diff --name-only "${BASE_BRANCH}..HEAD" 2>/dev/null || git diff --name-only HEAD~1 2>/dev/null || echo "")
DIFF_SUMMARY=$(git diff --shortstat "${BASE_BRANCH}..HEAD" 2>/dev/null || git diff --shortstat HEAD~1 2>/dev/null || echo "")
Step 3: Analyse for Drift
Compare intent signals against the actual diff. Look for two categories:
Scope Creep Detection
Files or changes that don't align with any stated intent:
- Unrelated directories: Changes in modules/directories not mentioned in TODOS or commit messages
- Feature additions: New capabilities, APIs, or UI elements not described in intent
- "While I was in there" changes: Formatting, refactoring, or dependency updates mixed with feature work
- Config/infra changes: Build config, CI, or dependency changes bundled with feature code
Missing Requirements Detection
Items from stated intent not reflected in the diff:
- Unchecked TODOS: Items in TODOS.md not addressed by any changed file
- Mentioned but missing: Features described in PR body or commit messages with no corresponding code changes
- Test gaps: Features implemented but no corresponding test files changed
- Doc gaps: API or behaviour changes with no documentation updates
Step 4: Output Structured Report
## Scope Drift Check
**Status:** `CLEAN` | `DRIFT DETECTED` | `REQUIREMENTS MISSING` | `DRIFT + MISSING`
### Intent Summary
Sources checked: TODOS.md ✓ | PR description ✗ | Commit messages (N commits) ✓ | STATE.md ✗
- [Summarise the stated intent in 2-3 bullet points]
### Delivered Summary
- N files changed across M directories
- [Summarise what the diff actually does in 2-3 bullet points]
### Scope Creep (if any)
| File/Directory | Why it looks unrelated | Severity |
|---------------|----------------------|----------|
| `path/to/file` | Not mentioned in any intent source | Low/Medium/High |
### Missing Requirements (if any)
| Requirement | Source | Evidence |
|------------|--------|----------|
| [Requirement text] | TODOS.md line N | No matching file changes found |
### Recommendation
- [One-line recommendation: "Clean — proceed to review" or "N items drifted, M requirements missing — review with awareness"]
MANDATORY COMPLIANCE — DO NOT SKIP
When this skill is invoked, you MUST execute the scope drift analysis pipeline. You are PROHIBITED from:
- Skipping the diff comparison and guessing whether drift occurred
- Reporting "no drift" without actually checking available intent sources
- Blocking or gating reviews based on drift results (this is informational only)
Integration Points
In /octo:deliver (flow-deliver)
Run scope drift check between Step 1 (context detection) and Step 4 (orchestrate.sh execution). Insert as Step 1c: Scope Drift Check (Dev context only):
After detecting Dev context and subtype:
1. Run scope drift analysis
2. Display the structured report
3. Proceed to Step 2 (visual indicators) regardless of result
The scope drift report becomes part of the validation context passed to the review providers.
In /octo:review (skill-code-review)
Run scope drift check as a pre-review step. Display results before the multi-LLM review pipeline begins.
In /octo:staged-review
Run scope drift check during Stage 1 (spec compliance). The drift report supplements the spec compliance check — drift detection catches lightweight intent signals that formal specs may not capture.
Configuration
No configuration needed. The skill auto-detects available intent sources and adapts:
- No TODOS.md? Skip that source.
- No PR? Skip PR body.
- No git history? Skip commit messages.
- All sources missing? Report "No intent sources found — scope drift check skipped."
If zero intent sources are found, the skill exits silently rather than producing a vacuous report.
Examples
Clean Result
## Scope Drift Check
**Status:** CLEAN
### Intent Summary
Sources: TODOS.md ✓ | Commit messages (4 commits) ✓
- Add retry logic to provider dispatch
- Handle 429 rate limit responses
### Delivered Summary
- 3 files changed: provider-router.sh, lib/resilience.sh, tests/unit/test-resilience.sh
- Added error classification and exponential backoff
### Recommendation
Clean — proceed to review.
Drift Detected
## Scope Drift Check
**Status:** DRIFT DETECTED
### Intent Summary
Sources: TODOS.md ✓ | PR description ✓ | Commit messages (7 commits) ✓
- Fix login page CSS alignment
- Add loading spinner to submit button
### Delivered Summary
- 8 files changed across 4 directories
- Fixed CSS alignment, added spinner, AND refactored auth module, updated 3 unrelated test fixtures
### Scope Creep
| File/Directory | Why it looks unrelated | Severity |
|---------------|----------------------|----------|
| `src/auth/oauth.ts` | Auth refactor not in any intent source | Medium |
| `tests/fixtures/users.json` | Test fixture updates unrelated to CSS/spinner | Low |
| `package.json` | Dependency bump not mentioned | Low |
### Recommendation
3 items drifted — review with awareness. Consider splitting auth refactor into a separate PR.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
skill-iterative-loop
Run tasks in a loop until goals are met — use for iterative refinement, polling, or convergence. Use when: AUTOMATICALLY ACTIVATE when user requests iterative execution:. "loop X times" or "loop around N times". "loop around 5 times auditing, enhancing, testing"
skill-context-detection
Auto-detect work context (Dev vs Knowledge) for workflow tailoring
skill-code-review
Expert multi-AI code review with quality and security analysis
skill-doc-sync
Post-ship doc sync across project markdown. Use when: "sync docs", "update docs", "document changes", "release notes".
skill-meta-prompt
Craft better prompts using proven optimization techniques — use when your prompt needs refinement. Use when: Use PROACTIVELY when user wants to:. "create a prompt for", "write a prompt for". "optimize this prompt", "improve this prompt"
octopus-quick
Quick execution for ad-hoc tasks without workflow overhead. Use when: Use this skill when user says "quick fix", "ad-hoc task", or explicitly. requests fast execution without full workflow overhead.
Didn't find tool you were looking for?