How the SEO Machine /rewrite Command Tracks Changes and Generates Before/After Comparisons

The /rewrite command in SEO Machine creates an immutable audit trail by saving a structured Change Summary markdown file alongside every rewritten article, embedding a visual before/after comparison block directly into the output for major rewrites.

The /rewrite command in the TheCraigHewitt/seomachine repository automates content optimization while maintaining complete transparency through structured change tracking. By generating parallel audit files and embedded comparison blocks, the system creates an immutable record of every modification made during the rewriting process.

The Three-Step Change Tracking Workflow

The change tracking mechanism is defined in .claude/commands/rewrite.md and executes three tightly coupled steps immediately after the rewriting engine finishes processing.

Step 1: Persisting the Rewritten Article

The command writes the new markdown content to a dated file path following the pattern rewrites/[topic-slug]-rewrite-[YYYY-MM-DD].md. This naming convention ensures every rewrite is versioned by date, preventing accidental overwrites of previous iterations. According to the file management logic in the command definition, this file serves as the canonical output that downstream agents and human editors will reference.

Step 2: Creating the Structured Change Summary

Simultaneously, the command generates a second file at rewrites/changes-[topic-slug]-[YYYY-MM-DD].md. This markdown file functions as a structured audit log, templated in the ### 2. Change Summary section of .claude/commands/rewrite.md. It records:

• Original Publication Date versus Rewrite Date
• Rewrite Scope classification (light, moderate, major, complete)
• Word Count Change formatted as [original] → [new]
• Estimated SEO Score Improvement
• Bullet-point lists of Major Changes, SEO Improvements, and Content Updates

This separation of concerns allows reporting tools to parse the change summary without parsing the full article text.

Step 3: Inserting the Before/After Comparison Block

For rewrites classified as major or complete, the command appends a concise visual diff to the end of the rewritten article file. Defined in the ### 3. Before/After Comparison section, this block juxtaposes key elements including the original headline versus the new headline, the original introduction versus the rewritten introduction, and a list of sections added or removed. Because this block lives in the same markdown document as the rewritten content, reviewers can scroll directly from the new text to the diff without opening separate comparison tools.

Workflow Architecture and Implementation Details

The change tracking system operates through five distinct phases baked into the command definition.

Pre-Rewrite Analysis and Scope Classification

Before any text generation begins, the command pulls existing analysis via /analyze-existing and retrieves current brand/SEO guidelines. This pre-flight check determines the rewrite scope—categorized as light, moderate, major, or complete—which dictates whether the system generates the optional before/after comparison block.

Structured Data Capture in Change Summaries

After the article is rewritten but before file persistence, the command populates the Change Summary template with quantitative metrics. The word-count delta is calculated by comparing the original document length against the newly generated text. The system also catalogs specific SEO upgrades, such as primary keyword integration in H2 headings or internal link additions, creating a machine-readable record of optimization efforts.

Visual Diff Generation for Major Rewrites

When the scope determination flags a rewrite as major or complete, the command extracts the original headline and introduction from the source material and pairs them with their rewritten counterparts. This diff-style section appears at the end of rewrites/[topic-slug]-rewrite-[YYYY-MM-DD].md, providing immediate visual context for the magnitude of changes without requiring external diff utilities.

Post-Processing and Agent Integration

Immediately after persisting both the rewritten article and the change summary, the command triggers the content scrubber (/scrub) followed by a suite of SEO agents including the optimizer, meta-creator, internal-linker, and keyword-mapper. These agents operate on the post-scrub version of the article, ensuring that the change-tracking data reflects the final human-readable output rather than intermediate draft states.

Practical Example: Tracking a Content Upgrade

Executing a rewrite generates two distinct files that work together to form a complete audit trail.

# Trigger a major rewrite

/rewrite content-marketing-guide

After execution, the rewrites/ directory contains:

rewrites/content-marketing-guide-rewrite-2025-10-15.md
rewrites/changes-content-marketing-guide-2025-10-15.md

Contents of changes-content-marketing-guide-2025-10-15.md:

---
Original Publication Date: 2023-04-01
Rewrite Date: 2025-10-15
Rewrite Scope: Major Rewrite
Word Count Change: 1,200 → 1,800
Primary Keyword: content marketing strategy
SEO Score Improvement: +25
---

Major Changes:
- Added a new "AI-driven tactics" section
- Removed outdated 2022 statistics
- Refactored intro for stronger hook

SEO Improvements:
- Integrated primary keyword in three H2s
- Added 4 internal links to pillar content
- Updated meta title & description

Before/After block appended to content-marketing-guide-rewrite-2025-10-15.md:

### 3. Before/After Comparison

- **Original headline**: "The Ultimate Guide to Content Marketing"
- **New headline**: "2025 Content Marketing Strategy: AI-Driven Tactics & Proven ROI"

- **Original intro**: "Content marketing has been a cornerstone…"
- **New intro**: "In 2025, AI reshapes how brands create content…"

- Sections added: AI-driven tactics, Voice-search optimization
- Sections removed: Out-of-date 2022 case study

Summary

• Dual-file output: Every execution produces both the rewritten article at rewrites/[topic-slug]-rewrite-[date].md and a structured change log at rewrites/changes-[topic-slug]-[date].md.
• Scope-driven comparisons: The before/after comparison block only generates for major or complete rewrites, as defined in .claude/commands/rewrite.md.
• Quantified metrics: The Change Summary captures word-count deltas, SEO score improvements, and specific content modifications in a parseable markdown format.
• Immutable versioning: Date-stamped filenames and structured audit trails ensure every rewrite remains transparent and reproducible for downstream reporting tools.

Frequently Asked Questions

Where does SEO Machine store rewrite change logs?

The command saves structured change logs to rewrites/changes-[topic-slug]-[YYYY-MM-DD].md in the repository root. This file exists alongside the rewritten article and contains metadata including publication dates, scope classification, word-count changes, and bullet-point lists of major edits.

What triggers the before/after comparison block?

The comparison block generates only when the rewrite scope is classified as major or complete during the pre-rewrite analysis phase. Light or moderate rewrites skip this step to avoid cluttering the output with negligible differences, as specified in the ### 3. Before/After Comparison section of .claude/commands/rewrite.md.

How does the command calculate word-count deltas?

The system compares the word count of the original source material against the newly generated text before the content scrubber (/scrub) and SEO agents process the final output. This metric appears in the Change Summary as Word Count Change: [original] → [new], providing a quantitative measure of content expansion or contraction.

Can the Change Summary file be used for automated reporting?

Yes. Because the Change Summary uses a consistent markdown template with YAML frontmatter and standardized bullet-point sections for Major Changes, SEO Improvements, and Content Updates, external scripts can easily parse these files to feed performance dashboards or quantify the ROI of content updates across multiple articles.

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