---
name: "SEO SXO"
repo: https://github.com/agricidaniel/claude-seo
source: https://github.com/agricidaniel/claude-seo/blob/HEAD/skills/seo-sxo/SKILL.md
license: "MIT"
install: "npx skills add agricidaniel/claude-seo --skill seo-sxo"
page: https://100xlab.com/resources/agent-skills/agricidaniel-claude-seo--seo-sxo--7nzj72
---

# Search Experience Optimization (SXO)

SXO bridges the gap between SEO (what Google rewards) and UX (what users need).
Traditional SEO audits check technical health. SXO asks: "Does this page deserve
to rank for this keyword based on what Google is actually rewarding in the SERP?"

## Core Insight

A page can score 95/100 on technical SEO and still fail to rank because it is the
**wrong page type** for the keyword. If Google shows 8 product pages and 2 comparison
pages for your keyword, your blog post will never break through -- no matter how
well-optimized it is.

## Commands

| Command | Purpose |
|---------|---------|
| `/seo sxo <url>` | Full SXO analysis (auto-detect keyword from page) |
| `/seo sxo <url> <keyword>` | Full SXO analysis for a specific keyword |
| `/seo sxo wireframe <url>` | Generate IST/SOLL wireframe with concrete placeholders |
| `/seo sxo personas <url>` | Persona-only scoring (skip SERP analysis) |

## Execution Pipeline

### Step 1: Target Acquisition

1. Fetch the target URL via `scripts/render_page.py --mode auto` (SPA-aware and SSRF-safe)
2. Parse with `scripts/parse_html.py` to extract: title, H1, meta description,
   headings hierarchy, word count, schema markup, CTAs, media elements
3. If no keyword provided, extract primary keyword from title tag + H1 overlap
4. Validate keyword is non-empty before proceeding

### Step 2: SERP Backwards Analysis

Read `references/page-type-taxonomy.md` for classification rules.

1. Search Google for the target keyword (WebSearch)
2. For each of the top 10 organic results, record:
   - URL and domain authority tier (brand / niche authority / unknown)
   - Page type (classify using taxonomy)
   - Content format (long-form, listicle, how-to, comparison, tool, video)
   - Word count estimate (from snippet length and page structure)
   - Schema types present (from SERP features: ratings, FAQ, HowTo)
   - Media signals (video carousel, image pack, thumbnail presence)
3. Record SERP features present:
   - Featured snippet (paragraph / list / table / video)
   - People Also Ask (extract all visible questions)
   - Ads (top and bottom -- count and analyze ad copy themes)
   - Related searches (extract all)
   - Knowledge panel / local pack / shopping results
   - AI Overview presence and source types
4. Calculate SERP consensus:
   - Dominant page type (>60% = strong consensus, 40-60% = mixed, <40% = fragmented)
   - Content depth expectations (average word count tier)
   - Schema expectation (most common structured data types)
   - Media expectations (video required? images critical?)

### Step 3: Page-Type Mismatch Detection

This is the core SXO insight. Compare target page type against SERP consensus.

**Mismatch severity levels:**

| Target Type | SERP Expects | Severity | Recommendation |
|-------------|-------------|----------|----------------|
| Blog Post | Product Pages | CRITICAL | Create dedicated product page |
| Blog Post | Comparison | HIGH | Restructure as comparison with matrix |
| Product | Informational | HIGH | Add educational content layer |
| Landing Page | Tool/Calculator | HIGH | Build interactive tool component |
| Service Page | Local Results | MEDIUM | Add location signals + local schema |
| Any type match | - | ALIGNED | Focus on content depth and UX |

**Classification rules:**
- Classify target page using `references/page-type-taxonomy.md`
- Classify each SERP result using the same taxonomy
- Flag mismatch if target type differs from SERP dominant type
- If SERP is fragmented (no dominant type), note opportunity for differentiation

### Step 4: User Story Derivation

Read `references/user-story-framework.md` for the full framework.

From SERP signals, derive user stories:

1. **PAA questions** reveal knowledge gaps and concerns
2. **Ad copy themes** reveal commercial triggers and value propositions
3. **Related searches** reveal the search journey (what comes before/after)
4. **Featured snippet format** reveals the expected answer structure
5. **AI Overview** reveals what Google considers the definitive answer

