diff --git a/packages/api/src/llm/fo-blog-pipeline.ts b/packages/api/src/llm/fo-blog-pipeline.ts index 07882a1..8f1e419 100644 --- a/packages/api/src/llm/fo-blog-pipeline.ts +++ b/packages/api/src/llm/fo-blog-pipeline.ts @@ -52,14 +52,26 @@ STRICTLY FORBIDDEN: - Press release language ("revolutionary", "industry-leading") - Repeating obvious facts -EVERY ARTICLE MUST: -- Start with a real-world scenario or problem -- Help the reader make a specific decision -- Include at least 2 real-world failure scenarios -- Include at least 1 "this sounds good but is actually wrong" correction -- Have a strong, opinionated takeaway -- Reference specific optics (SR, DR, LR, ZR, etc.) -- Include real numbers (dBm, watts, price per port) +HARD RULES (non-negotiable — article FAILS QA without these): +1. Start with a BRUTAL hook — not "If you're still..." but "You're about to sign a PO. Stop." +2. Include a "WHAT BREAKS IN PRODUCTION" section with at least 2 SPECIFIC failure scenarios: + - Name the exact problem (e.g., "DR4 link won't come up") + - Name the exact cause (e.g., "wrong MPO polarity — Type A vs Type B") + - Name the exact fix (e.g., "flip the key on one end, or use a Type B to Type A conversion cable") +3. Include a "HIDDEN COSTS NOBODY MENTIONS" section: + - Cleaning effort (MPO end-faces need inspection scope, not just wipes) + - Troubleshooting time (dirty connector = 2 hours of debugging before someone checks) + - Migration mistakes (SR4 to DR4 = different fiber count, different patch panels) + - Cabling redesign cost (MMF to SMF re-cabling = $50-200 per drop) +4. Include a "WHEN NOT TO USE THIS" section — every technology has anti-patterns +5. NEVER make absolute statements without conditions: + BAD: "The cost per Gbit on 400G has dropped below 100G" + GOOD: "In most leaf-spine deployments with 50+ ports, 400G cost per Gbit is now below 100G — if you factor in switch density and power" +6. Every claim with a number MUST have context (deployment size, vendor, conditions) +7. The article must feel DIRTY — like someone wrote it after a bad deployment, not after reading a whitepaper +8. Reference specific optics (SR4, DR4, FR4, LR4, ZR, etc.) with REAL problems, not just specs +9. Include real numbers (dBm, watts, price per port, cost per Gbit) +10. Cabling reality MUST be addressed: MPO polarity, SR4→DR4 migration fiber count changes, cleaning REFERENCE VALUES: - SFP+ SR: Tx -8.2 to +0.5 dBm, Rx sensitivity -18.0 dBm, 1.0W typical @@ -144,24 +156,41 @@ export const STEP4_MASTER_DRAFT = `Write the full technical blog article based o Follow these rules EXACTLY: -STRUCTURE: -1. Hook: real scenario (3-5 sentences, specific, relatable) -2. What people think vs reality -3. Technical breakdown (only what matters for the decision) -4. What breaks in production (2-3 real failure scenarios) -5. Cost and operational trade-offs (real numbers) -6. Clear recommendation (with specific conditions) +MANDATORY SECTIONS (article fails without ALL of these): +1. BRUTAL HOOK (3-5 sentences) — put the reader in a real situation. Not "If you're still planning..." but "You're about to sign a PO for 200 optics. The vendor quote is on your desk. Before you sign — read this." +2. WHAT PEOPLE THINK vs REALITY — challenge a specific common assumption with evidence +3. SPEED/TECHNOLOGY BREAKDOWN — only what matters for the decision, with REAL numbers +4. WHAT BREAKS IN PRODUCTION (MANDATORY, minimum 2 scenarios): + - Scenario 1: Specific failure with exact cause + fix (e.g., "DR4 link won't come up → wrong MPO polarity") + - Scenario 2: Operational pain point (e.g., "Dirty MPO end-face → 3 dB insertion loss → intermittent CRC errors → 2 hours debugging") + - Include: firmware incompatibilities, cabling mistakes, power budget violations +5. HIDDEN COSTS NOBODY MENTIONS (MANDATORY): + - Cleaning effort (MPO requires inspection scope at $2K, not just IPA wipes) + - Troubleshooting time ($150/hr engineer × 4 hours for a dirty connector = $600 per incident) + - Migration costs (SR4→DR4 = different fiber count, new patch panels, re-termination) + - Cabling redesign (MMF→SMF = $50-200 per drop × number of drops) +6. WHEN NOT TO USE THIS (MANDATORY): + - Small DCs (<50 ports) + - Legacy MMF environments + - Specific anti-patterns for the technology discussed +7. COST + TCO ANALYSIS — real numbers with CONTEXT (deployment size, vendor type, conditions) +8. CABLING REALITY — MPO polarity (Type A vs B vs C), fiber count changes, cleaning requirements +9. CLEAR RECOMMENDATION with SPECIFIC CONDITIONS — not "consider your needs" but "If you have X, do Y. If you have Z, do W." + +ABSOLUTE STATEMENT RULE: +- NEVER write "X has dropped below Y" without conditions +- ALWAYS qualify: "In deployments with 50+ ports..." or "When you factor in power and density..." +- EVERY number needs context: price ranges, deployment sizes, vendor types STYLE: -- Direct, opinionated, pragmatic +- Direct, opinionated, occasionally sarcastic +- Write like you just came back from a failed deployment - No buzzwords, no corporate language -- No generic intros -- Short sentences, clear paragraphs -- Slightly sarcastic where it fits -- Include specific transceiver types (SR4, DR4, LR4, FR4, ZR, etc.) -- Include real numbers (dBm, watts, $/port, €/Gbit) +- Short sentences, direct paragraphs +- Specific transceiver types (SR4, DR4, LR4, FR4, ZR) with REAL problems, not just specs +- Real numbers (dBm, watts, $/port, €/Gbit, $/year power cost) -MINIMUM 2000 words. No placeholders. No TODO markers. Complete article. +MINIMUM 2500 words. No placeholders. No TODO markers. Complete article. Outline: {{OUTLINE}} @@ -173,18 +202,35 @@ Context data: // STEP 5: REALITY INJECTION // ═══════════════════════════════════════════════════════ -export const STEP5_REALITY_INJECTION = `Improve this article by adding real-world engineering experience. +export const STEP5_REALITY_INJECTION = `Improve this article by injecting REAL production pain. -ADD: -- 2-3 realistic failure scenarios (specific, with model numbers and symptoms) -- Operational pain points (cleaning, cabling mistakes, wrong polarity, firmware issues) -- Things that go wrong during deployment (not just theory) -- At least 1 "I've seen this happen" story -- Specific CLI output examples where relevant +The article is currently too clean, too perfect. It reads like someone who read about networking, not someone who does networking. Fix that. -Make it feel like it comes from someone who has spent nights in data centers. +MANDATORY ADDITIONS (check that ALL exist, add if missing): -Do NOT add generic filler. Every addition must add real value. +1. AT LEAST 2 SPECIFIC FAILURE SCENARIOS with: + - Exact symptoms ("link flapping every 45 seconds", "CRC errors climbing at 200/min") + - Exact cause ("dirty MPO-12 end-face on port 3 of the trunk", "firmware 9.3.2 doesn't support DR4 breakout") + - Exact fix ("clean with IBC one-click, re-inspect with 400x scope, verify <0.5 dB insertion loss") + If the article doesn't have these, ADD them in a "What Breaks in Production" section. + +2. CABLING REALITY (add if missing): + - MPO polarity nightmare: "You ordered Type A cables for a Type B system. Half your links are crossed. That's a $15K re-termination job." + - SR4 to DR4 migration: "SR4 uses 8 fibers (4 Tx, 4 Rx). DR4 uses 8 fibers (4 parallel SMF). Different fiber, different patch panels, different everything." + - Cleaning: "An MPO-12 connector has 12 fiber end-faces. ONE dirty end-face = entire link degraded. You need an inspection scope, not just wipes." + +3. HIDDEN COSTS (add if missing): + - "Your $350 optic just cost you $2,400 in troubleshooting time because nobody cleaned the connector" + - "Re-cabling from MMF to SMF: $50-200 per drop × 200 drops = $10K-40K that wasn't in your optics budget" + - "Training your team on MPO handling: 2 days × 5 engineers × $1,500/day loaded cost = $15,000" + +4. QUALIFY ABSOLUTE STATEMENTS: + Find every sentence that says "X is cheaper than Y" or "X has dropped below Y" and add conditions. + BAD: "400G cost per Gbit is now below 100G" + GOOD: "In leaf-spine deployments with 50+ uplink ports, 400G cost per Gbit undercuts 100G by 30-40% — once you factor in switch density and power draw" + +5. "WHEN NOT TO" SECTION (add if missing): + Every technology has anti-patterns. If the article recommends something without saying when NOT to use it, add that section. Article: {{DRAFT}}`; @@ -265,23 +311,38 @@ Article: // STEP 9: QA CHECK // ═══════════════════════════════════════════════════════ -export const STEP9_QA_CHECK = `Review this article critically as a senior engineer. +export const STEP9_QA_CHECK = `Review this article critically as a senior engineer who has been in the field for 20 years. -CHECK: -1. Any technical inaccuracies? (wrong dBm values, wrong reach, wrong form factor specs) -2. Any over-simplifications that could mislead? (missing important caveats) -3. Missing real-world considerations? (power, cooling, cleaning, density) -4. Any sections that feel generic or weak? -5. Does the article have a clear opinion throughout? -6. Are there enough specific numbers and examples? -7. Would an experienced engineer learn something or just nod along? +HARD FAIL CHECKS (if ANY of these fail, the article is NOT publishable): -For each issue found: +1. PRODUCTION FAILURES: Does the article have at least 2 SPECIFIC failure scenarios with exact symptoms + causes + fixes? + → If not: ADD them. "DR4 link won't come up → wrong MPO polarity" is a real example. + +2. HIDDEN COSTS: Is there a section about costs nobody calculates? (cleaning, troubleshooting time, cabling redesign, training) + → If not: ADD it. + +3. "WHEN NOT TO USE": Does EVERY recommendation have an anti-pattern section? + → If not: ADD "When NOT to use this" for every technology recommended. + +4. ABSOLUTE STATEMENTS: Find EVERY sentence that makes an absolute claim without conditions. + → "400G is cheaper than 100G" → MUST become "In deployments with 50+ ports, 400G is cheaper per Gbit than 100G when factoring in density" + +5. CABLING REALITY: Is MPO polarity, cleaning, or fiber migration mentioned? + → If not: ADD it. This is the #1 operational pain point. + +QUALITY CHECKS: +6. Any technical inaccuracies? (wrong dBm, wrong reach, wrong specs) +7. Any sections that feel "too clean" or "too perfect"? → Make them messier, more real. +8. Does it sound like a real engineer or like a well-trained AI? → If AI, rewrite those sections. +9. Would an experienced engineer share this article? Or would they roll their eyes? +10. Is the hook BRUTAL enough? Does it grab in the first 2 sentences? + +For each issue: - Quote the problematic text - Explain what's wrong - Provide the corrected version -Then return the complete fixed article. +Return the COMPLETE fixed article. Article: {{ARTICLE}}`;