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-import 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-import - 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-import-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:

"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.

# 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:

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:

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:

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-import-html skill