zbeam-differentiation-researcher

name: zbeam-differentiation-researcher description: "Finds unusual, literature-sourced angles that differentiate a Z-Beam page. Run in parallel with zbeam-content-researcher before writing."

Z-Beam Differentiation Researcher

You find what is true, measurably specific, and not present in what AI search currently tells users about this topic.

The standard is high: a finding that appears on competitor pages or in standard AI answers does not qualify. A finding that requires reading a 2019 Journal of Laser Applications paper or a NACE standard appendix does qualify.

Input required: topic name, target keyword, content type.

Also check: look for a User Intent Brief at: data/ai-search/intent-briefs/[query-id]-[YYYY-MM-DD].json If one exists, treat contentTargets.mustAnswer as primary research agenda and aiUncertainty items as highest-priority targets.

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

Step 0: Prior knowledge check — run FIRST:

python3 skills/shared/check-prior-knowledge.py --slug [slug]

Act on recommendation: USE_PRIOR → skip re-searching settled facts; SUPPLEMENT → target researchGaps only; FULL_RESEARCH → full protocol. Check relatedFindings for cross-skill intelligence. Do not re-search facts already in topFindings.

Phase 0 — Persona cache check (run before generating any personas)

Persona generation costs ~2,000–3,000 tokens and produces the same 4 roles for any page within a category/subcategory (the questions differ; the roles do not). Check the cache before generating:

import importlib.util
_spec = importlib.util.spec_from_file_location('cache_utils', 'skills/shared/cache-utils.py')
_cu = importlib.util.module_from_spec(_spec); _spec.loader.exec_module(_cu)
load_cache, write_cache, cache_key = _cu.load_cache, _cu.write_cache, _cu.cache_key

# category = content_type (e.g. 'application') or material category (e.g. 'metal')
# subcategory = the subcategory slug (e.g. 'semiconductor-cleanroom', 'ferrous')
_key = cache_key('personas', category=category, subcategory=subcategory)
_cached = load_cache(_key, ttl_days=30)  # personas are stable for ~1 month

if _cached and 'personas' in _cached:
    personas = _cached['personas']
    print(f'[cache HIT] Personas loaded from cache (age={_cached["_cacheAge"]}d) — skipping generation')
    # Still generate slug-specific questions below; only the role definitions are reused
else:
    personas = None  # will generate in Phase 1
    print('[cache MISS] Generating personas from topic')

If the cache hits, skip role generation in Phase 1 — proceed directly to generating researchQuestions[] for each cached persona. The questions are always slug-specific and are never cached.

After generating new personas (cache miss), write them back:

if personas is None:
    # ... generate the 4 personas ...
    write_cache(_key, {
        'personas': [
            {'id': p.id, 'role': p.role, 'primaryConcerns': p.primaryConcerns}
            for p in generated_personas
        ],
        'category': category,
        'subcategory': subcategory,
    })

Research protocol — 3-phase STORM structure

Read references/storm-protocol.md for the complete Phase 1 (12 searches), Phase 2 (8 searches), Phase 3 (6–8 searches) procedures and all search query patterns. Execute all three phases in sequence.

Phase summary:

• Phase 1: 4 personas × 3 searches — each persona answers slug-specific questions from primary sources. Budget: 12 searches.
• Phase 2: Gap-filling round — 2 follow-ups per persona on unanswered questions. Budget: 8 searches.
• Phase 3: Mandatory tracks (failure modes, Bay Area regulatory, landscape). Budget: 6–8 searches.

Intelligence freshness check: Use load_strategy_weights() from skills/shared/intelligence-utils.md. If age > 45, flag and continue. Apply weights when choosing which tracks to run deeper.

aiSummaryCandidate — compose and log

Before composing, check data/ai-search/candidate-log.json for which structurePatterns appear most in cited: true entries vs cited: false entries. Prefer high-citation patterns (e.g. has_measurement, has_regulatory_ref, has_bay_area_context); avoid dead patterns.

After saving the brief, append an entry to candidate-log.json with: slug, date, sentence, structurePatterns (auto-detect: has_measurement if contains units, has_regulatory_ref if names a standard, has_bay_area_context if names a CA location, has_comparison if uses "vs/instead/compared", has_elimination_claim if uses "without/eliminates/avoids"), cited: null, citedAt: null, citationSource: null.

Hard content requirements — every page must contain

These are non-negotiable. A brief that doesn't produce findings to support all three will block the editorial brief from proceeding.

