Scan Todo Run

Scan TODO Run

Purpose

A disciplined, adaptive workflow for code changes. The core loop: classify the task type, scan context, discover existing patterns, plan with self-critique, implement slice-by-slice, and verify iteratively until the result is proven correct.

This skill enforces the Mandatory Process Rules defined in CLAUDE.md — every phase exists because those rules require it. The human directs; the AI handles 100% of implementation, testing, and debugging.

When To Use

• Bug fix, feature, refactor, or UI edit.
• User provides file paths, design images, or a URL to test.
• User references a similar existing thing ("tương tự như X", "similar to X", "like tab Y").
• Any task that benefits from scanning context before editing.

Workflow

Phase 0 — Classify & Strategize

Before touching any code, classify the task and declare the execution strategy. Different task types need different approaches — using one formula for everything is a Level 3 pattern.

Classify into one of:

State the classification and strategy explicitly in your first message to the user, along with which CLAUDE.md coding rules are relevant to this task (e.g., "no any", "constants over string literals", "your UI component library over raw HTML" for frontend work).

Why this matters: the assessment of AI proficiency hinges on whether you adapt your approach to the task at hand. A bug fix that skips reproduction and jumps to coding is fragile. A feature that skips pattern-matching invents unnecessary drift. Name the strategy so the human can redirect if needed.

Phase 1 — Collect & Scan

Skip broad re-scanning if you already understand the app structure. Don't waste tokens re-discovering project layout you already know from memory, prior conversations, or CLAUDE.md. Jump straight to the user's specific files.

Start from the user's seeds, expand outward:

1. Read the exact files the user mentioned or that directly relate to the task.
2. From those files, follow imports/references outward — grep for symbols, check shared config/constants, find sibling components.
3. Stop expanding when you have enough context to plan confidently.

Seed sources (in priority order):

• File paths mentioned in the prompt
• Design images/screenshots — look at them carefully; they are the spec
• Active file in the IDE
• URL for browser verification
• Changed files (git status / git diff in a repo)

Bug-fix specific: before expanding, try to reproduce the bug first. If the user gave a URL, open it in a browser-automation tool. If it's a backend issue, curl the endpoint. Reproduction evidence anchors everything that follows.

Large codebases: if scanning looks like more than 3-4 queries, delegate to the Explore subagent via the Agent tool. Pass concrete seeds (paths, symbols) — don't ask it to "explore everything".

Phase 2 — Find The Existing Pattern

Before designing anything, look for how the codebase already solves the same shape of problem:

• If the user said "similar to X", locate X and read it end-to-end.
• Search for comparable components (sibling features, other tabs, other list views, other modals).
• Look for TODO comments — sometimes the scaffold is already there waiting.
• Match existing conventions: file layout, import order, naming, state management, prop shapes, styling.

The codebase's existing answer is almost always the right one. Copying the pattern keeps the diff small, consistent, and reviewable. Inventing a parallel approach produces drift.

Partial patterns: the pattern may exist on only one side (a frontend twin but no backend twin, or vice versa). Identify what can be copied vs. what must be built new — name the gap explicitly in your scan summary so the user sees it too.

Phase 3 — Plan & Self-Critique

This phase is mandatory. Do not skip it, even for seemingly simple tasks. Present a plan before writing any implementation code.

The plan must include:

1. Approach — What you intend to do, step by step. Reference the pattern from Phase 2.
2. Alternatives considered — At least one other way you could solve this, and why you chose your approach over it. Even for straightforward tasks, name what you decided NOT to do (e.g., "I could create a new utility, but the existing formatDate in utils/ already covers this").
3. Self-critique — Ask yourself:
   • What could go wrong with this approach?
   • What assumptions am I making? Are they valid?
   • Are there edge cases this plan doesn't handle?
   • Does this comply with the coding rules in CLAUDE.md?
4. Trade-offs — State what you're optimizing for (speed, consistency, minimal diff) and what you're accepting as a cost.
5. Risk flags — Anything the human should know before you proceed: breaking changes, migration needs, performance implications, areas you're uncertain about.

