--- name: h2c_compress description: | Comprime un prompt scritto in linguaggio naturale in un blocco H2C equivalente, riducendo il numero di token in input senza perdere informazione semantica. Restituisce: il blocco H2C pronto da copiare, il conteggio token prima/dopo, la percentuale di risparmio, e una verifica di equivalenza semantica. Si attiva quando l'utente dice (IT) "comprimi questo prompt", "comprimi in h2c", "trasforma in h2c", "riduci i token di questo prompt", "h2c compress", "ottimizza questo prompt", "converti il prompt in h2c", "/h2c-compress" oppure (EN) "compress this prompt", "compress to h2c", "convert to h2c", "reduce prompt tokens", "h2c compression". Si attiva anche quando l'utente incolla un prompt e dice "questo lo voglio in h2c" o esprime l'intento di ridurre i token di un prompt che riutilizzerà. NON usare per: comprimere risposte/output del modello (l'output deve restare leggibile), comprimere conversazioni (usa /compact del modello), gestire catene di agenti H2C runtime (usa skills/h2c_orchestrator.md del repo). --- # h2c_compress — compressione prompt NL → H2C Obiettivo: prendere un prompt in linguaggio naturale e restituire il blocco H2C equivalente, che l'utente possa usare al posto del prompt originale per ridurre i token in input nelle esecuzioni successive. ## Quando attivare L'utente ha un prompt scritto (lo incolla nel messaggio o ne descrive il contenuto) e chiede esplicitamente di "comprimerlo", "ridurlo a H2C", "ottimizzarlo per token", o equivalenti. Se il prompt non è incollato e non è chiaro quale prompt comprimere, chiedere una volta sola di incollarlo, poi procedere. ## Flusso operativo 1. **Identifica il tipo di richiesta** nel prompt NL e scegli il blocco H2C target dalla grammatica v1.2 (vedi `SPEC.md` se accessibile, altrimenti il repo ufficiale https://github.com/PaoEng/H2C): | Tipo di prompt | Blocco H2C target | |---|---| | "crea un progetto X con Y" (specifiche di build) | `[ARCH:PLAN]` | | "implementa/scrivi codice per Z" | `[BUILD:EXEC]` (se piano già esiste) o `[ARCH:PLAN]` | | "correggi questo errore Y in file Z" | `[BUILD:FIX]` | | "esegui i test del modulo X" | `[TEST:RUN]` | | "analizza la causa di Y e proponi soluzione" | `[STATE:FINDINGS]` | | "stato attuale del progetto X" | `[CTX:PRIMITIVES]` | Se il prompt non rientra in nessun blocco standard (es. brief di meeting, domanda generica, mail), **rifiuta cortesemente la compressione**: H2C è pensato per task di sviluppo software, non per ogni tipo di richiesta. 2. **Estrai i campi obbligatori e opzionali** del blocco target dalla SPEC v1.2. Per ogni campo, mappa la frase in linguaggio naturale al valore compresso: - Identifica slug (`id:`) breve e parlante (kebab-case, no spazi) - Identifica `fw:` (framework/linguaggio), `lib:` (librerie elencate), `auth:` (meccanismo auth), `pattern:` (pattern architetturale), `tools:` (operazioni esposte), `struct:` (lista file), `deps:` (servizi esterni), `notes:` (vincoli importanti come "TTL 10min", "rate-limit 60/min") - Comprimi liste in `[a,b,c]` senza spazi - Sostituisci `|` interni ai valori con `_` o `:` (il `|` è separatore di campi) - Per i `notes:[...]`, condensa frasi in token-words (es. "cache TTL 10 minuti" → `cache_TTL_10min`) 3. **Verifica copertura**: scorri il prompt NL frase per frase e accertati che ogni informazione abbia un campo H2C corrispondente. Se qualcosa non ci sta nei campi standard, mettila in `notes:`. 4. **Output strutturato** verso l'utente, in questo ordine: a. Il **blocco H2C pronto** in code-fence, copia-incollabile: ``` [ARCH:PLAN] id:...|fw:...|lib:...|... ``` b. **Conteggio token** prima/dopo, calcolato eseguendo (via Bash) Python con `tiktoken` (modello `cl100k_base` come proxy realistico). Se tiktoken non è disponibile, fallback a stima `len(text)/3.2`: ```python import tiktoken enc = tiktoken.get_encoding("cl100k_base") nl_tokens = len(enc.encode(prompt_nl)) h2c_tokens = len(enc.encode(prompt_h2c)) ``` c. **Tabella riassuntiva** con: token NL, token H2C, % risparmio, blocco target usato: | Metrica | Prompt NL | Prompt H2C | Δ | |---|---|---|---| | Token | | | **-%** | d. **Verifica di equivalenza semantica**: lista dei campi h2c → frasi del prompt NL coperte, con eventuali warning su informazioni che non hanno mappatura naturale (vanno in `notes:`). e. **Indicazione d'uso**: una riga che spiega come riusare il blocco ("Incolla questo blocco al posto del prompt originale. Qualunque LLM moderno capisce H2C zero-shot."). 5. **Onestà sul risparmio**: spiega che la compressione riduce gli **input token**, non gli output. Su singola esecuzione il risparmio totale è ~5-10%; diventa significativo se il prompt viene riusato N volte. ## Cosa NON fare - Non inventare campi (`fw:`, `lib:`, ecc.) se l'informazione non c'è nel prompt NL. Lascia il campo fuori — la SPEC dichiara cosa è OBBLIGATORIO vs OPZIONALE per ogni blocco. - Non comprimere ulteriormente cambiando il significato. La regola è: "stessa esecuzione, meno token", non "task simile, più corto". - Non aggiungere blocchi di follow-up (BUILD:EXEC, TEST:RUN) — la skill comprime UN prompt, non genera la pipeline a valle. - Non comprimere prompt che non sono task tecnici (chiacchiere, domande, brief di meeting, email): per quelli H2C non porta valore e la compressione perde leggibilità. ## Esempio (dal repo H2C, api-meteo) **Input (NL, ~175 token):** > Crea un progetto per una API meteo sviluppata in Python 3.11 utilizzando > FastAPI. Il progetto deve integrare le librerie FastAPI, httpx in modalità > asincrona e cachetools. L'autenticazione deve avvenire tramite API Key, > letta dalla variabile d'ambiente OPENWEATHER_API_KEY. L'API deve consumare > i dati di OpenWeatherMap. Organizza il progetto seguendo un pattern modulare > basato su router e service. Le funzionalità principali devono essere esposte > come "tools" e includere due operazioni: current e forecast. […] cache in > memoria con TTL pari a 10 minuti e un rate limit di 60 richieste al minuto. **Output (H2C, ~60 token):** ``` [ARCH:PLAN] id:api-meteo|fw:python3.11|lib:fastapi,httpx,cachetools|auth:APIKey::env(OPENWEATHER_API_KEY)|pattern:router,service|tools:[weather:{current,forecast}]|struct:[main.py,routers/weather.py,services/{weather_service.py,cache_service.py},models/weather.py,config.py,.env]|deps:OpenWeatherMap|notes:[cache_TTL_10min,rate-limit_60req-min,httpx_async] ``` **Risparmio: ~65% sull'input.** Equivalenza semantica: 100% (mappatura 1:1 verificata: ogni vincolo del prompt NL ha il suo campo nel blocco H2C). ## Quando dichiarare "non comprimibile" - Prompt < 50 token: il guadagno è minimo, il rumore dell'analisi maggiore - Prompt non tecnico (mail, brief, domanda concettuale): H2C non si applica - Prompt che richiede output creativo (scrittura, traduzione, ragionamento): la struttura H2C non aggiunge valore - Prompt già in H2C: avvisa che è già compresso In questi casi, di' chiaramente "questo prompt non è un buon candidato per H2C compression perché [motivo]", senza forzare una conversione che peggiora le cose.