siae-writing-plans

name	siae-writing-plans
description	Use when transforming an approved design doc into a step-by-step implementation plan with bite-sized tasks. Produces docs/plans/<topic>/ directory with overview + task-NN files. Examples: "scrivi piano implementativo", "decomponi design in task", "trasforma design in piano", "piano bite-sized", "aggiorna piano", "task implementativi", "docs/plans/".
validates_via	{"predicate":"plan_produced","evidence_type":"file_exists","evidence_check":"docs/plans/<topic>/overview.md exists with task-NN files AND [PENDING]/[DONE] markers"}

SIAE Writing Plans — Da Design a Piano Implementativo

LA LEGGE DI FERRO

NESSUN PIANO SENZA DESIGN APPROVATO — NESSUN TASK CON PLACEHOLDER

Tipo: Rigid | Fase SDLC: 2. Design (output)

📊 Dai repo itsiae: piani con > 13 task hanno 3x piu' probabilita' di essere abbandonati a meta'. Decomposizione bite-sized e' critica. Fonte: analisi dei repository GitHub dell'org itsiae.

HARD-GATE

NON scrivere il piano senza un design approvato. Se non esiste un design doc validato dall'utente in `docs/plans/`, torna a `siae-brainstorming` prima.

• Esiste un design doc approvato? NO → FERMATI. Torna a siae-brainstorming.
• SI → procedi con la decomposizione in task.

Un piano senza design = assunzioni non esaminate = lavoro da rifare. Un piano con step vaghi ("aggiungi la validazione") = un piano che fallira'.

---

Quando si applica

Invocata da siae-brainstorming dopo l'approvazione del design (Step 6).

Invocata direttamente quando:

• Hai un design doc gia' approvato e devi produrre il piano
• Devi aggiornare/rivedere un piano esistente dopo feedback
• Hai una spec/requisiti e il design e' implicito o semplice

NON usare quando:

• Il design non e' ancora stato approvato (prima siae-brainstorming)
• Il piano esiste ed e' gia' valido — non riscriverlo senza motivo

---

Processo

