Seo Cluster

# Execution Workflow

## Overview

The execution phase transforms a `cluster-plan.json` into actual content. It handles
priority ordering, context injection for the blog writer, backward link updates,
resume capability, and post-execution quality scoring.

## Priority Algorithm

Content is created in this strict order:

1. **Pillar page first** -- The hub must exist before any spokes can link to it
2. **Spokes by search volume (descending)** -- Highest-volume spokes first for
   maximum early impact
3. **Within same volume, by cluster index** -- Process Cluster 0 before Cluster 1
4. **Within same cluster, by post index** -- Process Post 0 before Post 1

Rationale: The pillar establishes the topical authority foundation. High-volume
spokes generate the most organic traffic, so they should be published earliest
for faster compounding returns.

## Cluster Context Injection

When invoking `blog-write` for each post, pass a structured context block:

```json
{
  "cluster_context": {
    "role": "pillar|spoke",
    "pillar_title": "The Complete Guide to ...",
    "pillar_url": "/guide/...",
    "cluster_name": "Cluster Name",
    "cluster_index": 0,
    "post_index": 0,
    "primary_keyword": "target keyword",
    "secondary_keywords": ["variant 1", "variant 2"],
    "template": "how-to",
    "word_count_target": 1500,
    "outgoing_links": [
      { "url": "/pillar-url", "anchor": "main topic guide", "type": "mandatory" },
      { "url": "/sibling-post", "anchor": "related subtopic", "type": "recommended" }
    ],
    "incoming_link_placeholder": "<!-- cluster-link:cluster-0-post-1 -->",
    "differentiation_note": "This post should focus on X, while sibling post covers Y"
  }
}
```

### Context Fields Explained

| Field | Purpose |
|-------|---------|
| `role` | Whether this is the pillar or a spoke (affects depth and breadth) |
| `pillar_title` / `pillar_url` | So spokes can link back to the pillar |
| `cluster_name` / `cluster_index` | For organizing and labeling |
| `post_index` | Position within the cluster |
| `primary_keyword` | The main target keyword for this post |
| `secondary_keywords` | Additional keywords to naturally incorporate |
| `template` | Content template to follow (how-to, listicle, comparison, etc.) |
| `word_count_target` | Target word count (not a hard limit, a guideline) |
| `outgoing_links` | Links this post MUST include, with suggested anchor text |
| `incoming_link_placeholder` | HTML comment marker for future backward link injection |
| `differentiation_note` | How this post differs from siblings targeting similar topics |

## Backward Link Injection

After each new post is written, update previously written posts to link to it:

### Process

1. Read the link matrix from `cluster-plan.json`
2. Identify all posts that should link TO the newly written post
3. For each of those posts (that is already written):
   a. Open the post file
   b. Search for the placeholder comment: `<!-- cluster-link:POST_ID -->`
   c. Replace the placeholder with an actual contextual link
   d. If no placeholder found, append a contextual link in the most relevant section
4. Log all backward links added

### Placeholder Format

```html
<!-- cluster-link:cluster-0-post-1 -->
```

This is inserted during content creation at a contextually appropriate location.
When the target post is later written, the placeholder is replaced with:

```html
For a deeper dive, see our guide on <a href="/target-url">anchor text</a>.
```

## Resume Capability

Execution can be interrupted and resumed. The resume algorithm:

### Detection

1. Read `cluster-plan.json` from the current directory
2. Scan the output directory for existing post files
3. Match found files against the plan using:
   - Filename patterns (slug derived from title or keyword)
   - Content inspection (check for `primary_keyword` in frontmatter or first H1)
4. Mark matched posts as `"status": "written"` in the plan

### Resume Logic

1. Load the plan with updated statuses
2. Fi