1. Definire la “Single Source of Truth” nelle Instructions

Per prima cosa, dobbiamo dire a Copilot che la documentazione non è opzionale e dove si trova. Crea (o aggiorna) il file .github/copilot-instructions.md nella root:

# Documentation Rules
- Every time a public API, environment variable, or architectural component is modified, the documentation must be updated.
- ROOT/README.md: Technical overview and setup instructions.
- ROOT/doc/: Architectural decisions and deep dives.
- ROOT/doc/manual/: End-user functionality.
- Formatting: Use GitHub Flavored Markdown.
- Language: Italian for reasoning, English for code/technical terms.

2. Creare un Prompt File per il Sync (.prompt)

Invece di scrivere ogni volta lunghe istruzioni in chat, creiamo un template di “Sync”. Crea un file chiamato .github/prompts/sync-docs.prompt:

---
title: Sync Documentation
description: Analizza le modifiche recenti al codice e aggiorna README e Manuale.
---

Act as a Technical Writer and Architect.
1. Analyze the changes in the current workspace (git diff or recent commits).
2. If there are new dependencies, update the "Requisiti" section in ROOT/README.md.
3. If there are new features, update the corresponding files in ROOT/doc/manual/.
4. If there is a change in logic, create or update a markdown file in ROOT/doc/ explaining the "Why".
5. Present the changes as a diff so I can review them before applying.

Context: #workspace

Come usarlo: Nella chat di VS Code, ti basterà scrivere / (se configurato) o richiamare il prompt file per avviare la procedura di scansione e aggiornamento.

3. Utilizzare gli Hooks (Automazione Proattiva)

Questa è la parte più avanzata. Gli Hooks possono essere configurati per attivarsi in determinati momenti.

Opzione A: VS Code Task (Semi-automatico)

Puoi creare un task in .vscode/tasks.json che interroga Copilot tramite CLI o script per verificare se la documentazione è allineata.

Opzione B: Git Pre-Commit Hook (Consigliato per un Architect)

Puoi usare uno script di pre-commit che “chiede” a Copilot (tramite gh copilot CLI se installata) di verificare se i cambiamenti nel codice riflettono cambiamenti nei file .md.

Se non vuoi usare la CLI, puoi simulare un “Human-in-the-loop Hook”:

1. Configura una Skill o un Custom Agent chiamato @doc-check.
2. Prima di ogni commit importante, scrivi: @doc-check check sync. L’agente confronterà lo stage di git con la cartella doc/.

4. Sfruttare l’MCP Server (Model Context Protocol)

Se la tua documentazione è molto vasta, Copilot potrebbe perdere pezzi di contesto. Qui entra in gioco l’MCP Server.

• L’idea: Configura un MCP server di tipo “Filesystem” o “Search” puntato sulla tua cartella doc/.
• Vantaggio: Quando chiedi a Copilot di aggiornare il manuale, lui non leggerà solo i file aperti, ma userà l’MCP per indicizzare l’intera cartella manual/, trovando esattamente il paragrafo che deve essere aggiornato senza che tu debba dirgli quale file aprire.

5. Configurazione del Workflow “Architect”

Ecco come dovresti operare quotidianamente per massimizzare l’abbonamento Pro+:

1. Modifica al codice: Finisci una feature.
2. Trigger: Apri la chat e scrivi @workspace /sync-docs (usando il prompt file creato al punto 2).
3. Review: Copilot ti proporrà le modifiche per il README.md e per i file in doc/manual/.
4. Apply: Accetta le modifiche.
5. Commit: Fai un unico commit che include code + docs.

Il consiglio dell’esperto (Refactoring della Documentazione)

Se un file del manuale supera le 500 righe, chiedi a Copilot di usare la sua Skill di scomposizione:

"@workspace split ROOT/doc/manual/guide.md into sub-modules by feature and update the table of contents."

Questo mantiene la documentazione modulare proprio come il tuo codice C++/Python.