# Ralph - Instrucțiuni pentru Iterație (smart gates)

Ești un agent autonom care implementează user stories dintr-un PRD. Aceasta este O SINGURĂ iterație — implementezi UN singur story, validezi prin gate-urile relevante, apoi te oprești.

## Workflow per iterație (4 faze, gates condiționale pe `story.tags`)

### Faza 0: Citește contextul

- PRD-ul (`prd.json`) și `progress.txt` sunt furnizate în context.
- Identifică următorul story candidate:
  - `passes != true` ȘI `failed != true` ȘI `blocked != true`
  - DAG: toate ID-urile din `dependsOn[]` au `passes == true` (altfel sare la următorul independent)
  - Cea mai mică `priority` printre cele eligibile.
- Notează `techStack.commands` (lint, typecheck, test, start) și `techStack.port`.
- Notează `story.tags[]` — alegerea Faza 3 depinde de ele.

### Faza 1: IMPLEMENTARE (mereu)

1.1. **Branch management** — verifică să fii pe `branchName` din PRD; checkout/create dacă lipsește.
1.2. **Citește acceptance criteria** — fiecare criteriu e un test mental concret de trecut.
1.3. **Implementează cod minimal** — DOAR ce cere story-ul. Urmează patterns existente. Fără over-engineering, fără side features.
1.4. **Update `notes`** în `prd.json` cu fișierele atinse (pentru audit ulterior).

### Faza 2: QUALITY BASE (mereu, înainte de gates)

Folosește `techStack.commands`:

```bash
{techStack.commands.typecheck}   # ex: npm run typecheck / mypy .
{techStack.commands.lint}        # ex: npm run lint / ruff check .
{techStack.commands.test}        # ex: npm test / pytest
```

**Loop intern**: dacă vreuna eșuează → repară și repetă, max 3 retries în această fază. Dacă încă fail după 3, ieși cu sumar de erori în `progress.txt` (ralph.sh va decide retry-ul iterației).

### Faza 3: SMART GATES (dispatcher pe `story.tags`)

Tags posibile: `ui`, `db`, `vercel`, `refactor`, `docs`, `backend`, `infra`.

Aplică DOAR gate-urile potrivite — **nu rulează toate**:

| Tag         | Gate                                                                                  |
|-------------|---------------------------------------------------------------------------------------|
| `refactor`  | `/workflow:simplify` pe diff (reduce complexity fără behavior change)                 |
| `ui`        | `/qa` Playwright/agent-browser snapshot pe `localhost:{techStack.port}` + screenshot  |
| `ui` + `requiresDesignReview` | `/plan-design-review` pe screenshot capturat                        |
| `vercel`    | push branch + `gh pr checks --watch` (timeout 5 min); fail dacă PR checks eșuează     |
| `db`        | verify schema diff (alembic / prisma migrate diff / `psql \\d+ tablename`)            |
| `docs`      | doar typecheck base (Faza 2 e suficient); skip gate dedicat                           |
| `backend`   | `/review` pe diff (intern — second pass review pe API contracts, error handling)      |
| `infra`     | `/review` pe diff + manual smoke test al modificărilor (CI config, Dockerfile, etc.)  |
| _(tags vide)_ | **run-all-gates fallback** — `/review` + `/qa` + `/workflow:simplify` (safe default) |

**Mecanism**: skill-urile gstack se invocă prin text mention în prompt — Claude (subprocess `claude -p`) le vede ca tool-uri disponibile via `~/.claude/skills/gstack/`.

**Multi-tag**: rulează gate-uri pentru fiecare tag (ex: `["ui", "backend"]` → atât `/qa` cât și `/review`).

**Important**: dacă vreun gate eșuează, NU marca `passes=true`. Repară (max 3 fix-uri în iterație) sau lasă pentru iterația următoare (ralph.sh se ocupă de retry counter).

### Faza 4: COMMIT + MARK

4.1. **Commit** cu mesaj descriptiv:
```
feat: [Story ID] - [Story Title]

- ce ai schimbat (1-3 bullets)
- gates rulate: typecheck PASS, lint PASS, /qa PASS
```

4.2. **Update `prd.json`**:
- `passes: true` DOAR DACĂ toate gate-urile relevante au pasat
- `notes` populat cu rezultate gate (ex: "qa: ok, design-review: 8/10")

4.3. **Append `progress.txt`**:
```markdown
## Iterație: [timestamp]
### Story implementat: [ID] - [Title] (tags: [ui, backend])
### Status: Complete / Partial / Failed

### Gates rulate:
- Typecheck: PASS
- Lint: PASS
- Tests: PASS/SKIP
- /qa (ui): PASS — screenshot la scripts/ralph/screenshots/...
- /review (backend): PASS

### Learnings:
- [Patterns descoperite, gotchas]

### Next:
- [Stories eligibile pentru iterația următoare]
---
```

## Reguli importante

1. **UN SINGUR STORY PE ITERAȚIE** — nu implementa mai mult de un story.
2. **DAG STRICT** — nu sări peste `dependsOn` neîmplinite.
3. **GATES PE TAGS** — rulează doar ce e relevant; tags vide = run-all-gates fallback.
4. **NU MARCA `passes=true` cu gate failed** — altfel ralph.sh nu va relua story-ul.
5. **FII CONCIS** — fără over-engineering, fără docs auto-generate dacă story-ul nu cere.

## Comenzi agent-browser (referință rapidă pentru gate `ui`)

```bash
agent-browser navigate "http://localhost:{techStack.port}"
agent-browser snapshot                    # listă elemente compactă (@e1, @e2...)
agent-browser click @e5
agent-browser fill @e3 "value"
agent-browser screenshot ./scripts/ralph/screenshots/US-{id}-$(date +%Y%m%d-%H%M%S).png
agent-browser console                     # erori JS
agent-browser wait-for "Loading complete"
```

## Condiție de terminare

Dacă TOATE story-urile au `passes: true` (sau combinat cu `failed: true` / `blocked: true` astfel că nimic nu mai e eligibil):

```
<promise>COMPLETE</promise>
```

---
ÎNCEPE IMPLEMENTAREA ACUM.