# How the /optimize Command Validates Meta Elements and Scores Publishing Readiness in SEOMachine

> Discover how the SEOMachine /optimize command validates meta elements and scores publishing readiness. Achieve a passing score with this essential guide.

- Repository: [Craig/seomachine](https://github.com/TheCraigHewitt/seomachine)
- Tags: how-to-guide
- Published: 2026-03-12

---

**The `/optimize` command validates meta elements by checking title and description length, keyword presence, and completeness, then scores publishing readiness using a weighted 0-100 scale where articles must achieve ≥80 points with zero critical issues to pass.**

The `/optimize` command in the [TheCraigHewitt/seomachine](https://github.com/TheCraigHewitt/seomachine) repository serves as the final SEO polish before content is pushed to WordPress. It orchestrates the **Content Analyzer** agent and the **SEOQualityRater** module to validate meta elements and score publishing readiness through a rigorous, rule-based evaluation system.

## Execution Flow of the /optimize Command

When you run `/optimize draft-article.md`, the system executes a six-step pipeline defined in [`.claude/commands/optimize.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/commands/optimize.md) and orchestrated by [`.claude/agents/content-analyzer.md`](https://github.com/TheCraigHewitt/seomachine/blob/main/.claude/agents/content-analyzer.md):

1. **Command Parsing**: The CLAUDE CLI parses the instruction and loads the target markdown file.
2. **Content Extraction**: The Content Analyzer extracts the meta title, meta description, primary keyword, and body content.
3. **SEO Quality Rating**: The analyzer invokes `rate_seo_quality()` from [`data_sources/modules/seo_quality_rater.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/seo_quality_rater.py).
4. **Meta Validation**: Inside `SEOQualityRater._score_meta_elements()`, the system validates title/description length and keyword presence.
5. **Score Aggregation**: Category scores are weighted and summed into an `overall_score` (0-100).
6. **Readiness Determination**: Publishing readiness is set to `True` only if `overall_score >= 80` and `critical_issues` is empty.

## Meta-Element Validation Logic

The `SEOQualityRater` class enforces strict SERP-friendly standards through the `_score_meta_elements()` method in [`data_sources/modules/seo_quality_rater.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/seo_quality_rater.py).

### Title and Description Requirements

The validator applies length-based penalties and critical flags:

- **Missing Elements**: Absent title or description triggers a **-40 point penalty** and adds a critical issue.
- **Title Length**: 
  - `< 50` characters → **-15 points** (warning)
  - `> 70` characters → **-10 points** (warning)
- **Description Length**:
  - `< 150` characters → **-15 points** (warning)
  - `> 170` characters → **-10 points** (warning)

### Keyword Presence Checks

The primary keyword must appear in both meta elements:

- **Missing in Title**: **-15 points** (warning)
- **Missing in Description**: **-10 points** (suggestion)

```python

# Simplified excerpt from _score_meta_elements

if not meta_title:
    score -= 40
    critical.append("Meta title is missing")
else:
    title_len = len(meta_title)
    if title_len < 50: 
        score -= 15
        warnings.append("Title too short")
    if primary_keyword and primary_keyword.lower() not in meta_title.lower():
        score -= 15
        warnings.append("Keyword missing from title")

```

## Calculating the Overall SEO Score

After validating meta elements, the system calculates a weighted overall score and determines publishing readiness.

### Weighted Category Scoring

The `rate_seo_quality()` function applies the following weights defined in [`data_sources/modules/seo_quality_rater.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/seo_quality_rater.py):

```python
weights = {
    'content': 0.20,
    'keywords': 0.25,
    'meta': 0.15,
    'structure': 0.15,
    'links': 0.15,
    'readability': 0.10,
}
overall_score = sum(category_score * weight for category, weight in weights.items())

```

The **meta category** (weight 0.15) directly impacts the final score based on the validation rules described above.

### Publishing Readiness Thresholds

Publishing readiness is determined by strict thresholds:

```python
publishing_ready = overall_score >= 80 and len(critical_issues) == 0

```

The system categorizes articles into four readiness tiers:

- **≥ 90**: Excellent – publish immediately
- **80‑89**: Good – minor tweaks allowed, still publishable
- **70‑79**: Fair – address priority fixes before publishing
- **< 70**: Needs work – significant improvements required

## Practical Usage and Report Output

To validate meta elements and check publishing readiness, run the command from the repository root:

```bash
/optimize drafts/podcast-analytics-2025.md

```

The generated report includes a dedicated meta-analysis section:

```markdown

## 5. SEO Quality Rating

**Overall SEO Score**: 84/100 – B (Good)
**Publishing Ready**: Yes

### Meta Elements

- Meta title: 58 chars ✅ (contains primary keyword)
- Meta description: 158 chars ✅ (contains primary keyword)
- No critical meta issues detected

```

If validation fails, the report flags critical blockers:

```markdown
- ❌ Meta title is missing (critical)
- Overall SEO Score: 62/100 – D (Needs Work)
- Publishing Ready: No

```

## Summary

- The `/optimize` command orchestrates the **Content Analyzer** agent and **SEOQualityRater** module to validate meta elements and score publishing readiness.
- Meta validation enforces length constraints (50‑60 chars for titles, 150‑160 chars for descriptions) and mandatory primary keyword inclusion, applying penalties up to **-40 points** for missing elements.
- The overall SEO score is calculated using weighted categories, with **meta elements contributing 15%** to the final 0‑100 rating.
- Publishing readiness requires an **overall score ≥ 80** and **zero critical issues**, ensuring only SERP‑optimized content reaches WordPress.

## Frequently Asked Questions

### What happens if my meta title is missing?

If the meta title is missing, the `SEOQualityRater._score_meta_elements()` method applies a **-40 point penalty** to the meta category score and flags it as a **critical issue**. This automatically disqualifies the article from publishing readiness, regardless of other scores.

### What SEO score is required for publishing readiness?

The `/optimize` command requires an **overall SEO score of 80 or higher** combined with **zero critical issues** to mark an article as publishing ready. Scores between 80‑89 are considered "Good" and publishable with minor tweaks, while scores below 80 block publication until improvements are made.

### How does the /optimize command handle keyword placement?

The command validates that the **primary keyword appears in both the meta title and meta description**. Missing keywords trigger warnings (-15 points for title, -10 points for description) but do not block publishing unless they contribute to dropping the overall score below 80 or are combined with other critical failures.

### Where is the scoring logic implemented?

The scoring logic resides in [`data_sources/modules/seo_quality_rater.py`](https://github.com/TheCraigHewitt/seomachine/blob/main/data_sources/modules/seo_quality_rater.py), specifically within the `SEOQualityRater` class. The `rate_seo_quality()` function orchestrates category weighting, while `_score_meta_elements()` handles the specific validation rules for titles and descriptions.