zbeam-section-executor - SKILL.md Agent Skill

name: zbeam-section-executor description: "Executes a single section update on an existing Z-Beam frontmatter page. Called by generation loop or page orchestrator — never chooses what to update."

Z-Beam Section Executor

Purpose

This skill does ONE thing: apply a targeted update to a single named section of an existing frontmatter page. The generation loop and page orchestrator are the orchestrators — this skill never decides what to update or in what order. It receives a directive and executes it.

Input (passed as args or from orchestrator context)

slug — page slug (e.g., steel-laser-cleaning)
section — section name (e.g., faq, characteristics, laserInteraction)
contentType — material or application
directive — the section-specific directive block extracted from scored findings or editorial brief

Step 1: Load section map

Select the reference file based on contentType:

# material
cat skills/quality/zbeam-section-executor/references/material-sections.json

# application
cat skills/quality/zbeam-section-executor/references/application-sections.json

From the map, extract for the target section:

yamlPath — where in the YAML to read/write
dataSource — which input to draw from
referenceFile — section-specific guide to load next

Step 2: Load section guide

Load only the named referenceFile for this section — not all guides at once:

cat skills/quality/zbeam-section-executor/[referenceFile]

Step 3: Extract only the relevant YAML section

Never full-load the page YAML. Extract only the target section using python:

python3 -c "
import yaml, json, sys
data = yaml.safe_load(open('frontmatter/[contentType]s/[slug].yaml'))
# Navigate yamlPath: e.g. 'body.characteristics' -> data['body']['characteristics']
path = '[yamlPath]'.split('.')
node = data
for key in path:
    node = node.get(key, {})
print(json.dumps(node, indent=2))
"

Record the before-state of every field you will touch.

Step 4: Load only the relevant data source

Load only the data listed in dataSource — not the full editorial brief or category package:

python3 -c "
import json, glob, sys
# For categoryPackage sources:
pkg = sorted(glob.glob('data/research/category-data/*.json'))[-1]
data = json.load(open(pkg))
# Navigate to dataSource path — e.g. 'categoryPackage.dataCardSources'
print(json.dumps(data.get('[sourceKey]', {}), indent=2))
"

# For editorialBrief sources:
python3 -c "
import json, glob
brief = sorted(glob.glob('data/research/editorial-brief-[slug]-*.json'))[-1]
data = json.load(open(brief))
# Navigate to sectionDirectives.[section]
print(json.dumps(data.get('sectionDirectives', {}).get('[section]', {}), indent=2))
"

Step 5: Apply changes via surgical text replacement

Use the Edit tool with exact string matching. Never use yaml.dump() — it reformats folded scalars, list indentation, and scalar quoting, breaking the renderer even when YAML is technically valid.

For single-line values, use sed. For multi-line blocks, use the Edit tool with sufficient surrounding context to make the match unique.

Apply only what the directive specifies. Preserve every field not explicitly in scope.

Step 6: PARAGRAPH_STRUCTURE_RULE check

After writing any heading description, run:

import yaml
data = yaml.safe_load(open('frontmatter/[contentType]s/[slug].yaml'))
path = '[yamlPath]'.split('.')
node = data
for key in path:
    node = node.get(key, {}) if isinstance(node, dict) else {}
desc = node.get('heading', {}).get('description', '') if isinstance(node, dict) else ''
word_count = len(desc.split())
if word_count >= 80 and '\n' not in desc:
    print(f'PARAGRAPH_STRUCTURE_RULE FAIL: {word_count}w with no paragraph break — insert blank line between topic shifts in the >- block')
else:
    print('Paragraph structure: OK')

A heading description >= 80 words with no paragraph break is a blocking failure. Fix before proceeding.

Step 7: Plain-language check

Every prose field written must contain at least one sentence with no domain vocabulary:

import re, yaml
DOMAIN_VOCAB = re.compile(
    r'\b(fluence|ablation|J/cm²|pulse duration|repetition rate|photomechanical|'
    r'photothermal|HAZ|thermal diffusivity|absorptivity|reflectivity|passivation|'
    r'delamination|microhardness|wettability|magnetite|hematite|Fe2O3|Fe3O4|MRR)\b',
    re.IGNORECASE)
sentences = [s.strip() for s in re.split(r'[.!?]', desc) if len(s.strip()) > 20]
plain = [s for s in sentences if not DOMAIN_VOCAB.search(s)]
if not plain:
    print('PLAIN-LANGUAGE FAIL: zero plain sentences — must fix before returning result')
else:
    print(f'Plain-language: OK ({len(plain)} plain sentence(s))')

Zero plain sentences is a blocking failure.

Step 8: Validate YAML

python3 -c "import yaml; yaml.safe_load(open('frontmatter/[contentType]s/[slug].yaml'))" && echo "YAML valid"

If invalid, revert to before-state and report the error.

Step 9: Return result

Return exactly:

section — the section name that was executed
result — pass or fail
blockingIssues — list of any unresolved PARAGRAPH_STRUCTURE_RULE or PLAIN-LANGUAGE failures, or YAML validation errors

What this skill must NOT do

Read the full page YAML beyond the target section
Load the full editorial brief (load only sectionDirectives.[section])
Run the full pipeline gate check (validate:gate:core)
Write to any file other than the target page YAML
Decide what section to run or in what order — that is the orchestrator's job
Use yaml.dump() for any write operation