Authoring Analysis

Determine authoring approach for EACH content sequence: default content or specific block.

When to Use This Skill

Use this skill when:

•You have page structure with content sequences (from identify-page-structure)
•You have block inventory (local + Block Collection)
•Ready to make authoring decisions following David's Model

Invoked by: page-migration skill (Step 3)

Prerequisites

From identify-page-structure skill, you need:

•✅ Section boundaries with styling notes
•✅ Content sequences per section (neutral descriptions)
•✅ Block inventory (local + Block Collection with purposes)
•✅ screenshot.png for visual reference

Related Skills

•page-migration - Orchestrator that invokes this skill
•identify-page-structure - Provides section structure and block inventory
•content-modeling - This skill invokes it when block selection is unclear
•block-collection-and-party - This skill invokes it to validate blocks
•generate-migration-html - Uses this skill's output to create HTML

IMPORTANT: Step 3e Execution Trigger

After completing Step 3 (analyzing all sequences), you MUST execute Step 3e if:

•✅ At least one section contains exactly ONE sequence that became a block
•✅ That section has distinct background styling from identify-page-structure

If NO sections meet these criteria → Skip Step 3e If ANY sections meet these criteria → Execute Step 3e for EACH qualifying section

Authoring Analysis Workflow

Context: You now have:

•Section boundaries with styles
•Content sequences per section
•Available block palette

FOR EACH content sequence, follow this mandatory process:

Step 3a: MANDATORY - Default Content Check (FIRST!)

Question: "Can an author create this with normal typing in Word/Google Docs?"

Default content means:

•✅ Headings, paragraphs, lists
•✅ Inline images within text
•✅ Simple quotes
•✅ Just... typing content

NOT default content means:

•❌ Repeating structured patterns (card grids, feature lists)
•❌ Interactive components (accordions, tabs, carousels)
•❌ Complex layouts (side-by-side columns, split content)
•❌ Requires specific structure for decoration

Decision:

•If YES (can type normally) → Mark as DEFAULT CONTENT, DONE ✅
•If NO (needs structure) → Proceed to Step 3b

Examples:

code

"Large centered heading, paragraph, two buttons"
→ Can author just type heading, paragraph, links? YES
→ Decision: DEFAULT CONTENT ✅

"Two centered buttons"
→ Can author just type two links? YES
→ Decision: DEFAULT CONTENT ✅

"Four items in grid, each with image, heading, description"
→ Can author just type this? NO - requires grid structure
→ Decision: Proceed to Step 3b ➡️

"Expandable questions and answers"
→ Can author just type this? NO - requires interaction/decoration
→ Decision: Proceed to Step 3b ➡️

Step 3b: Block Selection (ONLY IF NOT DEFAULT)

With block inventory context, ask: "Which available block would an author choose for this?"

DECISION TREE: When to Invoke content-modeling

