# Analisi operativa step-by-step - `mcp-mantis-test-writer`

Repository: `https://github.com/sophiadeveloper/mcp-servers`

Branch target: `rework`

Spec primaria: `prompt_mcp_mantis_test_writer.md`

## Obiettivo complessivo

Implementare in modo progressivo la nuova skill `mcp-mantis-test-writer`, aggiornando agenti, documentazione e, solo se utile, routing hooks, mantenendo scope minimo e compatibilita' con gli standard gia' presenti nel repository.

La skill deve produrre checklist di test manuali in formato Mantis-ready, direttamente in chat/video, copy-paste ready, senza integrazione diretta con Mantis e senza creare o modificare file di test applicativi.

## Principi guida

- Procedere per step piccoli, reviewable e validabili.
- Prima leggere pattern e file esistenti, poi modificare.
- Non introdurre refactor non richiesti.
- Non modificare ruoli o tool assegnati agli agenti.
- Non modificare `scripts/portable-agents-lib.js`.
- Non modificare manualmente runtime generati degli agenti, salvo workflow esplicitamente previsto e motivato.
- Non eseguire `node scripts/sync-portable-agents.js` se non richiesto da workflow esistente.
- Non introdurre integrazione con `mantis-mcp` nella nuova skill.
- Non aggiungere note reali a ticket Mantis.
- Non creare file di test automatici.
- Non eseguire test applicativi.
- Non introdurre framework di test.

## Stato iniziale e gap da coprire

### 1. Agente `test_writer`

File da verificare e aggiornare:

```text
docs/agents/canonical-subagents.yaml
```

Gap:

- Il ruolo `test_writer` esiste gia', ma va reso piu' esplicito come ruolo read-only.
- Deve produrre output in chat.
- Deve scrivere checklist manuali, smoke scenario, regression plan e test note Mantis-ready.
- Deve chiarire che non crea file test e non esegue test.
- Deve demandare a `implementer` solo se l'utente chiede esplicitamente creazione o modifica di file di test automatici.
- Conviene rimuovere o ridimensionare riferimenti troppo ampi ad automation candidates, per evitare ambiguita' con implementazione test.

### 2. Nuova skill `mcp-mantis-test-writer`

Directory richiesta:

```text
skills/mcp-mantis-test-writer/
```

Struttura richiesta:

```text
skills/mcp-mantis-test-writer/
├── SKILL.md
├── references/
│   ├── template-format.md
│   └── output-examples.md
└── evals/
    └── evals.json
```

Non creare `scripts/` o `assets/` salvo necessita' reale e motivata.

Gap da coprire:

- Frontmatter con `name: mcp-mantis-test-writer`.
- Description con trigger precisi:
  - checklist test manuali;
  - test regression;
  - test nuove funzionalita';
  - Mantis-ready output;
  - PR/handoff/code review findings/ticket validation;
  - no Mantis note creation;
  - no test file writing.
- Regole permanenti chat-only.
- Separazione obbligatoria tra:
  - `Test nuove funzionalita'`;
  - `Test regression`.
- ID stabili `T01`, `T02`, `T03`.
- Passi nel formato `- 1)`, `- 2)`, `- 3)`.
- Legenda esiti `TODO`, `OK`, `KO`.
- Domande massime 1-3 solo se bloccanti.
- Nessuna invenzione di dati, path, funzioni, tabelle o risultati attesi.

### 3. Documentazione operativa

File prioritario:

```text
docs/developer-guide-agentic-programming.md
```

File ulteriori:

```text
docs/agents/local-orchestration-playbook.md
docs/skill-governance-matrix.md
```

Gap da coprire:

- Aggiungere `mcp-mantis-test-writer` nella tabella skill.
- Sostituire riferimenti generici al piano test quando il task e' scrivere checklist manuale.
- Correggere la Fase 6 "Piano di Test" per usare:
  - skill `mcp-mantis-test-writer`;
  - subagent `test_writer`;
  - output solo in chat;
  - divieto di aggiungere note Mantis;
  - divieto di creare file.
- Correggere la sezione Valutatore, dove non deve essere usato `mcp-mantis-ticket-writer` per generare casi di test.
- Chiarire la separazione:
  - `mcp-mantis-test-writer`: checklist test Mantis-ready in chat;
  - `mcp-mantis-ticket-writer`: scrittura/refinement ticket;
  - `mcp-git-mantis-workflow` o `mantis-mcp`: nota reale sul ticket;
  - `mcp-browser-automation`: esecuzione test browser/UI;
  - `implementer`: creazione/modifica file test automatici solo su richiesta esplicita.

### 4. Hooks e routing automatico

File da verificare:

```text
scripts/hooks/sophia-user-prompt-submit.mjs
scripts/build-routing-catalog.mjs
scripts/smoke-codex-hooks.js
fixtures/hooks/
```

