/fix

name: fix
description: Opt-in fixer (the /claude-seo-ai:fix command). Applies the safe, deterministic SEO/AI-search fixes from a persisted audit to the user's site — meta viewport/charset/lang, JSON-LD, robots.txt AI directives, hreflang, sitemaps, OG/Twitter cards, image dimensions, canonical, AI discovery files — through the adapter that matches the platform (local files, Shopify theme/Admin, WordPress REST/WP-CLI, page APIs, or step-by-step instructions). Dry-run preview by default; writes only after explicit per-change confirmation. Runs only when the user invokes it — never auto-triggered.
disable-model-invocation: true
argument-hint: "<url|path> [--target auto|local|shopify|shopify-theme|shopify-admin|wordpress|wordpress-rest|wordpress-wpcli|page-api|webflow|wix|ghost|hubspot|bigcommerce|instructions] [--category M5 --category auto] [--include-proposed] [--store <shop>] [--provider <webflow|wix|ghost|hubspot|bigcommerce>] [--site <id>] [--wp-url <u>] [--ssh user@host:/path] [--project <dir>] [--dev-url <u>] [--run <run_id|latest>] [--report <path>] [--lang en|es] [--dry-run] [--publish] [--rollback <run_id>] [--force]"
allowed-tools: Read, Grep, Glob, Bash, Agent

<!-- Portions Copyright (c) 2026 Enrique Rocha (@soyenriquerocha) - see LICENSE for original authors · tododeia.com · id er-d03758e1 -->

fix (opt-in writer)

`disable-model-invocation: true` means the model can **never** trigger this on its own — only the user running `/claude-seo-ai:fix`. Writes happen only through the **seo-fixer-writer** subagent (the one agent with Write/Edit) and only after explicit confirmation.

`--category` filters the report's findings and matches on a finding's **module id** (`M5`, `M7`, `M17`, …), its **axis** (`search`, `ai`, or `both` — which matches both of the other two), its **fixable class** (`auto`, `proposed`, `advisory`), or its **scope** (`page`, `site`, …), case-insensitively. It is **not** a topic vocabulary and it does **not** split on commas: repeat the flag to widen the filter (`--category M5 --category M17`). Translate what the user asks for into those words — "fix my schema" is `--category M5`, "just the safe ones" is `--category auto` — and say which filter you applied. `--target` accepts the adapter ids plus the aliases `local`, `shopify`, `wordpress`, `manual`, and the provider names `webflow`/`wix`/`ghost`/`hubspot`/`bigcommerce` (each expands to `page-api`).

Two absolutes, before anything else:

• **Never fix from memory.** Every change comes from a persisted `report.json` on disk. If there is

no report for this target, run the audit first — do not reconstruct findings from the transcript.

• **You never write.** This thread runs read-only ops (`capabilities`, `plan`, `preview`, `verify`).

`apply`, `publish` and `rollback` belong to the writer subagent, and each needs a ticket.

Fixability classes (from each finding's `fixable` field — see `schema/finding.schema.json`)

• **AUTO** — deterministic, additive, machine-verifiable, low-semantic-risk. May be written (with

diff + confirmation): meta `viewport`/`charset`/`<html lang>`; Tier-1 JSON-LD blocks; `sameAs`/ `@id`/`dateModified` (from confirmed inputs only); robots.txt AI-crawler presets + `Sitemap:` line; self-referential canonical; hreflang link sets; OG/Twitter cards; image `width`/`height`; XML sitemap entries; `llms.txt` (disclosure-gated, scored 0).

• **PROPOSED** — changes prose or meaning; draft the diff and require a per-item accept: generated

`<title>` and meta description, answer-block/TL;DR rewrites, internal-link insertions, heading restructuring, **generated image alt text**.

• **ADVISORY** — never written: content/E-E-A-T rewrites, added stats or citations, Core Web Vitals,

rendering strategy, redirects/status codes, link-building, Merchant Center/GBP backend data.

Setup for every step

DATA="${CLAUDE_SEO_AI_HOME:-${CLAUDE_PLUGIN_DATA:-$HOME/.claude-seo-ai}}"
SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"

Every command below is `node "${CLAUDE_PLUGIN_ROOT}/scripts/<x>.mjs" …` with `--data "$DATA"`. Credentials are **never** passed as flags: adapters read `CLAUDE_PLUGIN_OPTION_<KEY>` then `<KEY>` from the environment. If a key is missing, name the key — never ask the user to paste a value here.

Flow

**0. Resolve and short-circuit.** Resolve `DATA` and `SCRIPTS`. If `--rollback <run_id>` was given, skip everything else: read `<DATA>/fix/runs/<run_id>/manifest.json`, show what would be restored (files from `<DATA>/backups/<run_id>/`, `before/*.json` payloads, `previous_live_id` for a published theme), confirm, then have the **writer** run each adapter's `rollback --all`. Report and stop.

**1. Load the report — never from memory.** Take `--report <path>`, else `--run <id>`, else the latest run for this target under `<DATA>/runs/<host>/latest`. Read `report.json` (findings, scores, target) and the `profile.json` beside it. If the report is missing, or `generated_at` is more than 24 h old, say so and offer to re-run `/claude-seo-ai:audit` first. Do not proceed on a stale report without the user saying to.

**2. Confirm the platform profile.** Read `profile.platform`, `profile.framework`, `profile.capabilities`, `profile.write_targets`. When platform confidence is below `high`, or `--target auto` leaves more than one plausible write path, show what was detected (with the signals) and ask the user to confirm or override with `--target`. A wrong profile writes to the wrong surface.

**3. Choose adapters and check readiness.** Selection rules, in this order:

• a local path target (or `--project <dir>`) ⇒ `local-files`, plus a platform adapter for

per-resource fields the source tree does not own;

• shopify ⇒ `shopify-theme` + `shopify-admin`;
• wordpress ⇒ `wordpress-rest` when its credentials exist and the SEO plugin exposes writes, else

`wordpress-wpcli` when `--ssh`/`WP_SSH` is set, else `instructions`;

• webflow / wix / ghost / hubspot / bigcommerce ⇒ `page-api` when the