1. Leggi design doc approvato in docs/plans/YYYY-MM-DD-*-design.md — identifica goal, scope, componenti, stack, criteri di accettazione, dipendenze.
2. Decomponi in task atomici 2-5 minuti — ogni task atomico, TDD, verificabile, eseguibile da subagent con contesto fresco. Template completo (overview.md + task-NN format + regole di qualita' + anti-pattern): reference/writing-plans-task-template.md.
3. Scrivi il piano come directory docs/plans/<topic>/ con overview.md (header + indice task con stato [PENDING]) + un file task-NN-<nome>.md per task. Vedi template per il formato esatto.
4. Step 3b — Placeholder scan (gate inline, sotto)
5. Step 3c — Plan review (gate inline, sotto)
6. Salva + commit + execution handoff — vedi reference/writing-plans-execution-handoff.md.

---

Step 3b — Placeholder Scan (Gate Obbligatorio, INLINE)

Prima di salvare il piano, scan completo per placeholder e riferimenti vaghi. Un piano con placeholder e' un piano che fallira'.

Pattern vietati — il piano NON e' pronto se contiene:

Pattern	Esempio
TBD	"Formato TBD"
TODO	"TODO: definire schema"
da definire	"Endpoint da definire"
da decidere	"Approccio da decidere"
similar to / simile a	"Simile al Task 2"
come sopra / vedi sopra	"Come sopra ma per utenti"
da completare	"Implementazione da completare"
[...] / ... in codice	function validate(...) { ... }
Riferimenti circolari	"Vedi Task N" senza contenuto inline

Procedura:

1. Scansiona ogni task-NN-*.md per i pattern sopra.
2. Se trovi match → lista i match con file e riga.
3. Risolvi OGNI placeholder con contenuto concreto (path, codice, comando).
4. Ri-scansiona fino a zero match.
5. Solo allora procedi a Step 3c.
6. Emetti checkpoint:

[WRITING-PLANS:PLACEHOLDER-SCAN] Scan completato
  File scansionati: {N}
  Pattern trovati: {0 = PASS / N = FAIL}
  Iterazioni: {N}

Un piano che passa questo gate ha zero ambiguita' per il subagent.

---

Step 3c — Plan Review (Gate Obbligatorio, INLINE)

Dopo il placeholder scan (pattern testuali), lancia un subagent plan-reviewer che verifica la qualita' semantica del piano.

Differenza col placeholder scan (Step 3b):

• Step 3b: pattern matching testuale (TBD, TODO, ...)
• Step 3c: verifica semantica (path validi, codice completo, coerenza col design)

Processo:

1. Lancia subagent con il prompt in plan-reviewer-prompt.md passando {plan_directory} e {design_doc_path}.
2. Il reviewer analizza ogni task-NN-*.md singolarmente (chunk-by-chunk).
3. Leggi il report del reviewer.
4. Se ci sono issue BLOCK: a. Fixa le issue nei task file. b. Ri-lancia il reviewer (loop max 5 iterazioni). c. Se dopo 5 iterazioni ci sono ancora BLOCK → escalation all'utente.
5. Se ci sono solo WARN (zero BLOCK): presenta i WARN all'utente.
6. Se zero issue: procedi a Step 4 (salva + commit).

Checkpoint:

[WRITING-PLANS:PLAN-REVIEW] Plan review completata
  Task reviewati: {N}
  Issue: {N BLOCK / N WARN}
  Iterazioni: {N}/5
  DECISIONE: {APPROVED / REVISE}

---

Salva e committa il piano

🟡 MEDIO — Mostra pre-flight card prima del commit.

🟡 MEDIO (reversibile) — 🔨 DevForge · siae-writing-plans
📋 Piano: docs/plans/<topic>/ · 🔢 Task: <N> task definiti
▼ Azione
1. 📌 Commit piano implementativo → docs/plans/<topic>/
💡 Perche': piano validato (Step 3b + 3c), pronto per commit
🚫 Se NO: il piano resta non committato

git add docs/plans/<topic>/
git commit -m "docs(plans): aggiungi piano implementativo per <feature>"

Per execution handoff (Subagent stessa sessione vs Sessione separata) vedi reference/writing-plans-execution-handoff.md.

---

REQUIRED SUB-SKILL

REQUIRED SUB-SKILL: siae-verification

Verifica che il piano sia coerente col design doc prima di committare.

REQUIRED SUB-SKILL: siae-subagent-development

Per execution dei task nella stessa sessione (handoff opzione 1).

REQUIRED SUB-SKILL: siae-executing-plans

Per execution dei task in sessione separata (handoff opzione 2).

---

Classificazione rischio operazioni

Operazione	Livello	Card
Lettura design doc	🟢 Sicuro	No
Scrittura piano su file	🟢 Sicuro	No
Git commit piano	🟡 Medio	Si
Execution handoff → subagent	🟡 Medio	Si (in siae-subagent-development)

---

Reference

• reference/writing-plans-task-template.md — overview.md + task-NN template, regole di qualita', anti-pattern, retrocompatibilita' file unico
• reference/writing-plans-execution-handoff.md — opzione 1 (subagent) vs opzione 2 (sessione separata), criteri di scelta, permission denied handling
• plan-reviewer-prompt.md — prompt subagent plan-reviewer per Step 3c

Guardrail operativi (centralizzati)

• Classificazione Rischio Operazioni: vedi lib/risk-taxonomy.md (tassonomia comune DevForge).
• Tabella Anti-Razionalizzazione: vedi lib/risk-taxonomy.md + lib/permission-denied-handling.md; regola locale: nessuna scorciatoia "solo questa volta" — se un gate blocca, il fix è soddisfarlo, non aggirarlo.