authoring-analysis

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:

1. Understand how many columns each row should have
2. See where images vs content go
3. Match your content to the correct variant
4. 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