# SEO instructions for the Claude routine

This file tells Claude what to do on every run of the routine. Edit it as much as you like: your brand's tone, the fields to rework, rules specific to your store. The sections marked "Customize" are the ones you will change most often.

## Golden rule: one piece of content per run

On each run, you handle **one piece of content only**, then you stop. Even if there is time left, even if other rows are waiting. The next run will pick up the next one.

## The tracking file

The `suivi-seo.csv` file, at the root of the repository, lists the content to optimize. Columns:

| Column | Content |
| --- | --- |
| `Type` | `product`, `collection`, `page` or `article` |
| `Handle` | the Shopify handle of the content |
| `Title` | the current title, for reference |
| `Optimized` | `YES` once the proposal has been sent to Vetta, otherwise `NO` |
| `OptimizedAt` | date and time it was sent (ISO 8601, for example `2026-09-25T14:00:00Z`) |
| `WorkingNow` | `YES` while a run is working on the row, otherwise `NO` |
| `WorkingSince` | date and time `WorkingNow` was set to `YES` |
| `VettaStatus` | status of the proposal in Vetta (`pending`, `approved`, `changes_requested`, `rejected`) |
| `VettaProposalUrl` | review link for the proposal in Vetta |

## How a run works

1. Read `suivi-seo.csv`.
2. If a row has had `WorkingNow = YES` for less than 2 hours, another run is in progress: stop without changing anything. If it has been more than 2 hours, treat that run as abandoned and set `WorkingNow` back to `NO`.
3. Pick the first row where `Optimized = NO`. If there is none, stop and say that everything has been processed.
4. Set that row to `WorkingNow = YES`, fill in `WorkingSince`, then commit and push right away (message: `seo: start <handle>`).
5. Using the Vetta connector, call `get_shop_context` to learn about the store and its languages. Then find the content with `list_contents` (parameters `type` and `query` = the handle) to get its ID, and read it with `get_content`.
6. Write the new version following the rules below. Base it on the SEO recommendations (`seo`) and, if Search Console is connected, on the queries close to the first page (`gsc.opportunities`) returned by `get_content`.
7. Send it with `propose_version`. You never publish: a person will review the proposal in Vetta. If the returned SEO score points to a problem you can fix, send a new proposal: it replaces the previous one.
8. Update the row: `Optimized = YES`, `OptimizedAt`, `WorkingNow = NO`, `WorkingSince` empty, `VettaStatus = pending`, `VettaProposalUrl` = the review link returned by `propose_version`.
9. Commit and push (message: `seo: <handle> proposed in Vetta`), then stop.

If a step fails (content not found, connector error), set `WorkingNow` back to `NO`, leave `Optimized` at `NO`, write the error in `VettaStatus` and push the file. Do not move on to another row.

## What to optimize (Customize)

- **SEO title**: 50 to 60 characters, main keyword at the start, brand name at the end if there is room.
- **Meta description**: 140 to 155 characters, one concrete benefit and a reason to click.
- **Description**: structured with subheadings and short paragraphs, main keyword in the first 100 words, no keyword stuffing.
- **Handle**: do not change it unless it is unreadable (for example `copy-of-product-2`). In that case, propose a short lowercase handle with hyphens.
- **Image alt text**: describe what the image shows, in one sentence.

## Writing rules (Customize)

- Language: English.
- Tone: [describe your brand's tone, for example "knowledgeable but approachable, no superlatives"].
- Never invent a feature, material, dimension, certification or figure. Only use what is already in the content or elsewhere in the store. If an important piece of information is missing, flag it in your summary.
- Keep existing internal links.
- Avoid empty phrases ("premium quality", "must-have", "discover our selection").

## End-of-run summary

Finish with two or three sentences on what you changed and why, with the review link, and list any information you could not verify. This summary appears in the routine's history.