blog-analyze

# Blog Analyzer: Quality Audit & Scoring

Scores blog posts on a 0-100 scale across 5 categories and provides prioritized
improvement recommendations. Includes AI content detection analysis. Works with
local files or published URLs.

Reference documents (paths from repo root):
- `skills/blog/references/quality-scoring.md`: full scoring checklist
- `skills/blog/references/eeat-signals.md`: E-E-A-T evaluation criteria
- `skills/blog/references/ai-slop-detection.md`: two-tier reflex methodology (v1.8.0)
- `skills/blog/references/editorial-heuristics.md`: ordinal 0-4 rubric, P0-P3 severity (v1.8.0, used with `--rubric`)
- `skills/blog/references/cognitive-load.md`: per-section concept density (v1.8.0, used with `--cognitive-load`)

## Input Handling

- **Local file**: Read the file directly
- **URL**: Fetch with WebFetch, extract content
- **Directory**: Scan for blog files, audit all (batch mode)
- **Flags**: `--format json|table`, `--batch`, `--sort score`, `--rubric`, `--cognitive-load`

### Optional Modes (v1.8.0)

- `--rubric`: in addition to the 100-point score, emit the ordinal 0-4 editorial-heuristics rubric with P0-P3 severity tags. See `skills/blog/references/editorial-heuristics.md`. The 100-point JSON schema is preserved; the rubric is added as a sibling `rubric` field.
- `--cognitive-load`: run `scripts/cognitive_load.py` against the post and embed the per-section load heatmap as a sibling `cognitive_load` field. See `skills/blog/references/cognitive-load.md`.

Both modes are additive. The default behavior (no flags) is unchanged.

## Scoring Process

### Step 1: Content Extraction

Read the blog post and extract:
- Frontmatter (title, description, date, lastUpdated, author, tags)
- Heading structure (H1, H2, H3 with hierarchy)
- Paragraph count and word counts per paragraph
- Statistics (any number claims with or without sources)
- Images (count, alt text presence, format)
- Charts/SVGs (count, type diversity)
- Links (internal, external, broken)
- FAQ section presence
- Schema markup (types present)
- Meta tags (title, description, OG tags, twitter cards)
- Sentence lengths for burstiness analysis
- Vocabulary tokens for diversity scoring

### Step 2: Score Each Category

Load `references/quality-scoring.md` for the full checklist. Score each:

#### Content Quality (30 points)
| Check | Points | Pass Criteria |
|-------|--------|---------------|
| Depth/comprehensiveness | 7 | Covers topic thoroughly, no major gaps |
| Readability (Flesch 60-70) | 7 | Flesch 60-70 ideal, 55-75 acceptable; Grade 7-8; Gunning Fog 7-8 |
| Originality/unique value markers | 5 | Original data, case studies, first-hand experience |
| Sentence & paragraph structure | 4 | Avg sentence 15-20 words, ≤25% over 20; paragraphs 40-80 words; H2 every 200-300 words |
| Engagement elements | 4 | Summary box, callouts, varied content blocks. Accepts: "TL;DR", "Key Takeaways", "The Bottom Line", "What You'll Learn", "At a Glance", "In Brief" |
| Grammar/anti-pattern | 3 | Passive voice ≤10%, AI trigger words ≤5/1K, transition words 20-30%, clean prose |

**Readability Bands** (apply per persona, or use default):

| Audience | Flesch Grade | Flesch Ease | Scoring Impact |
|----------|-------------|-------------|----------------|
| Consumer | 6-8 | 60-80 | Full points if in range |
| Professional | 8-10 | 50-60 | Full points if in range |
| Technical | 10-12 | 30-50 | Full points if in range |
| Default (no persona) | 7-8 | 60-70 | Current scoring unchanged |

Content clarity is the #2 factor for AI citation probability (+32.83%
score differential). Average US adult reads at 7th-8th grade level.

#### SEO Optimization (25 points)
| Check | Points | Pass Criteria |
|-------|--------|---------------|
| Heading hierarchy with keywords | 5 | H1 -> H2 -> H3, no skips, keyword in 2-3 headings |
| Title tag (40-60 chars, keyword, power word) | 4 | Front-loaded keyword, positive sentiment |
| Keyword placement/density | 4 | Natural integration, no stuffing, in first 100 words |
| Internal linking (3-10 contextual) | 4 | Descriptive anchor text, bidirectional |
| URL structure | 3 | Short, keyword-rich, no stop words, lowercase |
| Meta description (150-160 chars, stat) | 3 | Fact-dense, includes one statistic |
| External linking (tier 1-3) | 2 | 3-8 outbound links to authoritative sources |

#### E-E-A-T Signals (15 points)
| Check | Points | Pass Criteria |
|-------|--------|---------------|
| Author attribution (named, with bio) | 4 | Real name, credentials, not sales pitch |
| Source citations (tier 1-3, inline) | 4 | 8+ unique stats, zero fabricated |
| Trust indicators | 4 | Contact page, about page, editorial policy |
| Experience signals | 3 | "When we tested...", original photos/data |

When scoring source citations under E-E-A-T, evaluate whether each public statistic carries the FLOW evidence triple: year anchor in prose, inline citation with publisher and title, URL with retrieval date in the source block. Posts that cite tier 1-3 sources but lack retrieval dates score lower on this subcategory than posts that include the full triple. See `skills/blog/references/flow-alignment.md` for the standard.

#### Technical Elements (15 points)
| Check | Points | Pass Criteria |
|-------|--------|---------------|
| Schema markup (3+ types = bonus) | 4 | BlogPosting + FAQ + Person minimum |
| Image optimization | 3 | AVIF/WebP, descriptive alt text, lazy except LCP |
| Structured data elements | 2 | Tables, lists, comparison blocks |
| Page speed signals | 2 | LCP < 2.5s, no render-blocking JS |
| Mobile-friendliness | 2 | Responsive, tap targets 48px+ |
| OG/social meta tags | 2 | og:title, og:description, og:image, twitter:card |

#### AI Citation Readiness (15 points)
| Check | Points | Pass Criteria |
|-------|--------|---------------|
| Passage-level citability (120-180 words) | 4 | Self-contained sections with stat + source |
| Q&A formatted sections | 3 | 60-70% of H2s as questions, FAQ present |
| Entity clarity