SEO Readability Rewrite Agent (Structure-Preserving)

The SEO Readability Rewrite Agent analyzes a WordPress post or page and improves its readability
while preserving structure, layout, and HTML integrity.

It is designed to work safely with Gutenberg and classic editor content without breaking markup or layout.

What This Agent Does

1. Detects content language.
2. Assesses readability:
   • English → Uses deterministic Flesch Reading Ease score.
   • Other languages → Uses AI-based readability judgment.
3. Rewrites text segments only (never raw HTML).
4. Optionally creates a preview draft for visual review.
5. Can apply changes directly to the original post (with revision support).

Supported Content Types

• ✅ Gutenberg blocks (Safe HTML approach)
• ✅ Classic editor content
• ⚠️ Complex page builders (Elementor, WPBakery, etc.) — not supported yet so use carefully

The agent works by extracting text nodes from HTML. Exotic builders may inject unpredictable structures.

Required Fields

Before the agent can start, the following must be provided:

• Post ID (selected post/page)
• Flesch threshold (numeric, 0–120)
• Model (LLM model name)

Internally, can_start() validates post existence, edit permission,
threshold correctness, and model selection.

Readability Strategy

English Content

Uses the Flesch Reading Ease formula:

• 90–100 → Very easy
• 60–70 → Standard
• < 50 → Hard to read

If the score is below the configured threshold, rewriting is triggered.

Non-English Content

• Uses AI-based clarity judgment
• Assigns qualitative readability assessment
• Triggers rewriting when clarity is insufficient

How Rewriting Works

1. Extracts text segments from HTML.
2. Sends batches to the LLM.
3. Receives strict JSON response:

[{"id":"123","text":"Rewritten segment"}]

4. Reinserts text into original HTML DOM.
5. Preserves structure, attributes, classes, block comments, and shortcodes.

Dry Run Mode (Preview Mode)

By default, the agent runs in dry mode.

• Performs full analysis
• Rewrites internally
• Does NOT modify original post
• Can optionally create a draft preview

Draft Preview Post

• Creates or updates a linked draft
• Stores relation via meta keys:

_s2baia_preview_of
_s2baia_preview_agent

• Allows full theme preview
• Updates existing preview instead of duplicating

Applying Changes

• Creates a revision of the original post
• Replaces content safely
• Preserves WordPress revision history

Safety Design

• Never modifies raw HTML blindly
• Never replaces full post blindly
• Never injects HTML from LLM
• Requires valid JSON output
• Validates responses before applying
• Uses nonces for AJAX
• Escapes output properly

Advanced Customization

The rewriting system supports filters:

s2baia_rewrite_segments_via_llm_system_common
s2baia_rewrite_segments_via_llm_system_strategy
s2baia_rewrite_segments_via_llm_user_task

This allows custom prompt engineering, language tuning, brand voice enforcement, tone control, and industry rules.

Example Use Cases

• Improve blog readability score
• Simplify legal or technical content
• Adapt tone while preserving layout
• Prepare multilingual content for clarity
• Create preview drafts for editorial review

Limitations

• Very short content may not benefit
• Highly custom builders may behave unpredictably
• Non-English readability scoring is heuristic
• Aggressive thresholds may cause heavy rewriting

Best Practice Recommendations

• Use preview draft mode
• Start with moderate thresholds (60–70)
• Keep custom instructions concise
• Review changes visually before applying
• Avoid running multiple rewrite cycles consecutively

Conceptual Philosophy

This agent is not a “magic SEO button.” It is a controlled, structured readability refactor tool
combining deterministic metrics, AI semantic clarity optimization, and WordPress-native revision safety.