For each signal cluster, generate a user story:
```
As a [persona derived from signal],
I want to [goal derived from query intent],
because [emotional driver from ad copy / PAA tone],
but I'm blocked by [barrier derived from PAA questions / related searches].
```

Generate 3-5 user stories covering the primary intent angles.

### Step 5: Gap Analysis

Compare the target page against SERP expectations across 7 dimensions:

| Dimension | What to Compare | Score |
|-----------|----------------|-------|
| Page Type | Target type vs SERP dominant type | 0-15 |
| Content Depth | Word count, heading depth, topic coverage | 0-15 |
| UX Signals | CTA clarity, above-fold content, mobile layout | 0-15 |
| Schema Markup | Present vs expected structured data types | 0-15 |
| Media Richness | Images, video, interactive elements vs SERP norm | 0-15 |
| Authority Signals | E-E-A-T markers, social proof, credentials | 0-15 |
| Freshness | Last updated, date signals, content recency | 0-10 |

**Total: 0-100 SXO Gap Score** (lower = larger gap, higher = better alignment)

### Step 6: Persona-Based Scoring

Read `references/persona-scoring.md` for methodology.

1. Derive 4-7 personas from SERP intent signals:
   - Cluster PAA questions by theme
   - Segment ad copy by target audience
   - Map related searches to journey stages
2. For each persona, score the target page on 4 dimensions (25 pts each):
   - **Relevance**: Does the page address this persona's need?
   - **Clarity**: Can this persona find their answer within 10 seconds?
   - **Trust**: Are there adequate trust signals for this persona?
   - **Action**: Is there a clear next step for this persona?
3. Output persona cards with scores and specific improvement recommendations
4. Sort recommendations by weakest persona first (biggest opportunity)

### Step 7: Wireframe Generation (Optional)

Only execute when `/seo sxo wireframe` is invoked.

Read `references/wireframe-templates.md` for templates.

1. Generate IST (current state) wireframe from parsed page structure
2. Generate SOLL (target state) wireframe based on:
   - SERP consensus page type
   - Gap analysis findings
   - Persona scoring weaknesses
3. Use ultra-concrete placeholders:
   - NOT: "Add a CTA here"
   - YES: "Add pricing CTA with annual savings badge below hero, linking to /pricing#enterprise"
4. Output as semantic HTML section outline with annotations

## DataForSEO Integration

If DataForSEO MCP tools are available:

1. **Before any API call**, run cost estimate and confirm with user
2. Use `google_organic_serp` for precise SERP data (positions, features, snippets)
3. Use `keyword_data` for search volume and competition metrics
4. Fall back to WebSearch if DataForSEO unavailable -- note reduced precision in output

## SXO Score vs SEO Health Score

The SXO score is **separate** from the main SEO Health Score.

- SEO Health Score = technical compliance (crawlability, speed, schema, etc.)
- SXO Gap Score = alignment between page and SERP expectations
- A page can score 95 SEO + 30 SXO = technically perfect but strategically misaligned
- Both scores should be reported together when both are available

## Cross-Skill References

| Finding | Hand Off To |
|---------|-------------|
| E-E-A-T gaps in persona scoring | `/seo content` for deep E-E-A-T audit |
| Missing schema types | `/seo schema` for generation |
| Local intent detected in SERP | `/seo local` for GBP analysis |
| Content depth gaps | `/seo page` for deep page analysis |
| Technical issues found during fetch | `/seo technical` for full audit |
| Image/media gaps | `/seo images` for optimization |

## Output Format

### Full SXO Analysis

```
## SXO Analysis: [URL]
### Target Keyword: [keyword]

### 1. SERP Landscape
- Dominant page type: [type] ([confidence]% consensus)
- SERP features: [list]
- Content depth norm: [word count range]
- Schema expectation: [types]

### 2. Page-Type Alignment
- Your page type: [type]
- SERP expects: [type]
- Verdict: [ALIGNED | MISMATCH (severity)]
- Impact: [explanation]

### 3. User Stories (derived from SERP signals)
[3-5 user stories with source signals]

### 4. Gap Analysis (SXO Score: XX/100)
[7-dimension breakdown table]

### 5. Persona Scores
[4-7 persona cards with 4-dimension scores]

### 6. Priority Actions
[Ranked list: fix mismatch first, then weakest persona gaps]

### 7. Limitations
[What could not be assessed, data source notes]
```

