content-refiner

POST-GATE TOOL.

Transforms content that FAILED Gate 4 into passing content.

Focuses on trimming verbosity and fixing continuity.

• Trigger: Gate 4 (Acceptance Auditor) returned [FAIL].
• Goal: Fix word count OR continuity issues (or both).
• Key: Diagnose what failed BEFORE applying fixes.

DO NOT apply fixes blindly. Gate 4 fails for different reasons requiring different strategies.

Step 0: Identify What Failed (Mandatory)

Ask the user OR examine the Gate 4 failure message:

| Failure Type | Question | Action |

|--------------|----------|--------|

| Word Count | "Is the lesson over the target (typically 1500 words)?" | Calculate exact % to cut |

| Continuity | "Does the opening reference the previous lesson?" | Rewrite opening only |

| Both | "Word count AND continuity broken?" | Two-phase approach |

DIAGNOSIS EXAMPLES:

Example 1: Word Count Only

```

Content: 1950 words, Target: 1500

Excess: 450 words

% to cut: (450 / 1950) × 100 = 23%

→ CUT EXACTLY 23%, not generic 15-20%

```

Example 2: Continuity Only

```

Opening: "Let's explore this new topic..."

Problem: Doesn't reference Lesson N-1

→ Rewrite opening only; don't cut words

```

Example 3: Both

```

Word count: 1950 (23% over)

Opening: Generic, missing prior lesson reference

→ Phase 1: Rewrite opening (identify anchor from Lesson N-1)

→ Phase 2: Cut words to 23% (context-aware)

```

Step 1: Assess Content Layer (Context-Aware Cutting)

Read the lesson's frontmatter to determine layer:

| Layer | Cutting Strategy |

|-------|-----------------|

| L1 (Manual) | Keep foundational explanations; cut elaboration |

| L2 (AI-Collaboration) | Keep Try With AI sections (core); cut narrative padding |

| L3 (Intelligence) | Keep pattern insights; cut explanatory scaffolding |

| L4 (Spec-Driven) | Keep specification details; cut conceptual scaffolding |

---

Phase 1: The Connection Builder (Continuity Fix)

Do this FIRST if opening is generic.

Formula:

```markdown

In [Previous Lesson], you [SPECIFIC OUTCOME from Lesson N-1].

Now, we will [CONNECT outcome to new goal] by [STRATEGY].

```

Validation:

• [ ] Opening references Lesson N-1 by name
• [ ] Specific outcome (not generic "learned about...")
• [ ] Clear connection shows why this lesson matters (builds on N-1)

After fixing: Proceed to Fluff Cutter if word count also fails.

Phase 2: The Fluff Cutter (Word Count Fix)

Apply layer-specific cuts in this order:

FOR ALL LAYERS:

1. Delete redundant "Why This Matters" sections

- Keep ONLY if it reveals non-obvious insight

- If same point made in text AND in "Why This Matters" → delete WTM

1. Merge repeated examples

- Find duplicate explanations

- Keep first, delete second

1. Tighten transitions between sections

- Replace "As we discussed earlier, X..." with direct reference

FOR L1-L2 ONLY (students still building foundation):

1. Reduce "Try With AI" sections to exactly 2 prompts

- Keep foundational + one advanced

- Delete exploratory extras

1. Keep educational scaffolding (explanations, examples)

FOR L3-L4 ONLY (students ready for advanced patterns):

1. Trim narrative scaffolding

- Keep pattern insights and rules

- Delete "why this matters philosophically"

1. Remove beginner-level explanations

- Assume students understand fundamentals

FOR ALL LAYERS:

1. One Analogy Rule: Keep the BEST analogy for the concept; delete redundant ones
2. Merge Tables/Text: Use ONE format (table OR prose), never both
3. Reduce Examples: Keep 2-3 best; delete "also consider..."
4. Tighten Lists: Convert 5-item lists to 3 core items

Verification:

• [ ] Word count after cuts: [TARGET ± 5%]
• [ ] No L1 content cut from L1 lessons
• [ ] No pattern insights lost from L3-L4 lessons
• [ ] Try With AI: 2 prompts if L1-L2, keep all if L3-L4

Phase 3: Post-Refinement Validation (CRITICAL)

After applying fixes, verify the content now PASSES Gate 4:

```

✓ Word Count Check:

Current: [X] words

Target: [target_from_spec]

Status: [PASS if ≤target ± 5%, FAIL if over]

✓ Continuity Check:

Opening references Lesson [N-1]? [YES/NO]

Specific outcome mentioned? [YES/NO]

Connection to new lesson clear? [YES/NO]

✓ Layer Appropriateness:

No foundational cuts from L1-L2? [YES/NO]

No pattern insight loss from L3-L4? [YES/NO]

✓ Content Integrity:

Removed examples still explained elsewhere? [YES/NO]

Cut sections non-essential? [YES/NO]

```

NEXT STEP RECOMMENDATION:

```

"Refined content is ready.

Word count: [after] (target: ≤[target])

Continuity: Now references Lesson [N-1]

Recommend re-submitting to acceptance-auditor for Gate 4 re-validation.

Command: [provide re-validation instruction]"

```

---

```markdown

Diagnosis

Issue Found: [Word count | Continuity | Both]

Layer: [L1/L2/L3/L4]

Metrics

| Metric | Before | After | Target | Status |

|--------|--------|-------|--------|--------|

| Word Count | 1950 | 1485 | ≤1500 | ✅ PASS |

| Continuity | Generic opening | References Lesson 2 | Specific reference | ✅ PASS |

Fixes Applied

1. Phase 1: Rewrote opening to reference "booking-agent implementation" from Lesson 2
2. Phase 2: Deleted 240 words using layer-aware cuts:

- Removed redundant "Why This Matters" section (line 45, 120 words)

- Merged duplicate example (lines 67-89, 85 words)

- Cut 1 extra "Try With AI" prompt (35 words)

1. Phase 3: Validated word count and continuity

Ready for Re-validation

✅ Word count: 1485 (≤1500)

✅ Continuity: Opening references Lesson 2

✅ Layer integrity: All L2 AI examples preserved

Next: Re-submit to acceptance-auditor for Gate 4 validation

Refined Content

[Full refined lesson content]

```