OBVIOUS MATCH (Don't invoke content-modeling):

Pattern matches block purpose 1:1:

•"Grid of items with images/text" + see "cards" block → USE IT ✅
•"Expandable questions" + see "accordion" block → USE IT ✅
•"Tabbed content panels" + see "tabs" block → USE IT ✅
•"Side-by-side content" + see "columns" block → USE IT ✅
•"Rotating images" + see "carousel" block → USE IT ✅

Criteria for OBVIOUS:

•Content description matches block purpose exactly
•No ambiguity about structure
•Block exists in inventory

UNCLEAR MATCH (Invoke content-modeling):

Ambiguous which block to use:

•"Three items with images" - Could be cards? Could be columns? → INVOKE
•"List of features with icons" - Cards? Custom list block? → INVOKE
•"Customer quotes with photos" - Quote block? Cards? Testimonial block? → INVOKE

Missing from inventory:

•Content needs structure BUT no matching block exists → INVOKE
•content-modeling can recommend canonical model or suggest creating custom block

Complex authoring consideration:

•"Hero-like content but in middle of page" → INVOKE
•"Card-like items but only 2 of them" → INVOKE
•Need validation on author mental model → INVOKE

Criteria for UNCLEAR:

•Multiple blocks could work
•No obvious block match
•Need authoring perspective validation
•Creating custom block might be needed

Step 3c: Validate Block Exists (IF NEEDED)

Only if block not in Block Collection common set:

Invoke block-collection-and-party skill to:

•Confirm block exists
•Get live example URL
•Review content model

Step 3d: Get Block HTML Structure (BEFORE generating HTML)

CRITICAL: Before generating any HTML in next skill, fetch the pre-decoration HTML structure for ALL blocks you'll use.

bash

# Get structure examples for each block
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js cards
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js tabs
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js accordion
node .claude/skills/block-collection-and-party/scripts/get-block-structure.js columns

Why this prevents mistakes:

•Shows exact row/column structure (e.g., cards: each card = 1 row with 2 columns)
•Reveals all variants (e.g., "Cards" vs "Cards (no images)")
•Displays clean HTML without decoration
•Prevents the #1 HTML generation error: wrong structure

Use the output to:

•Understand how many columns each row should have
•See where images vs content go
•Match your content to the correct variant
•Generate HTML that matches the expected structure exactly

Step 3 Output Format

Complete analysis for all sequences:

code

Section 1 (light):
  - Sequence 1: "Large centered heading, paragraph, two call-to-action buttons"
    → Decision: DEFAULT CONTENT
    → Reason: Author can type heading, paragraph, links normally
    → Note: Prominent styling is a CSS concern

  - Sequence 2: "Two images side-by-side"
    → Decision: Columns block (2 columns)
    → Reason: Side-by-side layout requires structure
    → Obvious match with "columns" block in inventory

Section 2 (light):
  - Sequence 1: "Centered heading"
    → Decision: DEFAULT CONTENT
    → Reason: Just a heading - author types it

  - Sequence 2: "Grid of 8 items, each with icon and short text"
    → Decision: Cards block
    → Reason: Repeating structured pattern, needs block
    → Obvious match with "cards" block in inventory

  - Sequence 3: "Two centered buttons"
    → Decision: DEFAULT CONTENT
    → Reason: Just two links - author types them

Section 3 (grey):
  - Sequence 1: "Eyebrow text, heading, paragraph, button stacked vertically"
    → Decision: DEFAULT CONTENT
    → Reason: Author types text and link normally

  - Sequence 2: "Four items in grid, each with image, category tag, heading, description"
    → Decision: Cards block
    → Reason: Repeating structured pattern
    → Obvious match with "cards" block in inventory

Section 4 (dark):
  - Sequence 1: "Tab navigation with three switchable content panels"
    → Decision: Tabs block
    → Reason: Interactive component, needs decoration
    → Obvious match with "tabs" block in inventory

Step 3e: Validate Section Styling (Single-Block Sections Only)

⚠️ EXECUTION TRIGGER: This step is executed AFTER Step 3 is complete. Execute this step if and only if:

•✅ You have completed Step 3 (identified which sequences become blocks)
•✅ At least one section contains exactly ONE sequence that became a block
•✅ That section has distinct background styling from identify-page-structure

If NO sections meet these criteria → Skip Step 3e entirely and proceed to next skill

If ANY sections meet these criteria → You MUST execute all sub-steps below for EACH qualifying section

Why this validation matters:

When a section contains a single block, the background styling might be:

•Block-specific design (e.g., hero with dark background image) → Don't add section-metadata
•Section container styling (e.g., dark section with tabs block) → Add section-metadata

Without validation, we risk adding unnecessary section-metadata that conflicts with block styling or makes authoring more complex.

Sections with multiple sequences: Always keep section-metadata (styling applies to all content, not validated in Step 3e)

For EACH section with exactly one block, execute ALL these sub-steps:

Sub-step 1: Identify the candidate sections

Review your Step 3 output. Find sections where:

•Section contains exactly 1 content sequence
•That sequence became a block (not default content)
•Section has distinct background styling from identify-page-structure

Example:

code

Section 1 (dark blue):
  - Sequence 1: Large centered heading, paragraph, two buttons
    → Decision: Hero block

Section 3 (grey):
  - Sequence 1: Tab navigation with three switchable panels
    → Decision: Tabs block

Sub-step 2: For each candidate section, examine the screenshot

Open screenshot.png and examine the section visually.

Ask these questions:

Q1: Is the background an image (photo, gradient, illustration)?

•If YES → Likely block-specific design
•If NO (solid color) → Continue to Q2

Q2: Does the content fill the colored area edge-to-edge, or is there visible section padding?

•Edge-to-edge (full-bleed) → Likely block-specific design
•Visible padding around content → Likely section container styling

Q3: Does the block type typically have its own background styling?

•Hero, banner, full-width CTAs → Often have own backgrounds
•Tabs, accordion, cards, columns → Often use section backgrounds

Sub-step 3: Make the decision

Based on your analysis, decide for each single-block section:

SKIP section-metadata if:

•Background is an image/gradient (block-specific)
•Content is full-bleed/edge-to-edge (no section padding visible)
•Block type typically has intrinsic background (hero, banner)

KEEP section-metadata if:

•Background is solid color with visible section padding
•Block type typically inherits section styling (tabs, cards, accordion)
•Styling clearly provides container context (not block design)

Sub-step 4: Document your decisions

For each validated section, note:

•Section number
•Block type
•Background analysis (image vs solid, full-bleed vs padded)
•Decision (keep or skip section-metadata)
•Reason

Example output:

code

VALIDATED SECTIONS:

Section 1 (dark blue):
  - Block: Hero
  - Background: Full-width dark blue gradient image
  - Layout: Edge-to-edge, no visible section padding
  - Decision: SKIP section-metadata
  - Reason: Background is hero's design, not section styling

Section 3 (grey):
  - Block: Tabs
  - Background: Solid grey (#f5f5f5)
  - Layout: Content centered with visible padding (~80px on sides)
  - Decision: KEEP section-metadata style="grey"
  - Reason: Section provides container styling for tabs block

When in doubt:

If you're uncertain whether background is block-specific or section-wide:

•Default to KEEPING section-metadata (safer, easier for authors to remove than add)
•Add a note in your documentation explaining the ambiguity
•Consider asking the user for guidance

Step 3e Completion Checklist:

Before proceeding to next skill, verify you have completed:

•✅ Identified all single-block sections with background styling
•✅ Examined original screenshot for EACH candidate section
•✅ Answered Q1, Q2, Q3 for EACH candidate section
•✅ Made skip/keep decision for EACH candidate section
•✅ Documented reasoning for EACH decision
•✅ Updated section styling notes with validated decisions

Final Output

This skill provides complete authoring analysis:

1. Authoring decisions for all sequences:

•Each sequence marked as DEFAULT CONTENT or specific block name
•Reasoning documented

2. Block structures fetched:

•HTML structure examples for all blocks to be used

3. Section styling validation (if applicable):

•Updated section list with validated styling decisions
•Some sections may be marked "no section-metadata"

Next step: Pass these outputs to generate-migration-html skill