## Error Handling

| Error | Action |
|-------|--------|
| URL fetch fails | Report error, suggest checking URL accessibility |
| No keyword provided or detected | Ask user to provide target keyword |
| WebSearch returns <5 results | Proceed with available data, note limited sample |
| SERP has no organic results (all ads) | Note highly commercial SERP, analyze ad copy only |
| Target page is JavaScript-rendered | Note limitation, use available HTML content |
| DataForSEO cost exceeds threshold | Fall back to WebSearch, notify user |

## Quality Checklist

Before delivering results, verify:
- [ ] Target URL was fetched via `scripts/render_page.py --mode auto` (not raw curl/fetch)
- [ ] Page type classification uses taxonomy from references
- [ ] At least 5 SERP results were analyzed
- [ ] User stories cite specific SERP signals as evidence
- [ ] Persona scores include concrete improvement suggestions
- [ ] SXO score is clearly labeled as separate from SEO Health Score
- [ ] Limitations section is present and honest
- [ ] Cross-skill recommendations are included where relevant

---

## Supporting file: references/page-type-taxonomy.md

# Page Type Taxonomy for SERP Classification

Classify every page -- both the target URL and each SERP result -- into exactly one
of these 8 types. When signals overlap, choose the type with the strongest primary
signal match.

---

## 1. Landing Page

**Primary signals:** hero section with single value proposition, prominent CTA
(sign up / get started / book demo), pricing section or pricing link, testimonials
or social proof badges, minimal navigation (reduced header links).

**SERP indicators (top 10):** branded queries, high ad density at top, sitelinks
pointing to /pricing or /features, title tags with "| Product Name".

**Content structure:** Hero > Social proof > Features (3-5) > How it works > Pricing > CTA repeat > FAQ.

**Required elements:** Primary CTA above fold, trust badges, at least one testimonial,
WebSite or SoftwareApplication schema.

**Common mismatches:**
- Blog Post targeting landing-page keywords (severity: CRITICAL)
- Service Page missing CTA focus (severity: HIGH)

---

## 2. Blog Post

**Primary signals:** author byline, publish date, article body > 800 words,
comment section or social share buttons, breadcrumb with /blog/ segment,
related posts section.

**SERP indicators (top 10):** featured snippets (paragraph or list), PAA boxes
with 4+ questions, diverse domains in results, dates visible in snippets,
low ad density.

**Content structure:** Title > Author + Date > Introduction > H2 sections > Images/Examples > Conclusion > Author bio.

**Required elements:** Article or BlogPosting schema, author entity, datePublished,
dateModified, at least 1 image with descriptive alt text.

**Common mismatches:**
- Product Page targeting informational keyword (severity: HIGH)
- Landing Page targeting how-to keyword (severity: CRITICAL)

---

## 3. Product Page

**Primary signals:** price displayed, add-to-cart or buy button, product images
(multiple angles), specifications/features list, customer reviews with star ratings,
SKU or product identifiers.

**SERP indicators (top 10):** shopping results / product carousel, rich snippets
with price + availability + ratings, merchant names in titles, "buy" or "shop"
in title tags.

**Content structure:** Product title > Images > Price + CTA > Description > Specs > Reviews > Related products.

**Required elements:** Product schema (name, price, availability, review),
high-quality images, clear pricing, purchase CTA.

**Common mismatches:**
- Blog Post targeting product keyword (severity: CRITICAL)
- Comparison Page when user wants to buy (severity: MEDIUM)

---

## 4. Hybrid (Service + Content)

**Primary signals:** educational content sections mixed with CTAs, feature
explanations with "learn more" and "get started" side by side, common in SaaS,
both /blog/ and /product/ internal links in navigation.

**SERP indicators (top 10):** mix of branded and informational results,
some results with FAQ schema + others with SoftwareApplication schema,
moderate ad density.

**Content structure:** Problem statement > Solution overview > How it works > Feature deep-dives > Social proof > CTA > FAQ.

**Required elements:** FAQPage or HowTo schema combined with product schema,
both educational and commercial CTAs, clear value proposition.

**Common mismatches:**
- Pure Blog Post missing product integration (severity: HIGH)
- Pure Landing Page missing educational depth (severity: MEDIUM)

---

## 5. Service Page

