blog: calibration v5 — anti-consulting-prose, correct loss budget math, vendor lock-in specifics

packages/api/src/llm/fo-blog-pipeline.ts

@@ -362,8 +362,44 @@ A validated 10/10 prose rhythm:
   - No bullet points — everything as prose
   - Ending is a one-liner reframe: "Because 400G itself isn't the risk. Your assumptions are."
 
-The article should read like a human engineer wrote it during a long flight.
+CRITICAL WARNING WHEN CONVERTING TO PROSE:
-Keep it clear and professional, but natural.
+The target is ENGINEER VOICE, not CONSULTING VOICE. These are opposites.
+
+BAD prose (consulting/academic — FORBIDDEN):
+  "The discussion around OEM versus compatible optics is often framed as a question of cost versus reliability."
+  "In production, failures rarely come from a single obvious source."
+  "This is why inspection and cleaning are not optional steps, but part of the baseline operating model."
+  "Cabling is often underestimated in planning phases, especially during technology transitions."
+  → These sound like a McKinsey white paper. This is a FAILURE of the prose conversion.
+
+GOOD prose (engineer narrative — TARGET):
+  "You're about to spend $400,000 on optics. Here's how to accidentally turn it into a $2M problem."
+  "This is where your clean lab design dies."
+  "This is where your vendor stops replying."
+  "This is where your maintenance window explodes."
+  "The $350 optic turned into an $18,000 problem: 2 engineers × 6h × $120/h in troubleshooting, missed maintenance window, SLA penalty, customer escalation."
+  → These sound like someone who was there. THIS is the target.
+
+VENDOR LOCK-IN must be specific — never generic:
+  BAD: "Firmware updates, platform-specific requirements, or changes in validation policies can affect interoperability."
+  GOOD: "Cisco NX-OS upgrade? Third-party optics suddenly blocked. Juniper needs explicit optics settings or the link won't come up. Arista runs fine until a specific EOS release tightens EEPROM checks. Then you're on hold with TAC at midnight."
+
+WHEN NOT TO USE must be a concrete list, not a vague category:
+  BAD: "For mission-critical systems or highly sensitive applications, OEM may be preferred."
+  GOOD: "Skip compatible optics when: coherent 400ZR+/DCO in long-haul DCI, financial trading or sub-millisecond latency requirements, brownfield with unknown firmware states, any environment where TAC contract support is business-critical."
+
+LOSS BUDGET MATH — always show it correctly:
+  CORRECT FORMULA: Loss Budget = TX_min - RX_sensitivity = (-2.9 dBm) - (-7.7 dBm) = 4.8 dB available
+  Then: Link Loss = Fiber Loss + Connector Loss = (0.5km × 0.22 dB/km) + 0.3 dB = 0.11 + 0.3 = 0.41 dB
+  Then: Margin = 4.8 dB - 0.41 dB = 4.39 dB (healthy)
+  WRONG FORMULA: "Loss Budget = TX - (Fiber + Connector)" where result is a negative dBm value — that's the RX level, not the budget.
+
+HIDDEN COSTS must have actual numbers, not vague ranges:
+  BAD: "A $350 optic turned into a multi-thousand-dollar problem."
+  GOOD: "$350 optic → $18,000 problem: 2 engineers × 6h × $120/h = $1,440 troubleshooting, plus missed maintenance window = SLA penalty, plus customer escalation = real business damage."
+
+The article should read like a human engineer wrote it at 2AM after a failed deployment.
+Angry, specific, and right.
 
 Article:
 {{ARTICLE}}`;
@@ -424,6 +460,39 @@ CALIBRATION FAILS (auto-reject — fix before returning):
 21. REPEATED TOPICS: Check if cleaning, polarity, or power budget are each explained more than once across sections.
     → Each concept gets ONE home. Mention it elsewhere as a single-sentence reference at most.
 
+22. CONSULTING PROSE FAIL (HARD FAIL): If the article reads like a McKinsey white paper, it failed STEP8. Check for:
+    → "The discussion around X is often framed as..." — REPLACE with a hook or direct statement
+    → "In practice, failures rarely come from..." — too academic. Say WHAT actually breaks.
+    → "This is why X is not optional, but part of the baseline operating model" — consulting speak. REMOVE.
+    → "Cabling is often underestimated in planning phases" — vague. Name the SPECIFIC mistake and cost.
+    → Opening sentence with "The" or "In" — weak. Start with "You" or a specific scenario.
+    If ANY of these patterns appear: the article was over-softened. Restore engineer voice.
+
+23. VENDOR LOCK-IN TOO VAGUE: If vendor lock-in section only says "firmware updates" or "validation policies" without naming vendors:
+    → ADD: "Cisco NX-OS upgrade → third-party optics blocked. Juniper → needs explicit optics settings or no link. Arista → fine until a specific EOS release tightens EEPROM checks."
+    The named-vendor examples are what makes this shareable.
+
+24. "WHEN NOT TO USE" TOO SOFT: If the only answer is "mission-critical systems" or "sensitive applications":
+    → REPLACE with: coherent 400ZR+/DCO in long-haul, financial trading environments, brownfield with unknown firmware, TAC-contract-dependent environments.
+    → Concrete scenarios, not vague risk categories.
+
+25. LOSS BUDGET FORMULA: Verify that the formula is Loss Budget = TX_min - RX_sensitivity (result is positive dB available).
+    → Not: "Loss Budget = TX - (Fiber + Connector losses)" producing a negative dBm — that's the received power level, not the budget.
+    → Correct example: (-2.9 dBm) - (-7.7 dBm) = 4.8 dB available. Then Margin = 4.8 - Link_Loss.
+
+26. FIBER LOSS UNIT ERROR: Verify fiber loss uses km, not meters.
+    → 500m fiber = 0.5 km × 0.22 dB/km = 0.11 dB. NOT 500 × 0.22 = 110 dB.
+    → This is a factor-of-1000 error that any optical engineer will catch immediately.
+
+27. HIDDEN COSTS BRUTALITY: If the hidden costs section gives a vague dollar range without a breakdown:
+    → "$350 optic → $18,000 problem" must include: 2 engineers × 6h × $120/h = $1,440 troubleshooting, missed maintenance window = SLA penalty, customer escalation = business damage.
+    → The number has to be traceable or it won't be believed.
+
+28. HOOK PUNCH CHECK: Does the hook make the reader physically stop?
+    → WEAK: "You're about to sign a PO for 400G optics."
+    → STRONG: "You're about to spend $400,000 on optics. Here's how to accidentally turn it into a $2M problem."
+    → If the hook lacks a concrete number or consequence, strengthen it.
+
 For each issue:
 - Quote the problematic text
 - Explain what's wrong
@@ -656,6 +725,16 @@ WRONG PATTERNS (both styles — never produce):
 ❌ ## or ### section headers inside the article — plain text only, always.
 ❌ 8+ sections in one article — looks assembled, not written.
 ❌ Cleaning explained in "hidden costs" AND again in "cabling reality" — pick one home.
+❌ "The discussion around X is often framed as a question of Y versus Z." — consulting opening, not engineer voice.
+❌ "In production, failures rarely come from a single obvious source." — vague academic framing.
+❌ "This is why X is not optional, but part of the baseline operating model." — McKinsey white paper language.
+❌ "Cabling is often underestimated in planning phases." — generic. Name the mistake and its dollar cost.
+❌ "Firmware updates, platform-specific requirements, or changes in validation policies can affect interoperability." — too vague. Name Cisco, Juniper, Arista specifically.
+❌ "For mission-critical systems" as the only "when not to use" answer — too soft. Name coherent ZR+, financial trading, brownfield.
+❌ Loss Budget = TX - (Fiber + Connector) resulting in a negative dBm — that's received power, not budget. Budget = TX_min - RX_sensitivity = positive dB number.
+❌ Fiber loss: "500m × 0.22 dB/km = 1.1 dB" — off by factor 10. Correct: 0.5 km × 0.22 = 0.11 dB.
+❌ "A multi-thousand-dollar problem" without a breakdown — cite the numbers: engineer hours × rate + SLA penalty + customer escalation.
+❌ 400ZR reach stated as "80-120km" without qualification — 400ZR is standardized to 80km; beyond that depends on OSNR, amplification, vendor implementation.
 
 --- END GOLD STANDARD ---
 `;