authoring-analysis

SKILL.md

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