authoring-analysis

What this skill does

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

```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:**
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,