If You Already Know the Fix, Just Fix It

Direct execution modifies files immediately. No exploration phase, no read-only mode, no dependency mapping. It is the right choice when the solution is known, the scope is clear, and the target files are identified.

The three criteria: known solution, clear scope, identified files. When all three are met, plan mode adds overhead with zero value.

Textbook Direct Execution Scenarios

Stack trace → single function fix. A formatting bug in format_response() at line 23 of response_formatter.py. The stack trace pinpoints the location, the error is clear. Direct execution: fix the function.

Known edge case → null check. A NullPointerException in parse_record() when a JSON field is missing. The function, the missing field, and the fix (add a null check) are all known. Direct execution.

CI test failure → update reference. Pipeline fails with “Expected 200, got 404” because a route was renamed from /api/users to /api/v2/users but the test was not updated. Root cause identified via git blame. Direct execution: update the test.

Well-specified requirement → single function. “Add a date validation check: reject dates more than 90 days in the past” in validate_intake_form(). Clear algorithm, single function, single file. Direct execution.

Not Strictly Single-File

Direct execution is not limited to one file. A CLI bug fix might involve:

• Fixing parse_args() in cli.py
• Updating help text in the same file
• Adding a one-line entry to CHANGELOG.md

Two files, but the solution for each change is known. No exploration needed to figure out what to do. The criterion is solution certainty, not file count.

A 2-file change with known solutions → direct execution. A 1-file change in unfamiliar code with unclear approach → plan mode.

Recognizing Scope Underestimation

A developer started direct execution for a “simple” template bug. The session data tells the real story:

This is classic scope underestimation. The task had hidden dependencies across 5 files that direct execution could not discover through its normal workflow. Two rollbacks on router.py indicate the developer encountered unexpected connections between modules.

Plan mode would have revealed these dependencies through read-only exploration before any changes were made. The 47 minutes of partially-rolled-back direct execution could have been a 10-minute exploration followed by a focused implementation.

The lesson: if you start direct execution and discover the scope is larger than expected, the task was misclassified. Plan mode should have been used from the start.

Mixing Modes Within a Session

Two CI/CD issues:

1. A known typo in build.sh causing compilation failure
2. An outdated container image tag in deploy.yaml — correct replacement unknown

These are different tasks with different characteristics. The typo has a known fix → direct execution. The image tag requires investigation → plan mode.

Apply each mode where it fits. Do not force both issues into one mode. The typo should not wait for plan mode’s exploration, and the image tag should not be guessed at through direct execution.

When Plan Mode Is Proposed for Simple Fixes

A colleague says: “Let’s use Plan mode to analyze the full data flow before adding this null check to parse_record().”

The null check is a scoped fix in a known function for a known missing field. The complexity of the pipeline is irrelevant to the simplicity of the fix — the check handles the missing field regardless of its upstream source. Plan mode’s exploration adds overhead without changing the implementation.

This is the “plan mode overuse” pattern. Complex systems can still have simple fixes. Match the mode to the fix complexity, not the system complexity.

The Direct Execution Signature

Session logs that indicate direct execution was the right choice:

• Short duration (minutes, not tens of minutes)
• 1-2 files modified
• Clear error message or known requirement as the trigger
• No rollbacks
• No discovery phases visible in the timeline

If logs show 5+ files, rollbacks, and 40+ minutes for what started as a “simple fix,” the mode was wrong.

One-liner: Known solution, clear scope, identified files — when all three are met, start modifying immediately; plan mode adds zero value to a fix you already understand.