Zero Explanation Refactoring

Zero-Explanation Refactoring Protocol (Pure Code Stream Standard)

Overview

When tasked with refactoring a class or applying an automated code transformation (e.g., migrating 50 components from JavaScript to TypeScript), default LLM responses append 200 to 400 words of conversational narration:

• "First, I updated the imports on line 1..."
• "Next, I declared the TypeScript interface for UserProfile..."
• "Then, I added type annotations to each function parameter..."
• "Finally, I exported the default module..."

Narrative explanations cause two major engineering breakdowns:

1. Breaks Automated Refactoring Scripts: CLI batch processors and IDE refactoring tools (ai-refactor-cli | git apply) crash when non-code English explanations surround the patch.
2. Severe Output Token Waste: Explaining what the code did in English doubles the output token bill on every single file.
3. Redundant Cognitive Load: The human developer can already see what changed from the git diff.

The Zero-Explanation Refactoring Protocol mandates pure code / diff streams with zero conversational packaging during automated engineering operations.

Conversational Narration vs. Zero-Explanation Pure Stream

┌─────────────────────────────────────────────────────────────┐
│                 Output Stream Comparison                    │
│                                                             │
│  Conversational Narration (285 Tokens / Fails Pipeline):    │
│  I have successfully refactored the function for you!       │
│  Here is the updated code:                                  │
│  ```typescript                                              │
│  export const sum = (a: number, b: number): number => a + b;│
│  ```                                                        │
│  In this refactored version, I added type annotations to    │
│  parameters `a` and `b` and specified the return type...    │
│  ↳ 285 tokens billed, English text breaks `git apply`!      │
│                                                             │
│  Zero-Explanation Stream (18 Tokens - 93.7% Token Cut!):    │
│  ```typescript                                              │
│  export const sum = (a: number, b: number): number => a + b;│
│  ```                                                        │
│  ↳ 18 clean tokens, 100% ready for automated IDE piping!    │
└─────────────────────────────────────────────────────────────┘

Master System Prompt Refactoring Directive

Inject this directive into automated refactoring scripts and agent configurations:

<refactoring_output_rules>
1. PURE CODE DELIVERABLE: Output strictly the modified code block or unified diff.
2. ZERO ENGLISH EXPLANATIONS: Never explain what you changed, why you changed it, or how the code works after the code block.
3. ZERO OPENING / CLOSING PLEASANTRIES: Byte 0 must be the opening fence; the final byte must be the closing fence.
4. CODE-LEVEL COMMENTS ONLY: If architectural context is critical, write standard JSDoc/docstrings inside the code itself.
</refactoring_output_rules>

Automated Batch CLI Piping Recipe

With the Zero-Explanation standard enforced, developers can run mass refactoring across entire directories using bash loops:

# Automated batch refactor: Migrates all JS files to TS without manual intervention
for file in src/utils/*.js; do
  echo "Refactoring $file..."
  ts_file="${file%.js}.ts"
  llm -s "Convert to strict TypeScript. Output pure code only, zero explanation." < "$file" \
    | sed -n '/^```typescript/,/^```/p' \
    | sed '1d;$d' > "$ts_file"
  rm "$file"
done

Benchmark Comparison

Refactoring 50 legacy JavaScript utility modules to strict TypeScript:

Agent Operational Directive

MANDATORY: For code refactoring, translation, and automated editing tasks, agents must emit strictly the pure code block or diff. Eliminate all post-hoc conversational explanations, summaries of changes, and closing remarks.