# Narrow The Scope > Notice live, mid-session, when repeated attempts at one problem aren't converging — the same error recurring, several edit-and-guess cycles on the same file or area, or a fix that keeps growing instead of landing — and say so out loud instead of quietly grinding on. Usually means the attempted scope is bigger than what's actually been verified to work; the fix is a smaller, checkable slice, not another full-scope guess. Trigger on: the same error text recurring across attempts, three or more edits to the same file without a passing test/build/lint run in between, or the user saying things like "still broken," "same error," "try again," "this isn't working." - Skill: `edbertchan/narrow-the-scope` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add edbertchan/narrow-the-scope` - Raw SKILL.md: https://api.skillmd.com/api/skills/edbertchan/narrow-the-scope/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: EdbertChan (https://skillmd.com/u/edbertchan) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/edbertchan/narrow-the-scope --- # Narrow the Scope Repeated failure on one problem is a sizing signal, not just a persistence problem. When the same error keeps coming back, or a file has been edited several times with nothing verified in between, that's usually evidence the change being attempted is bigger than the piece that's actually understood — not a reason to try harder at the same size. **Why:** Guessing again at full scope after a failed attempt burns the same budget on the same blind spot. A smaller, verified slice turns up the actual constraint (the real error, the real edge case) in one cheap step instead of costing another full attempt to rediscover it. ## Mechanical trigger The "three edits to one file with no check between" trigger is counted for you by a PostToolUse hook, `engine/hooks/narrow-the-scope/` (installed by `install.sh`). It injects a one-line reminder at the third edit and resets on any test/build/lint command. When you see that reminder, this skill applies: run the check, say it plainly, propose the smaller slice. ## Detect it live, don't eyeball it This session's own transcript is a real transcript the moment it exists — `~/.claude/projects//.jsonl` is being appended to as the conversation happens, so the same mechanical check `reflect` runs after the fact can run **during** the session, on itself. Don't rely on a fuzzy sense that "this feels like it's dragging" — check: ``` python3 skills/reflect/scripts/token_audit.py claude /> ``` (same "most recent file in the project's transcript dir" rule `reflect` step 1 uses to find the current session without needing a session ID). Read off two numbers from its output: - `recurring failure signatures: N` — the same-shaped error repeating across attempts. - `longest edit streak with zero verification in between: N` — edits piling up on one file with nothing run to check them. A non-zero count on either is the evidence to cite when raising this with the user — not "it feels like we're stuck," but "the same `ModuleNotFoundError` fired on attempts 2 and 4" or "`foo.py` has 5 edits in a row with no test run between them." ## What to do once it's confirmed 1. **Say it plainly, with the count.** Name what's been tried and how many times, using the numbers above — not a vague "this is taking a while." 2. **Stop guessing at full scope.** If the same error recurs identically, the current theory of the bug is probably wrong; re-diagnose before attempting another fix, don't retry the same fix with small variations. When the same gate rejects a second edited version, write down the one-sentence premise both edits shared, then read the gate's source before a third edit. 3. **Propose the smaller slice**, concretely: reproduce the failure in isolation before touching the fix again; scope the next attempt to one file or one sub-case instead of the whole feature; add a verification step after every attempt from here on, not just at the end. 4. **Offer a checkpoint, don't just keep going.** "Want me to keep pushing on the full fix, or land the piece that's already working and dig into the recurring error separately?" — a real fork, not a rhetorical question before continuing regardless. ## Not every long session qualifies A session that's long because the user is steering a sequence of related-but-expanding requests, each confirmed as it arrives, is normal collaborative work — see [[principle-scope-the-session]] for that distinction (session-level topic drift, a different failure mode from this one). This skill is about one narrow problem not converging, evidenced by recurrence or an edit streak with no verification — not about session length or scope by itself. **Battle-tested:** built the same day the `reflect` skill gained mechanical detectors for these two signals (recurring failure signatures, no-verify edit streaks) — this skill is the live-session use of the exact same check, prompted by a real case of a problem (admin-bypass / e2e-worker CI failures) recurring across sessions for long enough that a manual workaround skill got built to route around it rather than resolve it. ## Related If a grading/validation board actually came back FAIL or NEEDS_WORK, or the user says "/thrash", that's `thrash-reflect-automate`, not this skill — this one is for a live problem thrashing mid-session with no board yet. If the question is instead about a done/shipped claim needing live evidence (not a stuck problem), that's `prove-it-ship-gate`.