Surgical Iteration — One Feature at a Time

The Rewrite Spiral

Every developer who has worked with AI on UI has experienced the rewrite spiral. You have a working hero section. You ask AI to add a stats row. When you look at the output, the hero has changed — slightly, subtly, in ways that are hard to attribute. The stats row looks correct. But now the hero spacing is off. You ask AI to fix the hero. The stats row shifts. Three iterations later, nothing is exactly right and everything has been touched at least twice.

This is context overload in action. The cause is holding too many features in a single conversation, and giving feedback that is too broad for AI to scope precisely.

The closing line is not a suggestion. It is the instruction that makes the difference between a targeted fix and a refactoring sweep. Knox's CLAUDE.md states it explicitly: "Always end AI prompts with: 'Fix only these items. Do not change anything else.' Without this line, AI will helpfully modify things you didn't ask about — breaking working code."

Vague vs. Surgical Feedback

The distinction between vague and surgical feedback is the distinction between "please help with this area" and "change this specific property from this value to this value."

Vague feedback gives AI permission to interpret what "better" means. AI's interpretation is always plausible but rarely what you intended. "Make the hero feel more sophisticated" might result in a thinner font weight, a more complex animation, and a layout compression — all of which AI considers more sophisticated, and all of which violate your design system.

Surgical feedback gives AI exactly one thing to change:

• "The hero H1 is font-weight: 500. The MASTER.md specifies 700. Fix only the H1 font-weight. Do not change anything else."
• "The card border is 2px. The design system requires 1px. Fix only the card border-width. Do not change anything else."
• "The body text in Section 2 uses #64748b. The color floor is #94a3b8. Fix only the body text color in Section 2. Do not change anything else."

Notice the structure: property, current value, target value, scope. This is the format that produces precise iteration without collateral changes.

The One Feature Rule

Multi-feature builds are not a context window problem. They are an isolation problem. When AI builds three features simultaneously, it makes choices that optimize across all three. Those optimization choices create subtle interdependencies that are invisible until one feature changes. Then everything changes.

The decomposition pattern breaks this cycle. Build each feature in complete isolation. Verify it works before moving on. When integrating, the integration prompt names the stable feature: "Here is the working hero section. Add only the stats row. Do not change the hero."

This is the pattern behind Knox's CLAUDE.md rule: "One feature = one conversation. Never ask AI to hold the full project in one session." The sessions are short because each feature is isolated. The integrations are clean because the prior feature is locked before the next begins.

The Session Decomposition Template

For multi-feature builds, Knox uses a session decomposition template before any code:

1. Define all features needed (list them explicitly — nothing vague)
2. Tackle each in isolation: "Build only [feature X]. Here is the context: [minimal context]."
3. Verify each feature before combining
4. Integrate: "Here is the working [feature X]. Add [feature Y] without changing X."

Applied to a real example — rebuilding the academy's lesson dashboard:

1. Features: lesson list sidebar, progress indicators, content area, track navigation
2. Sidebar first: "Build only the lesson list sidebar using glass-card pattern. No progress indicators yet."
3. Verify: sidebar renders correctly at desktop + mobile
4. "Here is the working sidebar. Add progress indicators only. Do not change the sidebar layout."
5. Continue for each feature

The quality stays high throughout because isolation prevents context overload from degrading any single feature.

The Iteration Protocol for UI/Site Work

The Surgical Iteration Rule applies to every prompt in an iterative session:

1. State the specific deviation (property, element, current value)
2. State the target value (from MASTER.md or reference)
3. Scope the change (which element, which section, which component)
4. Close: "Fix only these items. Do not change anything else."

This protocol creates an audit trail. Each iteration changes exactly what was stated. If the output changes more than that — if working elements are modified alongside the target — the closing line was not present or not followed. Add it to the next prompt.

Surgical iteration is the discipline that makes the rewrite spiral optional — something you can exit whenever you apply the protocol. The closing line costs three seconds to type. The rewrite spiral it prevents costs hours.