**Primary signals:** service descriptions with methodology/process, case studies
or portfolio, "our process" or "how we work" sections, team credentials,
contact form or consultation CTA, industry-specific terminology.

**SERP indicators (top 10):** local pack presence, "near me" related searches,
results from agency/firm domains, title tags with "[Service] | [Company]",
moderate PAA questions about process/cost.

**Content structure:** Service overview > Benefits > Process/Methodology > Case studies > Team > Pricing/Packages > Contact CTA.

**Required elements:** Service or ProfessionalService schema, clear process
description, at least one case study or testimonial, contact mechanism.

**Common mismatches:**
- Blog Post targeting service keyword (severity: HIGH)
- Product Page for custom/consultative services (severity: MEDIUM)

---

## 6. Comparison Page

**Primary signals:** "vs" or "versus" in title/URL, feature comparison matrix
or table, pros/cons lists, side-by-side layout, "best [X] for [use case]"
framing, multiple products reviewed.

**SERP indicators (top 10):** "vs" queries in related searches, multiple PAA
about alternatives, results from review sites (G2, Capterra, TrustRadius),
listicle-style titles ("10 Best..."), affiliate disclosures.

**Content structure:** Introduction > Comparison criteria > Feature matrix > Individual reviews > Verdict/Recommendation > FAQ.

**Required elements:** Comparison table with clear criteria, pros/cons for each
option, clear recommendation or "best for" segmentation, ItemList or Table schema.

**Common mismatches:**
- Single Product Page when user wants comparison (severity: HIGH)
- Blog Post without structured comparison (severity: HIGH)

---

## 7. Local Page

**Primary signals:** physical address displayed, Google Maps embed, NAP
(Name, Address, Phone) in consistent format, service area description,
directions or "visit us" section, location-specific content.

**SERP indicators (top 10):** local pack (map + 3 listings), "near me" in
related searches, Google Business Profile cards, location in title tags,
results from local directories (Yelp, BBB).

**Content structure:** Business name + location > Services at this location > Map + directions > Hours > Reviews > Local content > Contact.

**Required elements:** LocalBusiness schema (correct subtype), full NAP,
geo coordinates, openingHoursSpecification, embedded map.

**Common mismatches:**
- Generic Service Page missing local signals (severity: HIGH)
- Blog Post targeting "[service] in [city]" (severity: CRITICAL)

---

## 8. Tool / Interactive

**Primary signals:** input fields, calculator or generator interface, interactive
elements (sliders, dropdowns, toggles), results output area, utility-first
design with minimal marketing copy, "free [tool name]" in title.

**SERP indicators (top 10):** tool/calculator results in SERP, "calculator"
or "generator" or "checker" in related searches, results from tool-first sites,
minimal PAA (users want to DO, not READ).

**Content structure:** Tool interface (above fold) > Brief instructions > Tool output > Supporting content below > FAQ > Related tools.

**Required elements:** WebApplication or SoftwareApplication schema, functional
tool above fold, clear input/output flow, no login wall for basic functionality.

**Common mismatches:**
- Blog Post about topic where users want a tool (severity: CRITICAL)
- Landing Page without interactive element (severity: HIGH)

---

## Classification Priority

When a page shows signals for multiple types, use this priority:

1. If interactive tool is present and functional: **Tool**
2. If physical address + map: **Local** (unless tool is primary)
3. If comparison table + "vs" framing: **Comparison**
4. If price + buy button: **Product**
5. If CTA-heavy + minimal navigation: **Landing Page**
6. If service process + case studies: **Service Page**
7. If educational + CTA mix: **Hybrid**
8. Default: **Blog Post**

---

## Supporting file: references/persona-scoring.md

# Persona-Based Scoring Methodology

Score the target page from the perspective of each derived persona. This reveals
which audience segments the page serves well and which it fails.

---

## Persona Derivation

Derive 4-7 personas from SERP intent signals. Do not invent personas without
evidence -- every persona must trace back to a signal cluster.

### Sources for Persona Derivation

| Source | What It Reveals | Example Persona |
|--------|----------------|-----------------|
| PAA question cluster | Knowledge gaps by audience | Beginner, Technical Evaluator |
| Ad copy segments | Commercial audience targets | Budget Buyer, Enterprise Buyer |
| Related search themes | Journey stage groups | Researcher, Comparison Shopper |
| SERP result types | Content consumption preferences | Visual Learner, Data-Driven Analyst |
| Featured snippet format | Expected answer style | Quick-Answer Seeker |

