gh-leobrival-blog-kit-plugin/commands/blog-optimize.md

Blog Quality Optimization

Validate article quality with automated checks for frontmatter, markdown formatting, and spec compliance.

Usage

Single Article (Recommended)

/blog-optimize "lang/article-slug"

Examples:

/blog-optimize "en/nodejs-tracing"
/blog-optimize "fr/microservices-logging"

Token usage: ~10k-15k tokens per article

Global Validation (⚠️ High Token Usage)

/blog-optimize

⚠️ WARNING: This will validate ALL articles in your content directory.

Token usage: 50k-500k+ tokens (depending on article count) Cost: Can be expensive (e.g., 50 articles = ~500k tokens) Duration: 20-60 minutes for large blogs Use case: Initial audit, bulk validation, CI/CD pipelines

Recommendation: Validate articles individually unless you need a full audit.

Prerequisites

✅ Required: Article must exist at articles/[topic].md

If article doesn't exist, run /blog-generate or /blog-marketing first.

What This Command Does

Delegates to the quality-optimizer subagent to validate article quality:

• Spec Compliance: Validates against .spec/blog.spec.json requirements
• Frontmatter Structure: Checks required fields and format
• Markdown Quality: Validates syntax, headings, links, code blocks
• SEO Elements: Checks meta description, keywords, internal links
• Readability: Analyzes sentence length, paragraph size, passive voice
• Brand Voice: Validates against voice_dont anti-patterns

Time: 10-15 minutes Output: .specify/quality/[topic]-validation.md

Instructions

Create a new subagent conversation with the quality-optimizer agent.

Provide the following prompt:

You are validating the quality of a blog article.

**Article Path**: articles/$ARGUMENTS.md

Follow your Three-Phase Process:

1. **Spec Compliance Validation** (5-7 min):
   - Generate validation script in /tmp/validate-spec-$$.sh
   - Load .spec/blog.spec.json (if exists)
   - Check frontmatter required fields
   - Validate review_rules compliance (must_have, must_avoid)
   - Check brand voice anti-patterns (voice_dont)
   - Run script and capture results

2. **Markdown Quality Validation** (5-10 min):
   - Generate validation script in /tmp/validate-markdown-$$.sh
   - Check heading hierarchy (one H1, proper nesting)
   - Validate link syntax (no broken links)
   - Check code blocks (properly closed, language tags)
   - Verify images have alt text
   - Run script and capture results

3. **SEO and Performance Validation** (3-5 min):
   - Generate validation script in /tmp/validate-seo-$$.sh
   - Check meta description length (150-160 chars)
   - Validate keyword presence in critical locations
   - Count internal links (minimum 3 recommended)
   - Calculate readability metrics
   - Run script and capture results

**Output Location**: Save comprehensive validation report to `.specify/quality/$ARGUMENTS-validation.md`

**Important**:
- All scripts must be generated in /tmp/ (never pollute project directory)
- Scripts are non-destructive (read-only operations)
- Provide actionable fixes for all issues found
- Include metrics and recommendations in report

Begin validation now.

Expected Output

After completion, verify that .specify/quality/[topic]-validation.md exists and contains:

✅ Passed Checks Section:

• List of all successful validations
• Green checkmarks for passing items

✅ Warnings Section:

• Non-critical issues that should be addressed
• Improvement suggestions

✅ Critical Issues Section:

• Must-fix problems before publishing
• Clear descriptions of what's wrong

✅ Metrics Dashboard:

• Frontmatter completeness
• Content structure statistics
• SEO metrics
• Readability scores

✅ Recommended Fixes:

• Prioritized list (critical first)
• Code snippets for fixes
• Step-by-step instructions

✅ Validation Scripts:

• List of generated scripts in /tmp/
• Instructions for manual review/cleanup

Interpreting Results

✅ All Checks Passed

✅ Passed Checks (12/12)

No issues found! Article is ready to publish.

Next Steps: Review the article one final time and publish.

⚠️ Warnings Only

✅ Passed Checks (10/12)
⚠️  Warnings (2)

- Only 2 internal links (recommend 3+)
- Keyword density 2.3% (slightly high)

Next Steps: Address warnings if possible, then publish (warnings are optional improvements).

❌ Critical Issues

✅ Passed Checks (8/12)
⚠️  Warnings (1)
❌ Critical Issues (3)

- Missing required frontmatter field: category
- 2 images without alt text
- Unclosed code block

Next Steps: Fix all critical issues before publishing. Re-run /blog-optimize after fixes.

Review Checklist

Before considering article complete:

1. Frontmatter Complete?

   • All required fields present
   • Meta description 150-160 chars
   • Valid date format

2. Content Quality?

   • Proper heading hierarchy
   • No broken links
   • All images have alt text
   • Code blocks properly formatted

3. SEO Optimized?

   • Keyword in title and headings
   • 3+ internal links
   • Meta description compelling
   • Readable paragraphs (<150 words)

4. Spec Compliant?

   • Meets all must_have requirements
   • Avoids all must_avoid patterns
   • Follows brand voice guidelines

Next Steps

After validation is complete:

If All Checks Pass ✅

# Publish the article
# (copy to your CMS or commit to git)

If Issues Found ⚠️ ❌

# Fix issues manually or use other commands

# If content needs rewriting:
/blog-marketing "topic-name"  # Regenerate with fixes

# If SEO needs adjustment:
/blog-seo "topic-name"  # Regenerate SEO brief

# After fixes, re-validate:
/blog-optimize "topic-name"

When to Use This Command

Use /blog-optimize when you need to:

• ✅ Before publishing: Final quality check
• ✅ After manual edits: Validate changes didn't break anything
• ✅ Updating old articles: Check compliance with current standards
• ✅ Troubleshooting: Identify specific issues in article
• ✅ Learning: See what makes a quality article

For full workflow: /blog-generate includes optimization as final step (optional).

Tips

1. Run after each major edit: Catch issues early
2. Review validation scripts: Learn what good quality means
3. Keep constitution updated: Validation reflects your current standards
4. Fix critical first: Warnings can wait, critical issues block publishing
5. Use metrics to improve: Track quality trends over time

Requesting Re-validation

After fixing issues:

/blog-optimize "topic-name"

The agent will re-run all checks and show improvements:

Previous: ❌ 3 critical, ⚠️  2 warnings
Current:  ✅ All checks passed!

Improvements:
- Fixed missing frontmatter field ✅
- Added alt text to all images ✅
- Closed unclosed code block ✅

Validation Script Cleanup

Scripts are generated in /tmp/ and can be manually removed:

# List validation scripts
ls /tmp/validate-*.sh

# Remove all validation scripts
rm /tmp/validate-*.sh

# Or let OS auto-cleanup on reboot

Error Handling

If validation fails:

• Check article exists: Verify path articles/[topic].md
• Check constitution valid: Run bash scripts/validate-constitution.sh
• Review script output: Check /tmp/validate-*.sh for errors
• Try with simpler article: Test validation on known-good article

---

Ready to validate? Provide the topic name and execute this command.