content-factory/tasks/015-seo-and-language-review.md

Task 015: SEO And Language Review

Development description: Implement SEO and linguistic review jobs, issue reports, editor accept/reject/edit flows, and versioned application of accepted suggestions.

Implementation Details

• Backend endpoints:
  • POST /api/articles/{article_id}/seo/review
  • GET /api/articles/{article_id}/seo/report
  • POST /api/articles/{article_id}/language/review
  • GET /api/articles/{article_id}/language/report
  • endpoints to accept/reject/edit individual suggestions.
• SEO checks:
  • Title length.
  • Meta title length.
  • Meta description length.
  • H1/H2 structure.
  • Keyword placement.
  • Internal links.
  • External citations.
  • Schema type.
  • Slug.
  • FAQ eligibility.
  • Image alt text.
  • Readability.
  • Duplicate headings.
• Language checks:
  • Grammar.
  • Spelling.
  • Sentence length.
  • Passive voice.
  • Jargon density.
  • Brand tone.
  • Forbidden phrases.
  • Repetition.
  • Weak claims.
  • Unsupported certainty.
  • CTA consistency.
• Accepted suggestions create a new draft version when they change approval-relevant content.

Public Interface

• Editor runs SEO and language review.
• Editor accepts, rejects, or edits suggestions.
• UI shows issues with severity and locations.

Acceptance Criteria

• TDD pre-requirement: before implementation, write one failing behavior test that runs an SEO review and returns a visible issue through the public API; proceed one review behavior at a time and record evidence in Result.
• SEO report includes score, issues, suggested fixes, recommended slug/title, and schema JSON.
• Language report includes severity, location, message, and suggested rewrite.
• Editor can accept, reject, or edit each suggestion.
• Accepted content changes create a new immutable draft version.
• Target-site SEO and tone rules override global defaults.
• Final review can show unresolved SEO/language issues.
• Fake review runner produces deterministic demo reports.

Verification

• Run review API tests.
• Run draft-versioning tests for accepted suggestions.
• Run frontend review UI tests.
• Run Docker Compose smoke flow from draft to SEO/language reports.

Result

• Status: Pending execution.
• TDD plan: To be filled during execution.
• Red evidence: To be filled during execution.
• Green evidence: To be filled during execution.
• Refactor notes: To be filled during execution.
• Verification output: To be filled during execution.