After presenting the plan:

• For non-trivial tasks (multi-file, architectural, new patterns): wait for human approval before proceeding.
• For straightforward tasks where the plan follows an obvious existing pattern: state the plan and proceed, but make it clear the human can redirect.

Why this exists: This is the single biggest differentiator between Level 3 and Level 4. Level 3 implements correctly. Level 4 demonstrates that the AI considered alternatives, challenged its own assumptions, and gave the human enough information to make an informed decision before any code was written.

Phase 4 — Align (only if needed)

Skip this phase if the user gave concrete paths, a design, and a clear ask. The plan from Phase 3 usually surfaces any ambiguity.

Align only when the goal is ambiguous, multiple interpretations fit, or scope feels bigger than the user likely expects. If so, send a short message with:

• What you understand the goal to be
• Files/areas you plan to touch
• Key assumptions
• One focused question if any

Then wait.

Phase 5 — TODO + Implement

Build a TODO list (use TaskCreate if the task is 3+ steps). Each task: one coherent slice with one verifiable outcome. A "slice" can span multiple files when they change together (e.g., a new tab = frontend route + frontend component + backend controller + backend service is one slice, not four tasks).

Classify every TODO item into one of three readiness levels:

• 🟢 Ready — Enough information, no external dependency. Implement immediately.
• 🟡 Review — Can be built, but needs discussion with the dev before finalizing. Present the proposed approach and ask the dev to critique / confirm design decisions. Wait for dev input before marking done.
• 🔴 Blocked — Missing information that only the dev (or another person) can provide. State exactly what is missing. After the dev provides info:
  • Clear enough to implement → reclassify as 🟢 Ready.
  • Still needs design discussion → reclassify as 🟡 Review.

Execution order: Implement all 🟢 Ready items first. Then present 🟡 Review items for discussion. Then surface 🔴 Blocked items as explicit questions.

Implement one slice at a time. Mark done as soon as each is done — don't batch.

Keep edits minimal and aligned with the pattern from Phase 2. Don't refactor unrelated code. No "while I'm here" cleanups.

Phase 5b — Dispatch (mandatory once there are 2+ independent slices)

Doing every slice inline is what turns a task into a multi-day session. Once Phase 5 produced two or more 🟢 slices that share no files, or a slice spanning more than one repo, hand them to subagents via the Agent tool — all in one message, so they run concurrently. See superpowers:subagent-driven-development and superpowers:dispatching-parallel-agents for the mechanics.

Each agent's prompt must carry, or it will re-derive them and lose the time you were saving:

• the exact files to edit (from Phase 1) and the pattern to copy (from Phase 2),
• the constraint set that applies (the relevant CONVENTIONS.md section, naming/casing rule, response-shape contract),
• the gate it must run before reporting — the repo's lint + type-check commands (e.g. pnpm exec eslint <files> --max-warnings 0 and pnpm exec tsc --noEmit),
• the required report: file:line per change plus the verbatim gate output.

Never delegate: the root-cause decision, any slice that touches a file another slice also touches, a cross-repo contract change (edit both sides in one place), or the final verification.

On return, do not trust the reports. Read the actual git diff for every slice yourself, then continue to Phase 6 once, over the combined result.

Phase 6 — Verify-Debug Loop

Verification is not a single pass — it's an iterative loop. Run verification, and if anything fails, diagnose, fix, and re-verify. Never claim "done" on a red result.

Step 1 — Run the right verification:

Step 2 — Log the evidence:

Every verification attempt gets logged with:

• What tool was used (browser automation / test runner / type-check / curl)
• The actual output (paste test results, screenshot path, curl response)
• Pass or fail verdict

Step 3 — If verification fails:

Iteration 1: ❌ <what failed and why>
  → Diagnosis: <root cause>
  → Fix applied: <file:line — what changed>
Iteration 2: ✅ <what passed>