Decisione consigliata:

- Prima verificare se il routing catalog generato dai `SKILL.md` e' sufficiente.
- Se la nuova skill non viene suggerita in modo preciso, aggiornare gli hint curati con modifiche minime.
- Non usare keyword troppo generiche come solo `test`, per evitare falsi positivi.

Keyword consigliate:

- `checklist test`
- `piano test manuale`
- `test regression`
- `test regressione`
- `Mantis-ready`
- `READY to TEST`
- `test manuali`
- `casi di test da incollare`

Routing da preservare:

- `mcp-mantis-ticket-writer` per scrivere o rifinire ticket.
- `mcp-git-mantis-workflow` per note reali su ticket, branch, commit, allegati, rebase.
- `mcp-browser-automation` per esecuzione test UI/browser.
- `mcp-code-reviewer` per review e test gap nel diff.
- `mcp-technical-analyst` per intake multi-sorgente.

Se si modificano hooks:

- aggiungere fixture dedicata;
- aggiornare smoke test;
- eseguire `node scripts/build-routing-catalog.mjs`;
- eseguire `node scripts/smoke-codex-hooks.js`.

## Sequenza di sviluppo consigliata

### Step 0 - Ricognizione read-only

Obiettivo:

- leggere la specifica allegata;
- controllare pattern di skill e documentazione esistenti;
- identificare file effettivamente da toccare.

File da leggere almeno:

```text
skills/mcp-mantis-ticket-writer/SKILL.md
skills/mcp-code-reviewer/SKILL.md
skills/mcp-browser-automation/SKILL.md
skills/mcp-technical-analyst/SKILL.md
skills/mcp-master-orchestrator/SKILL.md
docs/agents/canonical-subagents.yaml
docs/developer-guide-agentic-programming.md
docs/agents/local-orchestration-playbook.md
docs/skill-governance-matrix.md
scripts/hooks/sophia-user-prompt-submit.mjs
scripts/build-routing-catalog.mjs
scripts/smoke-codex-hooks.js
```

Output dello step:

- elenco file da modificare;
- conferma se hooks vanno aggiornati o solo verificati;
- rischi/ambiguita' prima della modifica.

### Step 1 - Aggiornare `test_writer`

Obiettivo:

- aggiornare solo `docs/agents/canonical-subagents.yaml`.

Regole:

- `test_writer` deve restare read-only.
- Non cambiare id agente.
- Non modificare ruoli/tool agenti.
- Non modificare runtime generati.
- Non modificare generatori.

Output atteso:

- diff limitato al blocco `test_writer`;
- conferma no runtime/manual generated files.

Validazione minima:

```bash
git diff -- docs/agents/canonical-subagents.yaml
```

### Step 2 - Creare la skill

Obiettivo:

- creare la nuova skill con struttura richiesta.

File da creare:

```text
skills/mcp-mantis-test-writer/SKILL.md
skills/mcp-mantis-test-writer/references/template-format.md
skills/mcp-mantis-test-writer/references/output-examples.md
skills/mcp-mantis-test-writer/evals/evals.json
```

Regole:

- Nessuna cartella `scripts/`.
- Nessuna cartella `assets/`.
- Nessuna integrazione Mantis.
- Output solo chat/video.
- Formato copy-paste ready.

Validazione minima:

```bash
find skills/mcp-mantis-test-writer -maxdepth 3 -type f -print
cat skills/mcp-mantis-test-writer/SKILL.md
cat skills/mcp-mantis-test-writer/references/template-format.md
cat skills/mcp-mantis-test-writer/references/output-examples.md
cat skills/mcp-mantis-test-writer/evals/evals.json
```

### Step 3 - Aggiornare documentazione routing

Obiettivo:

- aggiornare documentazione operativa e governance.

File da modificare:

```text
docs/developer-guide-agentic-programming.md
docs/agents/local-orchestration-playbook.md
docs/skill-governance-matrix.md
```

Priorita':

- `docs/developer-guide-agentic-programming.md` e' il file piu' importante.

Modifiche richieste:

- tabella skill con nuova riga `mcp-mantis-test-writer`;
- Fase 6 aggiornata con prompt nuovo;
- sezione Valutatore aggiornata;
- distinzione tra checklist in chat e nota reale su ticket;
- distinzione tra scrittura checklist ed esecuzione test UI/browser;
- distinzione tra checklist manuali e file test automatici.

Validazione minima:

```bash
git diff -- docs/developer-guide-agentic-programming.md docs/agents/local-orchestration-playbook.md docs/skill-governance-matrix.md
```

### Step 4 - Verificare e aggiornare hooks solo se serve

Obiettivo:

- verificare se la nuova skill viene intercettata dal routing automatico.

Prima scelta:

- non modificare hooks se il catalogo generato da `SKILL.md` produce routing sufficiente.

Modifica hooks solo se:

- prompt come "prepara checklist test Mantis-ready" non suggerisce la nuova skill;
- il routing finisce su `mcp-mantis-ticket-writer` in modo ambiguo;
- la guida hook curata richiede una voce specifica per evitare confusione.

Se si modifica:

- aggiornare `DOMAIN_KEYWORDS` e `SKILL_HINTS` in modo conservativo;
- considerare aggiornamento `inferCategory` in `scripts/build-routing-catalog.mjs` con categoria `testing` o `ticketing-testing`;
- aggiungere fixture smoke mirata;
- aggiornare `scripts/smoke-codex-hooks.js`.

Validazioni:

```bash
node scripts/build-routing-catalog.mjs
node scripts/smoke-codex-hooks.js
```

### Step 5 - Validazione complessiva

Comandi minimi:

```bash
git diff -- . ':(exclude)node_modules'
find skills/mcp-mantis-test-writer -maxdepth 3 -type f -print
cat skills/mcp-mantis-test-writer/SKILL.md
cat skills/mcp-mantis-test-writer/references/template-format.md
cat skills/mcp-mantis-test-writer/references/output-examples.md
cat skills/mcp-mantis-test-writer/evals/evals.json
```

Comandi condizionali:

```bash
node scripts/build-routing-catalog.mjs
node scripts/smoke-codex-hooks.js
```

Eseguire comandi docs/agenti aggiuntivi solo se presenti nel repo, per esempio:

```bash
node scripts/check-agents-doc.js
```

Non eseguire test applicativi.

### Step 6 - Review spec-compliance

Usare `mcp-code-reviewer` con subagent `code_reviewer` in modalita' `spec-compliance`.

Verificare:

- tutti i requisiti della specifica allegata;
- no scope drift;
- no integrazione Mantis;
- no file test;
- no esecuzione test;
- no modifiche ruoli/tool agenti;
- documentazione coerente;
- formato checklist conforme.

### Step 7 - Review tecnica

Usare `mcp-code-reviewer` con subagent `code_reviewer`.

Verificare:

- coerenza con pattern skill esistenti;
- qualita' `SKILL.md`;
- separazione core/references;
- eval coverage;
- routing non ambiguo;
- eventuali hooks non rumorosi;
- validazioni eseguite.

### Step 8 - Correzioni mirate e riepilogo finale

Se le review trovano finding:

- applicare solo fix minimi;
- rieseguire validazioni pertinenti;
- ripetere review necessaria.

Output finale richiesto:

- file creati/modificati;
- riepilogo modifiche;
- comandi eseguiti e risultato;
- conferma `test_writer` read-only;
- conferma ruoli/tool agenti invariati;
- conferma nuova skill chat/video only;
- conferma nessuna integrazione Mantis;
- conferma nessun file test applicativo;
- conferma formato checklist;
- rischi residui o follow-up.

## Criteri di accettazione finali

### Skill

- `skills/mcp-mantis-test-writer/SKILL.md` presente e coerente.
- References presenti e utili.
- Evals presenti e allineati ai rischi principali.
- Nessuno script locale non necessario.
- Nessun asset non necessario.

### Agente

- `test_writer` esplicitamente read-only.
- Output in chat.
- No file edits.
- No test execution.
- Handoff a `implementer` solo per creazione/modifica file test automatici richiesta esplicitamente.

### Documentazione

- Guida sviluppatore aggiornata.
- Fase 6 corretta.
- Sezione Valutatore corretta.
- Governance matrix aggiornata.
- Playbook coerente.

### Hooks

- Nessuna modifica se non necessaria.
- Se modificati, routing conservativo e smoke test aggiornati.
- Nessun conflitto con ticket writer, git-mantis workflow o browser automation.

### Formato checklist

- Markdown con elenchi puntati.
- Nessuna lista ordinata markdown standard.
- Passi nel formato:
  - `- 1)`
  - `- 2)`
  - `- 3)`
- Sezioni separate:
  - `# Test nuove funzionalita'`
  - `# Test regression`
- ID test progressivi `T01`, `T02`, `T03`.
- Legenda esiti:
  - `TODO`
  - `OK`
  - `KO`

## Note per review e regressioni

Rischi da controllare con attenzione:

- Ambiguita' tra scrivere checklist test e scrivere ticket Mantis.
- Ambiguita' tra scrivere checklist test e aggiungere nota reale al ticket.
- Ambiguita' tra scrivere checklist manuale e creare file test automatici.
- Ambiguita' tra scrivere piano test e eseguire test browser/UI.
- Routing hooks troppo aggressivo su keyword generica `test`.
- Documentazione che chiede alla nuova skill di fare azioni fuori scope.
- Eval troppo generici o non collegati ai vincoli principali.