content-decay-detector

# Content Decay Detector

Monitor existing content for ranking drops and generate a prioritized refresh queue. Refreshing decaying content is the highest-ROI SEO activity — it's faster and cheaper than creating new content, and recovering a lost position is easier than earning a new one.

## Stage

S3: Blog & SEO — Blog maintenance and optimization. This skill keeps your existing content competitive and prevents rankings from silently eroding.

## When to Use

- User has existing blog content and wants to check for decay
- User notices traffic declining on specific pages
- User asks "what content needs updating?"
- User says "content decay", "ranking drops", "stale content", "refresh", "content audit"
- Monthly maintenance check — should run every 30 days on active blogs
- After `seo-audit` reveals declining pages

## Input Schema

```yaml
site_url: string              # REQUIRED — the site to audit
                              # e.g., "myblog.com", "example.com/blog"

content_list: object[]        # OPTIONAL — specific pages to check
  - url: string               # Page URL
    title: string             # Page title
    publish_date: string      # Original publish date
    last_updated: string      # Last update date
    target_keyword: string    # Primary keyword

check_competitors: boolean    # OPTIONAL — whether to check if competitors published fresher content
                              # Default: true

timeframe: string             # OPTIONAL — "30d" | "90d" | "6m" | "1y"
                              # Default: "90d"
```

**Chaining from S6 seo-audit**: Use `declining_pages` as the `content_list`.

## Workflow

### Step 1: Gather Content Data

If `content_list` not provided:
1. `web_search`: `site:[site_url]` — discover indexed pages
2. Identify the top 15-20 most important pages (by topic relevance)
3. For each page, note: title, URL, apparent publish/update date

### Step 2: Check for Decay Signals

Read `shared/references/seo-strategy.md` for decay signals and refresh methodology.

For each page:
1. `web_search` for the page's target keyword — check current ranking position
2. Look for decay signals:
   - **Outdated information**: Product features, pricing, dates mentioned
   - **Competitor freshness**: Newer, better content published by competitors
   - **Missing elements**: No images, no data, thin content compared to current SERP
   - **Broken patterns**: "2023" in a title when it's 2025+, discontinued products mentioned

### Step 3: Score Decay Priority

For each decaying page, assign priority:

| Factor | Score | Criteria |
|---|---|---|
| Revenue impact | 1-5 | Contains affiliate links + had traffic = high revenue impact |
| Decay severity | 1-5 | Major outdated info = 5, minor = 1 |
| Fix effort | 1-5 (inverted) | Easy fix = 5, full rewrite = 1 |
| Competitor threat | 1-5 | Competitor published better version = 5 |

**Priority = Revenue × Decay × Fix_Ease × Competitor_Threat** (normalized)

### Step 4: Generate Refresh Instructions

For each page in priority order, specify:
1. **What's decayed** — specific outdated elements
2. **What to update** — concrete changes to make
3. **What to add** — new sections, data, or elements competitors have
4. **Internal linking** — new pages to link to/from since original publish
5. **Estimated effort** — time to refresh

### Step 5: Self-Validation

- [ ] Decay signals are evidence-based (not guesses)
- [ ] Priority ordering makes business sense (revenue-impacting first)
- [ ] Refresh instructions are specific and actionable
- [ ] Effort estimates are realistic
- [ ] Not recommending refreshes for content that's performing fine

## Output Schema

```yaml
output_schema_version: "1.0.0"
content_decay:
  site: string
  pages_analyzed: number
  pages_decaying: number
  total_refresh_effort: string  # Estimated total hours

  decaying_pages:
    - url: string
      title: string
      priority: string          # "P0-critical" | "P1-high" | "P2-medium" | "P3-low"
      decay_signals: string[]
      refresh_actions: string[]
      estimated_effort: string
      revenue_impact: string    # "high" | "medium" | "low"

  healthy_pages: string[]       # Pages that don't need refresh

chain_metadata:
  skill_slug: "content-decay-detector"
  stage: "blog"
  timestamp: string
  suggested_next:
    - "affiliate-blog-builder"
    - "seo-audit"
    - "internal-linking-optimizer"
    - "keyword-cluster-architect"
```

## Output Format

```
## Content Decay Report: [Site]

### Summary
- **Pages analyzed:** XX
- **Pages decaying:** XX
- **Total refresh effort:** XX hours
- **Estimated traffic recovery:** XX%

### Priority Refresh Queue

#### P0 — Critical (do this week)

**[Page Title]** — [URL]
- Decay: [what's wrong]
- Action: [what to do]
- Effort: [time estimate]
- Impact: [expected result]

#### P1 — High (do this month)
[same structure]

#### P2 — Medium (schedule)
[same structure]

### Healthy Pages (no action needed)
- [Page] — still ranking, content fresh
- [Page] — recently updated

### Monthly Maintenance Schedule
- Week 1: Refresh P0 pages
- Week 2: Refresh P1 pages
- Week 3: Create new content for gaps found
- Week 4: Internal linking review
```

## Error Handling

- **No site URL**: "I need your blog URL to check for content decay. What's the site?"
- **Site has no indexed pages**: "I can't find indexed pages for this URL. Check that the site is public and indexed by search engines."
- **All content is fresh**: "Great news — no significant decay detected. Run this check again in 30 days."
- **Can't determine ranking positions**: Use available signals (content age, competitor freshness, outdated info) for prioritization.

## Examples

**Example 1:** "Check my blog for content decay"
→ Discover indexed pages, check each for decay signals, generate prioritized refresh queue with specific actions per page.

**Example 2:** "Which of my articles need updating?"
→ Analyze content list, identify outdated pricing, stale comparisons, missing new p