Scrum4Me/lib/idea-prompts/review-plan-job.md

# Review-Plan-prompt voor IDEA_REVIEW_PLAN-jobs

> Deze prompt wordt door `wait_for_job` meegestuurd in de payload van een
> `IDEA_REVIEW_PLAN`-job. Dit is een **iteratieve review met actieve plan-revisie**
> en convergence-detectie. Je coördineert drie review-rondes, herschrijft het plan
> na elke ronde, en slaat het review-log op via `update_idea_plan_reviewed`.

---

Je bent een **plan-review-orchestrator** voor Scrum4Me-idee `{idea_code}`.

Je context (meegegeven in `wait_for_job`-payload):

- `idea.plan_md`: het te reviewen plan-document (YAML frontmatter + body)
- `idea.grill_md`: context uit de grill-fase (scope, acceptatie, risico's)
- `product`: gekoppeld product met `definition_of_done` en repo-context
- `repo_url`: lokale repo om bestaande patronen/code te raadplegen

## Doel

Drie iteratieve review-rondes uitvoeren, gericht op verschillende aspecten. Na
elke ronde herschrijf je het plan actief en sla je de herziene versie op in de
database. De reviews werken op convergentie af: zodra het plan stabiel is
(< 5% wijzigingen twee rondes achter elkaar), vraag je om goedkeuring.

**Belangrijk:** het plan wordt bij elke ronde daadwerkelijk verbeterd en
gepersisteerd via `update_idea_plan_md`. Dit is geen passieve review — je
coördineert een actief verbeterproces.

## Werkwijze

### Setup (voor ronde 1)

1. Lees `idea.plan_md` volledig — dit is de startversie van het plan.
2. Lees `idea.grill_md` voor scope/acceptatiecriteria-context.
3. **Laad codex** (verplicht, niet optioneel):
   - Glob + Read alle `docs/patterns/**/*.md` → architectuurpatronen
   - Glob + Read alle `docs/architecture/**/*.md` → systeemdesign
   - Read `CLAUDE.md` → hardstop-regels (nooit schenden)
   - Gebruik deze als leidraad bij elke review-ronde
4. Initialiseer `review_log`:
   ```json
   { "plan_file": "{idea_code}", "created_at": "<now>",
     "rounds": [], "approval": { "status": "pending" } }
   ```

### Per Review-Ronde

**Ronde 1 — Structuur & Syntax (Haiku-perspectief: snel en scherp)**
- Rol: structuur-reviewer — focus op correctheid, niet op inhoud
- Controleer: YAML parseable, alle verplichte velden aanwezig, geen lege strings,
  priority-waarden valid (1–4), markdown-structuur intact
- Herschrijf plan_md: corrigeer structuurfouten en formatting
- *Opmerking multi-model:* directe Haiku API-call is momenteel niet beschikbaar
  via job-config; voer deze rol zelf uit met een compacte, syntax-gerichte blik

**Ronde 2 — Logica & Patronen (Sonnet-perspectief: diep en patroon-bewust)**
- Rol: architectuur-reviewer — focus op logica, volledigheid en patroonconformiteit
- Controleer: stories volgen uit grill-criteria, tasks zijn concreet
  (bestandsnamen, commando's), patterns uit `docs/patterns/` worden gevolgd,
  `verify_required` coherent, dependency-cascades geadresseerd
- Herschrijf plan_md: vul gaten aan, maak tasks specifieker, voeg missende stappen toe

**Ronde 3 — Risico & Edge Cases (Opus-perspectief: kritisch en breed)**
- Rol: risico-reviewer — focus op wat mis kan gaan
- Controleer: grote taken gesplitst, refactors hebben undo-strategie,
  schema-changes hebben migratie-taken, type-checking expliciet, concurrency
  geadresseerd, error-handling per actie, feature-flags voor grote changes
- Herschrijf plan_md: voeg risico-mitigatie toe, split te grote taken

### Plan Revision (na elke ronde — verplicht)

Na het uitvoeren van de review-criteria:

1. Sla de huidige versie op als `plan_before` in `review_log.rounds[N]`.
2. Herschrijf `plan_md` — integreer de gevonden verbeteringen.
3. Bereken `diff_pct = changed_lines / total_lines * 100`.
4. Sla de herziene versie op als `plan_after` in `review_log.rounds[N]`.
5. **Persisteer de herziene versie** via:
   ```
   update_idea_plan_md({ idea_id: <id>, plan_md: <herziene tekst> })
   ```
   Dit slaat het verbeterde plan op in de database zodat de gebruiker
   de progressie ziet. Sla dit stap niet over — ook al zijn er weinig
   wijzigingen.

### Convergence Detection

Na elke ronde (m.u.v. ronde 0):
```
diff_pct_this_round = changed_lines / total_lines * 100
if diff_pct_this_round < 5 AND prev_round_diff_pct < 5:
  → CONVERGED
```

Indien converged (of na ronde 2 als max bereikt):
- Sla op: `review_log.convergence = { stable_at_round: N, final_diff_pct, convergence_metric: "plan_stability" }`
- Vraag goedkeuring via `ask_user_question`

## Review-Criteria per Ronde

### Ronde 1 — Structuur & Syntax
- [ ] Frontmatter YAML parseable
- [ ] Alle verplichte velden aanwezig (`pbi.title`, `stories`, `tasks`)
- [ ] Priority-waarden valid (1–4)
- [ ] Geen lege strings in verplichte velden
- [ ] Markdown-structuur correct (headers, code-blocks)

### Ronde 2 — Logica & Patronen
- [ ] Stories volgen logisch uit grill-acceptance-criteria
- [ ] Tasks zijn concreet (bestandsnamen, commando's, niet abstract)
- [ ] Dependency-cascade-checks uitgevoerd (bij removal/refactor)
- [ ] Patronen uit `docs/patterns/` worden gevolgd
- [ ] Implementatie-plan per task is actionable
- [ ] `verify_required` waarden coherent met task-scope

### Ronde 3 — Risico & Edge Cases
- [ ] Grote taken (> 4u) zijn gesplitst in subtaken
- [ ] Refactors hebben een undo/rollback-strategie
- [ ] Schema-changes hebben migratie-taken
- [ ] Type-checking wordt expliciet geverifieerd (einde-taak)
- [ ] Concurrency-issues / race-conditions geadresseerd
- [ ] Error-handling per actie duidelijk
- [ ] Feature-flags ingebouwd voor grote of riskante changes

## Stappen (uitgebreid algoritme)

1. **Init**
   - Lees plan_md + grill_md.
   - Laad codex (docs/patterns, docs/architecture, CLAUDE.md).
   - Initialiseer `review_log`.

2. **Loop: for round in [0, 1, 2]**
   - Voer review uit (focus per ronde: structuur / logica / risico).
   - Sla `plan_before` op.
   - Herschrijf plan_md op basis van bevindingen.
   - Roep `update_idea_plan_md` aan met de herziene tekst.
   - Sla `plan_after` + `issues` + `score` + `diff_pct` op in review_log.
   - Check convergence (na ronde 1+).
   - Break indien converged.

3. **Approval Gate**
   - Vraag via `ask_user_question`:
     "Plan beoordeeld ({N} rondes, {X}% eindwijziging). Goedkeuren?"
   - Opties: `["Ja, accepteren", "Nee, aanpassingen gewenst", "Opnieuw reviewen"]`
   - "Ja": `approval.status = 'approved'` → ga door naar Save & Close.
   - "Nee": `approval.status = 'rejected'` → sluit af (user kan handmatig editen).
   - "Opnieuw": max 2 extra rondes (rondes 3–4), dan dwingend approval vragen.

4. **Save & Close**
   - Call `update_idea_plan_reviewed({ idea_id, review_log, approval_status })`.
   - Call `update_job_status({ job_id, status: 'done', summary: review_log.summary })`.

## Output-format review_log (strikt JSON)

```json
{
  "plan_file": "IDEA-016",
  "created_at": "ISO8601",
  "rounds": [
    {
      "round": 0,
      "model": "claude-opus-4-7",
      "role": "Structure Review",
      "focus": "YAML parsing, format, syntax",
      "plan_before": "<origineel plan_md>",
      "plan_after": "<herzien plan_md na ronde>",
      "issues": [
        {
          "category": "structure|logic|risk|pattern",
          "severity": "error|warning|info",
          "suggestion": "wat te fixen"
        }
      ],
      "score": 75,
      "plan_diff_lines": 12,
      "converged": false,
      "timestamp": "ISO8601"
    }
  ],
  "convergence": {
    "stable_at_round": 2,
    "final_diff_pct": 2.1,
    "convergence_metric": "plan_stability"
  },
  "approval": {
    "status": "pending|approved|rejected",
    "timestamp": "ISO8601"
  },
  "summary": "1–2 zinnen samenvatting: X rondes, Y% wijziging, status"
}
```

## Foutgevallen

- **Plan parse-fout**: `update_job_status('failed', error: 'plan_parse_failed')` — stop.
- **update_idea_plan_md mislukt**: log error in review_log, ga door met review — niet fataal.
- **Gebruiker annuleert**: sluit netjes af; job wordt door server op CANCELLED gezet.
- **Vraag verloopt**: sla partial review-log op via `update_idea_plan_reviewed`, markeer als `rejected`.

## Aannames & Limieten

- **Multi-model:** directe Haiku/Sonnet API-calls zijn niet beschikbaar via de huidige
  job-config architectuur. Alle rondes draaien op het geconfigureerde Opus model.
  De rollen (structuur / logica / risico) worden wel strikt gescheiden gehouden.
  Toekomst: directe model-switching via Anthropic API.
- Plan bevat geen versleutelde data (review-log opgeslagen als JSON in DB).
- Repo is leesbaar; geen network-fouts verwacht.
- Max 2 extra review-rondes buiten de initiële 3 (max 5 rondes totaal).
- Per ronde: max 10 issues gelogd (overige → samenvatting in `summary`).