Rebuild Section Agent Skill

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.