### Persona Card Format

For each persona, document:

```
**[Persona Name]** -- [one-line description]
- Role: [job title or situation]
- Goal: [what they want to accomplish]
- Emotional state: [from user-story-framework.md]
- Journey stage: Awareness | Consideration | Decision
- Key questions: [2-3 questions this persona needs answered]
- SERP evidence: [specific signals that generated this persona]
```

---

## 4-Dimension Scoring Rubric

Score each persona on 4 dimensions. Maximum 25 points each, 100 total per persona.

### Dimension 1: Relevance (0-25)

Does the page address this persona's specific need?

| Score | Criteria |
|-------|----------|
| 21-25 | Page directly addresses the persona's primary goal with specific content |
| 16-20 | Page covers the topic but lacks persona-specific depth or framing |
| 11-15 | Page is tangentially relevant -- persona must extrapolate to find value |
| 6-10 | Page mentions the topic but serves a different audience |
| 0-5 | Page is irrelevant to this persona's need |

**Scoring signals:** keyword alignment with persona goal, presence of persona-relevant
sections (e.g., "for small businesses" section for SMB persona), depth of coverage
for persona-specific use cases.

### Dimension 2: Clarity (0-25)

Can this persona find their answer within 10 seconds?

| Score | Criteria |
|-------|----------|
| 21-25 | Answer is visible above fold or within first scroll for this persona |
| 16-20 | Answer is on the page but requires scrolling or navigation |
| 11-15 | Answer exists but is buried in dense text or unclear structure |
| 6-10 | Persona must piece together the answer from multiple sections |
| 0-5 | Answer is not clearly present -- persona would bounce |

**Scoring signals:** heading clarity for persona's question, scan-ability (bullets,
tables, bold key terms), table of contents or jump links, information hierarchy
matching persona priority.

### Dimension 3: Trust (0-25)

Does the page provide adequate trust signals for this persona?

| Score | Criteria |
|-------|----------|
| 21-25 | Multiple trust signals directly relevant to this persona's concerns |
| 16-20 | General trust signals present but not persona-specific |
| 11-15 | Some trust signals but gaps in what this persona needs |
| 6-10 | Minimal trust signals -- persona would feel uncertain |
| 0-5 | No trust signals or signals that actively undermine trust for this persona |

**Scoring signals:** testimonials from similar users/companies, relevant credentials
or certifications, security badges (for risk-averse personas), case studies matching
persona's industry or size, author expertise signals.

### Dimension 4: Action (0-25)

Is there a clear next step for this persona?

