zbeam-generation-loop - SKILL.md Agent Skill

name: zbeam-generation-loop description: "Orchestrates write→validate→revise loop until PASS or 3-iteration cap. Use for single-section or full-page iteration."

Z-Beam Generation Loop

Pipeline position: editorial-brief → YOU → (page is publishable or flagged for human review)

What this skill does: Orchestrates other skills. It decides which skill to call, what minimal context to pass, and when to stop. It does not write, validate, or revise content directly.

Implementation scripts: skills/quality/zbeam-generation-loop/references/loop-scripts.py

Input

slug (required): the page slug, e.g. aluminum-laser-cleaning
mode (optional): new or update — auto-detected if omitted

slug         = '[slug]'   # ← fill at call time
mode         = None       # ← 'new' | 'update' | None (auto-detect in Step 0)
content_type = None       # ← 'material' | 'application' | 'new' (set in Step 0b)

Progress streaming via TaskCreate / TaskUpdate

One parent task at loop start; one child per step. Key tasks: Loop start, Step 0, Step 2 (Write pass N), Step 3 (Validate), Step 4a/4b (Skip-list/Revisor), Step 6/5 (final). No tasks for file reads or JSON log writes.

Step 0 — Auto-detect mode

frontmatter/applications/[slug].yaml  → mode = 'update'
frontmatter/materials/[slug].yaml     → mode = 'update'
(neither exists)                      → mode = 'new'
mode explicitly passed as 'prose'     → prose maintenance path (see Prose Mode section below)

Prose Mode (mode=prose)

Read references/prose-mode.md when mode=prose is set. Skip otherwise.

Step 0b — Detect content type

Check which frontmatter directory contains the slug file. Set content_type to material, application, or new. Load the section map for the correct type:

material → skills/quality/zbeam-section-executor/references/material-sections.json
application → skills/quality/zbeam-section-executor/references/application-sections.json
new → defer until after first write pass

Record dependencyTiers for section-mode pass ordering (Step 2 revision passes).

Step 0c — Confidence floor check

python3 skills/quality/zbeam-generation-loop/references/loop-scripts.py confidence_check [slug]

Result	Action
`OK` or `NO_BRIEF`	Continue to Step 1
`CONFIDENCE_FLOOR_FAIL`	Stop. Tell the user the brief lacks ≥3 quantitative data points and to run `zbeam-content-researcher` with a narrowed query before retrying.

Also write the instrumentation start record here via skills/shared/instrumentation.py.

Step 0d — Governance: prior knowledge check + hypothesis write

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

If USE_PRIOR or SUPPLEMENT: note prior findings and dead ends. If dead ends present, prefix hypothesis with "Prior dead ends — avoid: [deadEnds list]."

Infer hypothesis from editorial brief + mode — never ask the user:

new: "Writing [slug] targeting [keyword]. Hypothesis: data-dense page on [angle] enters top-20 impressions in 28 days."
update/improve: "Improving [slug] — fixing [dimensions]. Hypothesis: [specific fix] increases impressions for [keyword]."
prose: "Polishing [slug]. Hypothesis: jargon fixes bring FK ease above 35."

python3 skills/shared/change-log-utils.py write \
  --slug [slug] --skill zbeam-generation-loop --mode [new|update|improve|prose] \
  --hypothesis "[inferred — specific, testable, 28-day window]"

Step 1 — Check for existing validator output (skip logic)

Check data/audit/ for validation-[slug]-*.json (most recently dated).

Condition	Action
No file, or file not from today	Proceed to Write Pass (Step 2)
Today's file, result = PASS	Done — report PASS, skip everything
Today's file, result = FAIL/CONDITIONAL PASS	Skip write pass and first validate — go straight to Revisor (Step 4b), iteration = 1

Plan

Print the editorial brief summary, slug, content type, and mode, then proceed immediately — no approval required.

Step 2 — Write pass

mode = new: read skills/writing/zbeam-content-writer/SKILL.md, call with slug (always full page; section mode N/A for new).
mode = update: read skills/quality/zbeam-page-updater/SKILL.md, call with slug.

