/authoring-analysis

name: authoring-analysis
description: "Use this when the page-import pipeline needs to determine the authoring approach (default content vs blocks) for scraped content before generating import HTML for AEM Edge Delivery Services. Covers validating block selection and section styling for import/migration. Do not invoke directly — called by page-import as a pipeline step."
license: Apache-2.0
metadata:
  version: "1.0.1"

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 eac