# Istruzioni SEO per la routine Claude

Questo file dice a Claude cosa fare a ogni esecuzione della routine. Modificalo liberamente: tono del brand, campi da rielaborare, regole specifiche del tuo negozio. Le sezioni segnate «Da adattare» sono quelle che cambierai più spesso.

## Regola assoluta: un solo contenuto per esecuzione

A ogni esecuzione tratti **un solo contenuto**, poi ti fermi. Anche se resta tempo, anche se ci sono altre righe in attesa. L'esecuzione successiva prenderà il contenuto seguente.

## Il file di monitoraggio

Il file `suivi-seo.csv`, nella radice del repository, elenca i contenuti da ottimizzare. Colonne:

| Colonna | Contenuto |
| --- | --- |
| `Type` | `product`, `collection`, `page` o `article` |
| `Handle` | l'handle Shopify del contenuto |
| `Title` | il titolo attuale, come riferimento |
| `Optimized` | `YES` dopo l'invio della proposta a Vetta, altrimenti `NO` |
| `OptimizedAt` | data e ora dell'invio (ISO 8601, per esempio `2026-09-25T14:00:00Z`) |
| `WorkingNow` | `YES` mentre un'esecuzione lavora sulla riga, altrimenti `NO` |
| `WorkingSince` | data e ora del passaggio di `WorkingNow` a `YES` |
| `VettaStatus` | stato della proposta in Vetta (`pending`, `approved`, `changes_requested`, `rejected`) |
| `VettaProposalUrl` | link di approvazione della proposta in Vetta |

## Svolgimento di un'esecuzione

1. Leggi `suivi-seo.csv`.
2. Se una riga ha `WorkingNow = YES` da meno di 2 ore, un'altra esecuzione è in corso: fermati senza modificare nulla. Se è così da più di 2 ore, considerala abbandonata e rimetti `WorkingNow` a `NO`.
3. Scegli la prima riga con `Optimized = NO`. Se non ce n'è nessuna, fermati e segnala che è tutto fatto.
4. Porta la riga a `WorkingNow = YES`, compila `WorkingSince`, poi fai subito commit e push (messaggio: `seo: inizio <handle>`).
5. Con il connettore Vetta, chiama `get_shop_context` per conoscere il negozio e le sue lingue. Poi trova il contenuto con `list_contents` (parametri `type` e `query` = l'handle) per ottenerne l'identificativo, e leggilo con `get_content`.
6. Scrivi la nuova versione seguendo le regole qui sotto. Basati sui consigli SEO (`seo`) e, se Search Console è collegata, sulle query vicine alla prima pagina (`gsc.opportunities`) restituite da `get_content`.
7. Inviala con `propose_version`. Non pubblichi mai: una persona rileggerà la proposta in Vetta. Se il punteggio SEO restituito segnala un problema che puoi correggere, invia una nuova proposta: sostituisce la precedente.
8. Aggiorna la riga: `Optimized = YES`, `OptimizedAt`, `WorkingNow = NO`, `WorkingSince` vuoto, `VettaStatus = pending`, `VettaProposalUrl` = il link di approvazione restituito da `propose_version`.
9. Fai commit e push (messaggio: `seo: <handle> proposto in Vetta`), poi fermati.

Se un passaggio fallisce (contenuto non trovato, errore del connettore), rimetti `WorkingNow` a `NO`, lascia `Optimized` a `NO`, scrivi l'errore in `VettaStatus` e fai push del file. Non passare a un'altra riga.

## Cosa ottimizzare (Da adattare)

- **Titolo SEO**: da 50 a 60 caratteri, parola chiave principale all'inizio, nome del brand alla fine se c'è spazio.
- **Meta description**: da 140 a 155 caratteri, un vantaggio concreto e un invito al clic.
- **Descrizione**: strutturata con sottotitoli e paragrafi brevi, parola chiave principale nelle prime 100 parole, senza keyword stuffing.
- **Handle**: non modificarlo, a meno che non sia illeggibile (per esempio `copia-di-prodotto-2`). In quel caso proponi un handle breve, in minuscolo, con i trattini.
- **Testo alternativo delle immagini**: descrivi in una frase ciò che mostra l'immagine.

## Regole di scrittura (Da adattare)

- Lingua: italiano. Dai del tu al cliente.
- Tono: [descrivi il tono del tuo brand, per esempio «competente ma alla mano, senza superlativi»].
- Non inventare mai caratteristiche, materiali, dimensioni, certificazioni o numeri. Usa solo ciò che è già presente nel contenuto o nel negozio. Se manca un'informazione importante, segnalalo nel resoconto.
- Mantieni i link interni esistenti.
- Evita le frasi vuote («di qualità superiore», «imperdibile», «scopri la nostra selezione»).

## Resoconto di fine esecuzione

Chiudi riassumendo in due o tre frasi cosa hai cambiato e perché, con il link di approvazione, ed elenca le informazioni che non hai potuto verificare. Questo riepilogo compare nella cronologia della routine.