zbeam-editorial-brief

name: zbeam-editorial-brief description: "Turns research briefs into a precise writing directive. Run after both briefs are complete, before zbeam-content-writer."

Z-Beam Editorial Brief

You operate in one of two modes depending on whether you are creating a new page or updating an existing one. Determine the mode from context or from an explicit instruction.

Mode A — new-page: no existing frontmatter file for this topic. Full directive: score all findings, assign to sections, draft the summary target, produce sibling divergence constraints. The content-writer consumes this output.

Mode B — update: an existing frontmatter file already exists. Targeted directive: identify what the existing page lacks (sourced data, diverse FAQs, unusual effects), produce enrichment directives only for those gaps. Do not produce section assignments or a full writing directive — the page-updater consumes this output.

Determine which mode applies before proceeding. If unclear, check whether frontmatter/[contentType]/[slug].yaml exists — if yes, Mode B.

You are making the editorial decisions that turn research into a directive. The content writer (Mode A) or page-updater (Mode B) follows this brief — neither makes independent editorial judgments.

The goal: a finished page where every significant prose decision is traceable to a specific finding, ranked by its citation potential. No section should be written from general knowledge when a sourced specific fact is available.

Input required:

data/research/content-brief-[slug]-[YYYY-MM-DD].json
data/research/differentiation-brief-[slug]-[YYYY-MM-DD].json

Optionally:

data/ai-search/intent-briefs/[query-id]-[YYYY-MM-DD].json
data/research/category-data/[category]-[subcategory]-[YYYY-MM-DD].json

Output: save to data/research/editorial-brief-[slug]-[YYYY-MM-DD].json

Research readiness check — run first (mandatory)

python3 skills/writing/zbeam-editorial-brief/references/editorial-utils.py readiness_check [slug]
# Exits 0 = GO, 1 = AT_RISK (note in preGenWarnings), 2 = BLOCKED (stop)

Do not proceed to the Intelligence freshness check until this passes.

Step 0a: Perspective reconciliation (run before sibling audit, after readiness check)

Read references/pre-scoring-checks.md → Step 0a for the full protocol: coverage audit (zero-findings personas), tension mapping (conflicting persona findings), and section shaping (dominant perspective → problems/faq assignment). Produces perspectiveReconciliation output block.

Step 0b: Numeric conflict resolution (run before scoring, after sibling audit)

Read references/pre-scoring-checks.md → Step 0b for the full conflict resolution protocol: same-vs-different-scenario discrimination, citation-strength tie-breaking, and numericConflicts output key format. Pass numericConflicts to the writer directive.

Intelligence freshness check

Use load_strategy_weights() from skills/shared/intelligence-utils.md. If age > 45, flag and continue. Apply weights when scoring findings in Step 1: high-weight dimension → +1 to score; low-weight → −1.

Mandatory brief elements (required in every editorial brief)

• Topic sentence directives: for each major section (introduction, context, observations, processNotes), provide a draft topic sentence that states the main point first. The writer must not deviate from this structure.
• FAQ requirements: for each FAQ item, provide the key number or named standard that must appear in the answer. An FAQ answer without a number or named standard fails Dim 4.

Step 0: Sibling divergence audit (run before scoring)

Cache check first — sibling audits are expensive (~10 file reads) and the sibling set changes only when new pages are published. Use load_cache('sibling-audit', ttl_days=7) from skills/shared/cache-utils.py; on HIT, use siblingDivergenceConstraints directly. On MISS, read references/step0-sibling-audit.md and execute it, then write results back with write_cache.

Produces siblingDivergenceConstraints — hard rules the writer must not violate.

Step 1: Score every finding for citation potential

Read all findings from both briefs. Score each on three dimensions and compute a total:

Maximum score: 9. Findings scoring 7–9 are Tier 1 — they must appear prominently. Findings scoring 4–6 are Tier 2 — they should appear somewhere. Below 4 are supporting context only.

Output cap: include all Tier 1 findings, but cap Tier 2 at the top 5 by score. Drop below-4 findings entirely.

Tier 1 gate — check before proceeding to Step 2:

Count findings scoring 7+. If fewer than 2: set readyToWrite: false, list blockingGaps, tell user to return to researchers. Do not proceed to Steps 2–5.

If 2+ Tier 1 findings exist, record tier1Count and continue.

Step 2: Assign Tier 1 findings to sections

Determine content type first — check whether frontmatter/applications/[slug].yaml (application) or frontmatter/materials/[slug].yaml (material) is involved. The section map differs completely.

Read references/section-assignment.md for the full Step 2A (application) and Step 2B (material) assignment maps including field names, ordering rules, and GSC commands.

Step 2c: Topic alignment — runs after Step 2A/2B, before Step 2b prose ordering

Read references/topic-alignment.md and execute it now.

Purpose: validates that each finding's solutionFrame actually advances its assigned section's argument — not just that it belongs to the same broad category. A finding categorized as "regulatory" and assigned to a regulatory section can still be misaligned if its solutionFrame addresses a different problem than the section's topic statement.

What it produces per finding:

• relationship — central | supporting | qualifying | additive | misaligned
• placementInstruction — exactly where in the section this finding belongs
• topicSentenceRequired — true if the finding needs its own opening claim (additive/misaligned→reassigned)
• topicSentenceDraft — starter sentence the writer must use when topicSentenceRequired: true

What it produces for the brief:

• topicAlignmentLog — relationships summary, reassignments, new FAQ items created

The writer (content-writer or page-updater) must follow placementInstruction and topicSentenceRequired for every finding. A finding with topicSentenceRequired: true that is bolted onto an existing paragraph without its own topic sentence fails Dim 2 (claim-first sequencing).

Step 2b: Prose ordering mandate

Read references/prose-ordering-mandate.md for the three rules (differentiation findings lead, topic sentence structure, general-audience readability) with compliant/non-compliant examples and the required proseOrderingMandate output key. Apply to every section directive — the validator checks for violations.

Step 3: Identify what must not be written generically

For each content section, explicitly state what the writer must NOT fall back on — specific regulatory rule numbers over "BAAQMD compliance required", specific fluence ranges over "appropriate laser parameters", specific failure conditions over "results may vary".

Step 4: Handle data gaps explicitly

If dataDensityAssessment.meetsMinimumThreshold is false, specify how the writer handles each gap:

• No fluence data → qualified language ("published fluence data for this specific application is limited; parameters should be validated on representative samples")
• No California regulation → federal standard only + "confirm current Bay Area requirements with your EHS team"
• No primary literature → note directly in limitations

Step 5: Draft the page.description target

Draft 2–4 sentences with: specific material or application + primary cleaning challenge, single most citable quantitative finding with source, Bay Area/California regulatory or industry context, one claim from obscureFacts or crossTopicRelationships.

Mandatory output. If research briefs don't supply enough data for a dense page.description, the page is not ready — return to the researcher.

Steps 5b–5d: Output targets

Read references/output-targets.md for Steps 5b (summary target for application pages), 5c (citableSentences propagation + plain-language companion rule + aiSummaryCandidate), and 5d (SERP pageTitle/metaDescription targets with character count requirements).

Finding score drift (adaptive calibration — run before scoring)

python3 skills/writing/zbeam-editorial-brief/references/editorial-utils.py drift_calibration [category]

Apply drift signals when scoring: downgrade finding types with high drop rates by 1 point; upweight finding types with high survival rates by 1 point. Document adjustments in the editorial brief under scoringAdjustments.

After loop PASS — write back to drift log (called by the generation loop, not inline here):

python3 skills/writing/zbeam-editorial-brief/references/editorial-utils.py drift_writeback [slug] [content_type]

Output format

Read references/output-schema.md for the full Mode A JSON schema. Save to data/research/editorial-brief-[slug]-[YYYY-MM-DD].json.

If readyToWrite is false, explain what is blocking — missing briefs, insufficient data, or a topic that needs narrowing.

Mode B output format

Read references/mode-b-schema.md for the full Mode B JSON schema (existing page updates only).

The editorial brief is a fast step — reads existing files and makes decisions. Do not do web searches in this skill.