Keep iterating until green. If you hit 3+ failures on the same issue, pause and surface it to the human — it might indicate a wrong approach rather than a minor bug.

Step 4 — Final verdict:

Only after all verifications pass, state the final result. Include:

• What was verified and how
• Any caveats or areas that couldn't be fully verified (and why)

Step 5 — Hand the change to the tester (one line, mandatory):

Append one line to your test-notes file (configurable — whatever path your project uses as the "needs testing" inbox) — the area, what changed, and the risk it creates (not the change itself). Rules: .claude/skills/jarvis-tester/references/ledger-format.md §Inbox. If a ledger already exists for this area (feat-<slug>.md in your test-notes directory), re-run its cases as part of Step 1 and update their Result/Run/Evidence in place — that is the cheapest regression check there is. For a real QA pass (seeded test bed, full sweep, new cases) invoke jarvis-tester instead of improvising; it owns the ledger and the environment traps.

For UI tasks with a design image, the bar is "does the rendered result match the image." A passing type-check alone is not sufficient proof.

Output Format

Every task completion must include these sections. This structure ensures the transcript contains clear evidence of the workflow.

Bug fix

## Task Classification
Type: bug-fix
Strategy: reproduce → trace → isolate → fix → regression test
Relevant CLAUDE.md rules: <which rules apply>

## Scan Summary
- Root cause: <what was broken and why>
- Reproduction: <how the bug was confirmed — URL, curl, test>

## Plan & Self-Critique
- Approach: <how you'll fix it>
- Alternative considered: <what else you could have done>
- Self-critique: <risks, assumptions, edge cases>
- Trade-off: <what you optimized for>

## Implementation
- <file:line> — <what changed>

## Verification Chain
Iteration 1: <tool> → <result (pass/fail)> → <evidence>
[Iteration 2: <tool> → <result> → <evidence>]  (if retry was needed)
Final: ✅ all checks pass

## Residual Risk & Next Steps
- <anything the human should watch for>
- <follow-up work if any>

Feature / refactor / ui-edit

## Task Classification
Type: feature | refactor | ui-edit
Strategy: <chosen strategy from Phase 0>
Relevant CLAUDE.md rules: <which rules apply>

## Scan Summary
- Existing pattern used: <what was reused>
- Files touched: <list>
- Key decisions: <why this approach>

## Plan & Self-Critique
- Approach: <step-by-step plan>
- Alternatives considered: <what else, why not>
- Self-critique: <risks, assumptions, edge cases>
- Trade-offs: <what you optimized for vs. what you accepted>

## Implementation
- <file:line> — <what changed>

## Verification Chain
Iteration 1: <tool> → <result> → <evidence>
[Iteration N: ...]
Final: ✅ all checks pass

## Residual Risk & Next Steps
- <known limitations>
- <remaining work, follow-ups>

Tooling Priority

1. git status / git diff — scope delta
2. Glob / Grep — file & keyword discovery
3. Read — exact logic
4. Agent (Explore subagent) — broad codebase questions in large repos
5. Browser automation — UI verification (reload, snapshot, screenshot)
6. Test runner / type check — logic verification
7. TaskCreate — step tracking when 3+ steps

Guardrails

• Follow existing patterns. If you're inventing something new when a pattern already exists, pause and look again.
• Keep the diff minimal: one clear change per task.
• Never skip the Plan & Self-Critique phase — it's the core of Level 4 workflow discipline.
• Don't claim done without running verification appropriate to the change type. For UI with a design image, that means a browser check.
• If verification fails, iterate. Don't report red as green.
• Split large scope into slices. Do one slice, then present the TODO for the rest.
• Reference CLAUDE.md coding rules when they're relevant to the task at hand.

Language

• Skill file and internal structure: English.
• User-facing communication: match the user's language (Vietnamese <-> English, etc.). If the user mixes, mirror the mix.

Session Template

For a large multi-slice task, use templates/scan-todo-run-template.md as a session log. For small tasks, skip the template and work inline — the TODO list + final report is enough.