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

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 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 and orchestrated by .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.
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.

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)

# 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:

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:

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:

/optimize drafts/podcast-analytics-2025.md

The generated report includes a dedicated meta-analysis section:

## 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:

- ❌ 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}