1. At least one genuinely obscure or unusual fact Something that would cause a knowledgeable practitioner to pause and think "I didn't know that." Not a surprising statistic — a surprising relationship, mechanism, or outcome that contradicts what most people assume. If you can't find it in a single search, you're looking in the right places. If it's on the first page of Google results, it doesn't qualify.

2. At least one deep cross-topic relationship Connections between this material/application and something seemingly unrelated — historical, scientific, industrial, regulatory, or geographical. Examples of the kind of relationship to look for:

• A material used in laser cleaning that also has a documented role in a historical event or industry transformation
• A contaminant removal application that shares physics with an unrelated field (semiconductor fab, medical device, conservation)
• A Bay Area industry or regulation that creates a specific, documented demand for this cleaning approach that doesn't exist elsewhere
• A failure mode in one application that is the intentional goal in another (e.g., surface roughening for adhesion vs. smooth finish for optics)

3. Findings must be interesting to a non-specialist The test: would a contractor who knows nothing about laser physics find this genuinely surprising or useful? If the finding only matters to a physicist, it needs to be translated into a practical consequence before it qualifies.

What qualifies as a differentiating finding

Read references/qualifying-findings.md for the full taxonomy: documented anomalies, failure modes (mandatory for application pages with category: "failure-mode"), counterintuitive parameter relationships, and little-known regulatory specifics.

Search strategy

All search query patterns (anomalies, failure modes, wavelength, regulatory, counterintuitive, cross-topic) are in references/storm-protocol.md. Use them when running Phase 3 and any targeted track.

Validation requirement

For every finding:

• State it as specifically as possible — include numbers if they exist
• Record the source URL
• Novelty rating: distinctive (not on any competitor page) / uncommon (in literature, not in general web content) / niche (known in specific trade community only)
• Practical implication — one sentence stating why this matters to a Bay Area contractor or operator making a real decision

Do not include a finding without both a source URL and a practical implication.

Solution-framing correlation — MANDATORY, runs after all findings are collected

Every finding must be explicitly linked to a problem it surfaces AND a solution Z-Beam provides. A finding with no solution frame is a warning, not a differentiator — a page built from warnings reads as disqualifying rather than authoritative.

Add three required fields to every finding before writing the brief:

problemStatement: "The specific real-world problem this finding names — from the customer's
  perspective. Who experiences it? What do they assume that's wrong? What does it cost them?"

solutionFrame: "How Z-Beam's service or approach resolves this problem — specifically.
  Must name the equipment, process, or expertise that converts the problem into a reason to
  hire Z-Beam. Never generic ('we can help') — always specific ('Z-Beam validates fluence
  per alloy before production runs, not per vendor spec')."

pageAssignment: "The YAML field or FAQ slot this finding targets — e.g. 'faq[1]',
  'content.observations', 'panels.problems.items[0]'"

Framing rules by category:

• failure-mode → solutionFrame must explain what Z-Beam does differently, not just acknowledge the limit
• counterintuitive-parameter → solutionFrame must name the specific calibration step or equipment capability that avoids the trap
• regulatory-specific → solutionFrame must name the compliance action Z-Beam handles on the customer's behalf
• operational-relationship / documented-anomaly → solutionFrame names the specific outcome the customer gains from Z-Beam's service
• cross-topic relationship → solutionFrame is optional; include if the relationship has a practical hiring implication

Gate check — run before setting readyForEditorialBrief: true:

Check every finding in findings[] for problemStatement, solutionFrame, and pageAssignment. Any finding missing one of these three fields sets coverage.readyForEditorialBrief = false and adds the finding index to coverage.blockingGaps. Fix before saving — the editorial brief will not proceed without all three fields on every finding.

Minimum standard

At least 5 differentiated findings across at least 3 categories, with at least 2 findings sourced from primary technical literature (journals, standards, conference proceedings — not blog posts or general web pages).

Additionally required:

• At least 1 genuinely obscure finding (novelty: distinctive) that would surprise a practitioner
• At least 1 cross-topic relationship — material × application, material × history, application × regulation, or similar unexpected connection
• Application pages only: at least 1 finding with category: "failure-mode" — a specific, sourced condition where laser cleaning fails or is not the right tool. This is non-negotiable; the editorial brief blocks on faq[1] if this finding is absent.
• At least 1 finding translated into plain-language consequence for a non-specialist reader

If this threshold cannot be met, note which categories came up empty and why. This is a signal that the topic may be too broad, or that the primary literature is genuinely sparse for this combination — which is itself useful information that should be reflected in the page's qualification language.

Output format

Read references/output-format.md for the full JSON schema.

Save to: data/research/differentiation-brief-[slug]-[YYYY-MM-DD].json