Workflow PAUL

Ce este PAUL?

PAUL este acronimul pentru Plan-Apply-Unify Loop. Fiecare task non-trivial trece prin aceste trei faze obligatorii. Nu e optional — e o constrangere de workflow.

Faza 1: PLAN

Inainte de orice linie de cod, agentul trebuie sa:

1. Inteleaga complet requirement-ul — citeste codul existent, verifica STATE.md, revizuieste testele
2. Creeze un plan executabil unde fiecare task specifica 4 elemente:

Planurile au max 2-3 task-uri. De ce? Principiul GSD: un context window proaspat ar trebui sa consume ~50% pe executie, nu pe intelegerea planului.

Exemplu real — Phase 001

Uite cum arata un PLAN.md real din acest proiect:

# Phase 001 — PAUL Loop Demonstration

## Task 1: Scrie testul (TDD — red phase)
- Fisiere: tests/test_validate_structure.sh
- Actiune: Scrie test care ruleaza validate-structure.sh
- Verificare: Testul TREBUIE sa FAIL (scriptul nu exista)
- Done: Test exista, ruleaza, si esueaza cu eroare clara

## Task 2: Scrie codul minimal (TDD — green phase)
- Fisiere: validate-structure.sh
- Actiune: Script care verifica 33 componente v2.1
- Verificare: Ruleaza testul — trebuie sa treaca
- Done: Test trece, scriptul raporteaza corect

## Task 3: Atomic commit
- Fisiere: validate-structure.sh, tests/
- Actiune: git add + git commit conventional
- Verificare: git log arata commit-ul
- Done: Commit curat in istoric

Faza 2: APPLY

Executia propriu-zisa, cu disciplina TDD:

1. Executa task-urile secvential cu verificare dupa fiecare
2. Pentru cod: scrie test failing → confirma fail → scrie cod minimal → confirma pass
3. Daca un test trece la prima scriere, testul e probabil gresit — verifica ca prinde esecuri reale
4. Dupa 3 incercari esuate de fix → stop → revizuire arhitecturala → reconsidera
5. Fiecare task completat → atomic git commit

Faza 3: UNIFY

Cea mai importanta si cea mai des sarita faza. UNIFY este mandatory — nu sari niciodata aceasta faza.

1. Reconciliaza — am atins ce era planificat?
2. Actualizeaza STATE.md cu pozitia curenta
3. Ruleaza full test suite — verifica zero regresii
4. Daca ceva e incomplet → creeaza un PLAN nou pentru lucrarile ramase
5. Actualizeaza ROADMAP.md cu progresul
6. Ruleaza /obsidian:sync pentru a sincroniza sesiunea in vault

Exemplu real — SUMMARY.md din Phase 001

## Ce s-a facut
1. PLAN: Creat plan executabil cu 3 task-uri
2. APPLY:
   - TDD RED: Scris test care esueaza
   - TDD GREEN: Scris validate-structure.sh (33 checks)
   - Bug fix: ((PASS++)) returneaza exit 1 in bash
   - Bug fix: set -e + command substitution
3. UNIFY: STATE.md actualizat, ROADMAP marcat, SUMMARY scris

## Lectii invatate
- ((var++)) in bash returneaza exit code 1 cand var=0
- TDD chiar prinde bug-uri: 2 bug-uri gasite prin teste

Loop-ul complet vizual

PLAN   → Scrie .planning/phases/NNN/PLAN.md
         ↓
APPLY  → Executa task-uri cu TDD
         Test FAIL → Cod minimal → Test PASS → Commit
         ↓
UNIFY  → Scrie SUMMARY.md
         Update STATE.md
         Update ROADMAP.md
         Full test suite
         /obsidian:sync
         ↓
       → Repeat (urmatorul task sau urmatoarea faza)

Exercitiu

Deschide .planning/phases/001/PLAN.md si SUMMARY.md. Compara planul cu rezultatul. Observa cum SUMMARY-ul documenta "lectii invatate" — informatii care nu erau in plan dar au aparut din executie.