| Score | Criteria |
|-------|----------|
| 21-25 | Clear, persona-appropriate CTA with low friction |
| 16-20 | CTA exists but is generic (not tailored to persona's stage) |
| 11-15 | Next step is available but not prominent or requires searching |
| 6-10 | Only one CTA that doesn't match persona's journey stage |
| 0-5 | No clear next step -- persona reaches a dead end |

**Scoring signals:** CTA relevance to journey stage (awareness = "learn more",
decision = "buy now"), friction level (free trial vs sales call), CTA placement
relative to persona-relevant content, alternative paths for different readiness levels.

---

## Score Interpretation

| Range | Rating | Implication |
|-------|--------|-------------|
| 80-100 | Excellent | Page serves this persona well -- minor optimizations only |
| 60-79 | Good | Page is relevant but has notable gaps for this persona |
| 40-59 | Needs Work | Page partially serves this persona -- significant improvements needed |
| 0-39 | Critical Mismatch | Page fails this persona -- major restructuring or new page needed |

---

## Aggregation and Prioritization

### Weighted Average

Not all personas are equally important. Weight by estimated search volume share:

- If SERP shows 70% informational intent, weight informational personas higher
- If ads dominate, weight commercial personas higher
- If local pack present, weight local personas higher

### Priority Ranking

Sort improvement recommendations by:

1. **Weakest persona with highest search volume weight** = biggest opportunity
2. **Lowest-scoring dimension across all personas** = systemic issue
3. **Critical mismatch personas** = fundamental page-type problem

### Output Format

```
## Persona Scores for [URL]

| Persona | Relevance | Clarity | Trust | Action | Total | Rating |
|---------|-----------|---------|-------|--------|-------|--------|
| [Name] | XX/25 | XX/25 | XX/25 | XX/25 | XX/100 | [Rating] |
| ... | ... | ... | ... | ... | ... | ... |

### Weakest Persona: [Name] (XX/100)
**Top issue:** [specific problem]
**Recommended fix:** [concrete action with page-level detail]

### Systemic Issues
- [dimension]: [pattern across all personas]

### Priority Actions
1. [Action targeting weakest persona]
2. [Action targeting systemic issue]
3. [Action targeting next weakest persona]
```

---

## Validation Rules

- [ ] Every persona traces to specific SERP signals (no invented personas)
- [ ] Scores include specific evidence from the page (not just numbers)
- [ ] Recommendations are concrete (section names, CTA text, placement)
- [ ] At least 4 personas scored, no more than 7
- [ ] Weakest persona is addressed first in recommendations
- [ ] Score interpretation uses the standard ranges above

---

## Supporting file: references/user-story-framework.md

# User Story Framework: SERP Signals to User Intent

Derive user stories from observable SERP signals. Every story must cite the
specific signal that generated it -- no guessing.

---

## Signal Sources

### 1. People Also Ask (PAA)

PAA questions reveal **knowledge gaps and concerns** the searcher has.

- Cluster PAA by theme: definitional ("what is"), procedural ("how to"),
  evaluative ("is X worth it"), comparative ("X vs Y"), risk ("is X safe")
- Each cluster maps to a distinct persona or journey stage
- Definitional PAA = awareness stage, evaluative PAA = consideration,
  comparative PAA = decision stage

### 2. Ad Copy

Ads reveal **commercial triggers and objection handling** that convert.

- Extract recurring themes across all visible ads (top + bottom)
- Common patterns: free trial emphasis (barrier: commitment), trusted-by counts
  (barrier: trust), price anchoring (barrier: cost), speed claims (barrier: time)
- If no ads appear, the keyword is likely informational -- commercial intent is low

### 3. Related Searches

Related searches reveal the **search journey** -- what comes before and after.

- Searches with added qualifiers (+ "for beginners", + "pricing") = narrowing
- Searches with removed qualifiers = broadening / pivoting
- "[keyword] alternatives" = dissatisfaction signal
- "[keyword] vs [competitor]" = active comparison stage
- "[keyword] reviews" = trust-seeking before purchase

### 4. Featured Snippets

The snippet format reveals the **expected answer structure**.

- Paragraph snippet = user wants a concise definition or explanation
- List snippet = user wants steps or ranked items
- Table snippet = user wants structured comparison data
- Video snippet = user wants visual demonstration
- No snippet = Google uncertain about best format (opportunity)

### 5. AI Overview

AI Overview reveals what Google considers the **authoritative synthesis**.

- Sources cited = authority signals Google trusts for this topic
- Answer structure = the format Google believes best serves the query
- If target page is not cited = content does not match Google's synthesis model

---

## User Story Format

```
As a [persona],
I want to [goal],
because [emotional driver],
but I'm blocked by [barrier].
```

### Persona Derivation

Derive from signal clusters, not assumptions:
- PAA cluster about cost/pricing = **Budget-Conscious Buyer**
- PAA cluster about setup/implementation = **Technical Evaluator**
- Ads emphasizing trust/security = **Risk-Averse Decision Maker**
- Related searches with "for small business" = **SMB Owner**
- Related searches with "enterprise" = **Enterprise Buyer**

### Emotional States

Map SERP signals to emotional states:

| Signal Pattern | Emotional State |
|---------------|----------------|
| "Is X safe / legitimate / scam" in PAA | Skeptical |
| Many comparison queries in related | Overwhelmed by choices |
| "How to [basic task]" dominating PAA | Confused / frustrated |
| High ad density + shopping results | Ready to buy |
| "Best [X] for [use case]" results | Evaluating carefully |
| "[X] not working / problems" in PAA | Frustrated with current solution |

### Barrier Types

| Barrier | SERP Signal | Page Must Address |
|---------|------------|-------------------|
| Information gap | PAA questions unanswered by snippet | Clear, complete answer in first scroll |
| Trust gap | Ads emphasize trust badges / reviews | Social proof, credentials, guarantees |
| Comparison fatigue | Many "vs" and "best" related searches | Clear differentiation or recommendation |
| Price sensitivity | PAA about cost, free alternatives | Transparent pricing, value justification |
| Technical confusion | "How to" PAA, setup-related queries | Step-by-step guide, demo, or tool |
| Time pressure | Ads with "instant" / "today" / "fast" | Quick-win content, speed of resolution |

---

## Example Derivation

**Keyword**: "project management software"

**Observed signals:**
- PAA: "Is Monday.com better than Asana?", "What is the cheapest project management tool?", "Do I need project management software for a small team?"
- Ads: "Free forever plan", "Trusted by 150,000 teams", "Set up in 5 minutes"
- Related: "project management software for small business", "free project management tools", "Asana vs Monday vs ClickUp"
- Featured snippet: list of tools with brief descriptions

**Derived user stories:**

1. As a **small business owner**, I want to find affordable PM software, because
   I need to organize my growing team, but I'm blocked by **price sensitivity**
   and fear of paying for features I won't use.
   *(Source: PAA "cheapest", related "small business", ads "free forever")*

2. As a **team lead evaluating tools**, I want to compare the top 3 options side
   by side, because my boss asked for a recommendation, but I'm blocked by
   **comparison fatigue** from too many similar-looking options.
   *(Source: related "Asana vs Monday vs ClickUp", PAA "is Monday better than Asana")*

3. As a **non-technical manager**, I want software that works immediately without
   training, because I can't afford downtime during migration, but I'm blocked by
   **technical confusion** about setup complexity.
   *(Source: ads "set up in 5 minutes", PAA "do I need PM software for small team")*

---

## Story Quality Checklist

- [ ] Every story cites at least one specific SERP signal
- [ ] Persona name reflects the signal source, not assumptions
- [ ] Emotional driver is grounded in observable SERP tone
- [ ] Barrier is specific enough to suggest a page-level fix
- [ ] 3-5 stories cover the primary intent angles (no duplicates)
- [ ] Stories span at least 2 journey stages (awareness, consideration, decision)

---

## Supporting file: references/wireframe-templates.md

# Wireframe Templates: IST/SOLL Patterns

Generate before (IST) and after (SOLL) wireframes showing what the page currently
looks like vs what it should look like based on SERP expectations.

## Core Principles

1. **Ultra-concrete placeholders**: Not "add CTA" but "add pricing CTA with annual
   savings badge below hero, linking to /pricing#enterprise"
2. **Mobile-first**: Assume 375px viewport first; above-the-fold (~600px) must
   contain the most critical element for the page type
3. **Semantic HTML**: Output as section outline with HTML5 elements

## IST Generation

Parse the current page and map to this structure:

```
IST: [URL]
├── ABOVE FOLD
│   ├── [element]: "[actual content]"
│   └── [element]: "[actual content]"
├── MAIN CONTENT
│   ├── [section]: "[summary]" (~XXX words)
│   └── [section]: "[summary]" (~XXX words)
├── SUPPORTING
│   └── [element]: "[description]"
└── FOOTER — [elements present]

Missing from SERP expectations:
- [element]: [why it matters]
```

## SOLL Templates by Page Type

### 1. Landing Page

```
<header> Nav: logo + 3-4 links max + primary CTA button </header>
<section class="hero">
  H1: [value proposition matching target keyword]
  Subhead: [supporting benefit] | CTA: [primary action]
  Trust line: "Trusted by [X] companies including [logos]"
</section>
<section class="social-proof"> 3-5 logo badges + key metric </section>
<section class="features"> 3 blocks: icon + H3 + 2-line desc (address PAA) </section>
<section class="how-it-works"> 3-step process with numbered icons </section>
<section class="testimonial"> Quote + photo + name + title + company </section>
<section class="pricing"> 2-3 tiers, recommended highlighted, annual toggle </section>
<section class="faq"> 5-7 PAA questions, FAQPage schema </section>
<section class="final-cta"> Repeat hero CTA with urgency </section>
```

### 2. Blog Post

```
<article>
  <header> H1 | Author + photo + credentials | Date + Updated | Reading time </header>
  <nav class="toc"> Jump links to H2 sections </nav>
  <section class="intro"> Hook + thesis + TL;DR box (above fold) </section>
  <section> H2: [cluster 1] — address PAA #1 </section>
  <section> H2: [cluster 2] — address PAA #2 </section>
  <section> H2: [cluster 3] — comparison table if SERP warrants </section>
  <section> H2: [cluster 4] — image/diagram </section>
  <section class="expert-quote"> Blockquote from SME (E-E-A-T) </section>
  <section> H2: FAQ — remaining PAA questions </section>
  <footer> Author bio | Related posts (3) | CTA: newsletter </footer>
</article>
```

### 3. Product Page

```
<section class="product-hero">
  H1: [product + benefit keyword] | Gallery: 4-6 images
  Price + savings indicator | CTA: "Add to Cart" (above fold)
  Trust: stars + review count + shipping
</section>
<section class="key-features"> 4-6 bullets: feature + benefit </section>
<section class="specifications"> Table: specs, dimensions, compatibility </section>
<section class="reviews"> aggregateRating + 5 reviews, filterable </section>
<section class="comparison"> "Why choose this" table (if SERP shows intent) </section>
<section class="faq"> Product PAA questions </section>
<section class="related"> 4 complementary products </section>
```

### 4. Comparison Page

```
<header>
  H1: "[A] vs [B]: [year] Comparison"
  Quick verdict: "Best for [use case]: [winner]"
</header>
<section class="matrix"> Feature table: check/cross/partial icons </section>
<section class="reviews">
  H2: [A] — pros, cons, best for, pricing
  H2: [B] — pros, cons, best for, pricing
</section>
<section class="verdict"> Persona recs: "Choose A if...", "Choose B if..." </section>
<section class="faq"> Comparison PAA questions </section>
```

### 5. Service Page

```
<section class="hero"> H1: [service + location] | CTA: "Free Consultation" </section>
<section class="problem"> Empathy-driven problem statement </section>
<section class="process"> 3-5 numbered steps </section>
<section class="results"> 2-3 case studies with before/after metrics </section>
<section class="credentials"> Certs, experience, team </section>
<section class="pricing"> Packages or "starting at" </section>
<section class="faq"> PAA questions </section>
<section class="cta"> Repeat CTA + contact form </section>
```

### 6. Local Page

```
<section class="hero">
  H1: [service] in [city] — [business name]
  CTA: "Call Now" + "Get Directions" | NAP displayed
</section>
<section class="map"> Google Map embed + landmark directions </section>
<section class="services"> Location-specific services (unique content) </section>
<section class="reviews"> Review widget with reviewer locations </section>
<section class="hours"> openingHoursSpecification + "open now" </section>
<section class="about"> Team, history, community (location-specific) </section>
```

### 7. Tool / Interactive

```
<section class="tool" id="tool">
  H1: Free [Tool Name] — [purpose]
  Input: [fields/dropdowns/upload] (ABOVE FOLD)
  CTA: "Calculate" / "Generate" / "Check" | Output zone
</section>
<section class="instructions"> How to Use — 3 steps max </section>
<section class="explanation"> Educational depth for SEO </section>
<section class="faq"> Tool-specific PAA </section>
<section class="related-tools"> 3-4 related tools </section>
```

### 8. Hybrid (Education + Product)

```
<section class="hero">
  H1: [education + product keyword] | Dual CTA: "Learn More" + "Try Free"
</section>
<section class="education"> Address awareness-stage PAA </section>
<section class="solution"> Bridge: how [Product] solves this </section>
<section class="features"> 3-4 benefit-framed features </section>
<section class="proof"> Case study or testimonial </section>
<section class="cta"> Match journey stage from SERP analysis </section>
<section class="faq"> Mix of educational + product PAA </section>
```

## Placeholder Rules

When filling SOLL placeholders, always be specific:

| Bad (vague) | Good (concrete) |
|-------------|-----------------|
| "Add a CTA" | "Add 'Start Free Trial' button below hero, green #2d6a4f, links to /signup" |
| "Include social proof" | "Add 3 logos (G2, Capterra, TrustRadius) + '4.8/5 from 2,300 reviews'" |
| "Add FAQ section" | "Add 5 FAQs from PAA: 'Is X safe?', 'How much does X cost?', ..." |
| "Improve trust" | "Add SSL badge + 'SOC 2 certified' banner + customer count" |
| "More content" | "Add 400-word section under H2 'How [Feature] Works' with diagram" |