Revision passes (iteration ≥ 2): call zbeam-section-executor per failing section (not full page-updater). Pass slug, section, contentType, directive. Process in dependency-tier order; same-tier sections run concurrently.

Steps 2p, 2d, 2s — Polish, dedup, structural check

Read references/write-pass-checks.md for all three sub-steps:

2p — polisher script (runs after every write, before validation; errors re-enter Step 2)
2d — cross-section dedup check (revision passes only; dedup fixes don't increment iteration)
2s — structural validator (Exit 1 routes directly to revisor, skipping LLM validator)

Step 3 — Validate

Read skills/quality/zbeam-content-validator/SKILL.md, call with slug.

Capture result (PASS / CONDITIONAL PASS / FAIL) and failingDimensions (list of dimension IDs + failure reasons). Save raw output to data/audit/validation-[slug]-[date].json.

PASS or CONDITIONAL PASS → Step 5b (re-entry check)
FAIL → Step 4a (skip-list check)

Step 4a — Skip-list check

Maintain fail_history: dimension → [iteration numbers]. Two consecutive failures → add to human_review_flags.

human_review_flags non-empty → Step 4c (self-healing) before Step 5.
current_iteration >= 3 → Step 5 (MAX_ITERATIONS).
Otherwise → Step 4b (revisor).

Step 4b — Revisor pass

Read references/revisor-protocol.md → Step 4b for the full protocol: loop context write, RESEARCH_INSUFFICIENT circuit breaker, contextDiff build, and iteration-aware revisor call. After revisor completes, increment current_iteration, return to Step 2 (section mode).

Step 4c — Self-healing retry

Read references/revisor-protocol.md → Step 4c for the full self-healing protocol. Triggered when human_review_flags is non-empty AND current_iteration < 4. Cannot trigger twice for the same slug. If already_attempted: true → escalate to Step 5 immediately.

Step 5 — Stop conditions

HUMAN_REVIEW_REQUIRED

A dimension failed on two consecutive iterations AND self-healing (Step 4c) also failed.

Output: finalResult: HUMAN_REVIEW_REQUIRED, list of stuck dimensions and what revisor targeted.

Write end instrumentation record via skills/shared/instrumentation.py.

MAX_ITERATIONS

Three write → validate cycles completed without PASS.

Output: finalResult: MAX_ITERATIONS, all failing dimensions from last validator run.

Write end instrumentation record.

Step 5b — Re-entry check ("are you really done?")

python3 skills/quality/zbeam-generation-loop/references/loop-scripts.py reentry_check [slug] [contentType]

Checks: ≥2 quantitative figures claim-first, non-formulaic FAQ, commercial handoff, page.description ≥ 60 words, topic sentences, FAQ specificity. Failure + iteration < 3 → revisor. Failure + iteration ≥ 3 → HUMAN_REVIEW_REQUIRED.

Differentiation presence check: read references/differentiation-check.md and run. Miss + iteration < 3 → targeted revision pass. Miss + iteration ≥ 3 → HUMAN_REVIEW_REQUIRED.

Step 5c — Adversarial review

Read references/pass-protocol.md → Step 5c for the full adversarial review protocol: round count check, verdict routing table, and cap handling. If the main loop is at iteration 3, skip and go directly to Step 6.

Step 6 — Done (PASS)

Read references/pass-protocol.md → Step 6 for the full pass protocol: score drift log, red-team pass, eval scoring, and instrumentation record. (Governance hypothesis written at Step 0d.)

Steps 6b–6d — Post-pass gates

Read references/pass-protocol.md → Steps 6b–6d for: page count milestone (no action needed), HowTo spec gate (material pages only), and findings extraction to intelligence store.

Iteration log

Read references/iteration-log-schema.json for schema. Save to data/audit/generation-loop-[slug]-[date].json after every iteration (partial records survive crashes).

Token discipline rules

Read references/token-discipline.md.

Quick-reference flow

Read references/quick-reference.md for the full flow diagram.

⏸ COMMIT GATE

Never auto-commit. Summarize what changed, provide the git command, wait for Todd to run it.