| name | rebuild-section |
| description | R4a of the design-qa escalation ladder — rebuild ONE divergent section into canonical, editable WordPress core blocks from its source HTML, screenshots, spec, and design tokens, when R1–R3 (CSS / spec-rebuild / re-extract) could not reach visual parity. Dispatched as a subagent by design-qa; not user-invocable. Output ships ONLY if it re-scores `match` and survives canonicalization with no content loss — otherwise the loop falls to the R4b styled-island floor. |
| disable-model-invocation | true |
When to use me
You are a subagent dispatched by design-qa for one section that is still
divergent after R1 (theme/CSS), R2 (rebuild block markup from spec), and R3 (re-extract
spec). Your job is R4a: author native WordPress core blocks that reproduce this
section's layout and content faithfully, from richer inputs than R2 had (the source HTML and
the rendered screenshots, not just the spec).
Do not use me to invent content, to redesign, or to "improve" the section. Reproduce the
source. If you cannot reach match within the gates below, say so plainly and return your
best attempt — the orchestrator falls to R4b (a deterministic styled-island floor),
which is the correct outcome, not a failure on your part.
Inputs the orchestrator gives you
- The section's
SectionParity record — which signals tripped (section-dropped,
bg-color, column-flatten, media-dropped, unstyled-island) and the evidence samples.
These tell you exactly what is wrong; fix those, don't guess.
- The section's source HTML and its
styledHtml (computed-style-inlined snapshot) —
the ground truth for layout and content.
- Source and replica section screenshots (cropped to the band) — what it should look like
vs. what shipped.
- The
SectionSpec (headings, body, cells, images, columnCount, backgroundColor).
design-foundation.json tokens (color / typography / spacing roles) — use these so the
output is on-theme, not hardcoded values.studioSitePath (e.g. ~/Studio/example-com) + themeSlug — locate the installed theme so the variation inventory (styles/blocks/*.json) can be listed; the dispatching orchestrator passes both.
What to produce
Native WordPress block markup reproducing the section: core/columns + core/column for
multi-column bands, core/group for backgrounds/spacing, core/heading, core/paragraph,
core/image, core/buttons/core/button, core/list, etc.
Canonicalization constraint (hard): sizing and styling MUST survive
@wordpress/blocks serialize→parse. Use core block attributes and class names
(align, width, style.spacing, backgroundColor/textColor token slugs, layout)
— never inline <figure style="..."> or ad-hoc inline styles on block wrappers, which
the canonicalizer strips ([[project_block_fixer_canonicalization_constraint]]). When a value
maps to a design-foundation token, reference the token slug, not a raw hex/px.
Styling decisions: follow skills/replicate-with-blocks/styling-priority.md — the preset→patch→instance→variation→layout→CSS cascade, the structured-props cheat sheet, and the hard bans (no raw style="" attrs, no invented className CSS hooks). Native blocks only; core/html islands are exempt.
Existing block style variations — inventory first. Before emitting ANY new style, list <studioSitePath>/wp-content/themes/<themeSlug>/styles/blocks/*.json. Each file is a registered variation (slug, title, blockTypes, styles). When one matches what the section needs, REUSE it: apply is-style-<slug> on the block. NEVER redeclare an existing slug, never invent an is-style-* class with no backing file. New variations follow styling-priority.md option 5 (recurring + nameable only) and are written as a new styles/blocks/<slug>.json file (slug lib- prefixed) plus the class on each claiming block.
Preserve ALL source content — every heading, paragraph, list item, button label, and
image in the source section must appear in your output. Do not truncate, dedupe, or drop
([[feedback_never_lose_source_content]]). If the source shows a heading and an identical
paragraph, reproduce both.
Acceptance gates — your output ships ONLY if ALL pass
The orchestrator runs these after you return. Author with them in mind; you cannot
self-accept — acceptance is the measured re-score, not your assertion.
- Block-markup oracle — the markup parses cleanly via the WordPress block parser
(
liberate_validate_artifacts). No malformed blocks, no injection vectors.
- Canonicalization round-trip — survives
@wordpress/blocks serialize→parse with no
attribute/class loss (the block-fixer check). If a style would be stripped, you used the
wrong mechanism — move it to a core attribute/className.
- Re-measured
section-parity = match — after reinstall + re-capture, all five robust
signals clear: section present, bgDeltaE ≤ 10, columnCountMatch, media present, not an
unstyled island. A 3 → 1 column collapse, a wrong background, or a dropped image FAILS.
- Content coverage = no loss (
measureSectionCoverage) — every captured text item and
image is present in your markup.
If any gate fails, the rung fails and the loop falls to R4b. That is a valid, faithful
floor (the styled island renders pixel-accurate, just not block-editable) — never argue a
failed rebuild into a pass, and never ship a flatten or an unstyled island as a "known gap"
([[feedback_honest_visual_assessment]], [[project_faithful_recreation_enforcement]]).
Method
- Read the divergence reasons first — they scope the fix.
- Read the
styledHtml to recover the true layout (column count, alignment, backgrounds)
and the source HTML for the exact content and structure.
- Map the layout to core blocks: a row of N cards →
core/columns with N core/column;
a text-over-photo band → core/cover; a media-beside-text → core/columns (one column
image, one text). Match the source column count exactly.
- Resolve colors/fonts/spacing to
design-foundation token slugs.
- Return the block markup. The orchestrator reinstalls, re-captures, and re-scores.
Stay generic
Derive everything from the inputs for THIS section. Never hardcode a site's colors,
filenames, copy, or section order ([[feedback_scripts_must_be_site_agnostic]]). The same
skill must rebuild any platform's bespoke section.
