diff --git a/src/lib/kind-prompts.ts b/src/lib/kind-prompts.ts index f7e03c1..15a7a16 100644 --- a/src/lib/kind-prompts.ts +++ b/src/lib/kind-prompts.ts @@ -25,6 +25,7 @@ function loadPrompt(rel: string): string { const KIND_TO_PROMPT_PATH: Partial> = { IDEA_GRILL: 'idea/grill.md', IDEA_MAKE_PLAN: 'idea/make-plan.md', + IDEA_REVIEW_PLAN: 'idea/review-plan.md', TASK_IMPLEMENTATION: 'task/implementation.md', SPRINT_IMPLEMENTATION: 'sprint/implementation.md', PLAN_CHAT: 'plan-chat/chat.md', @@ -40,9 +41,9 @@ export function getKindPromptText(kind: ClaudeJobKind): string { } // Back-compat re-export. wait-for-job.ts roept getIdeaPromptText aan voor -// de twee idea-kinds; behouden zodat we de bestaande call-site niet hoeven +// de drie idea-kinds; behouden zodat we de bestaande call-site niet hoeven // te wijzigen tot een aparte cleanup-pass. export function getIdeaPromptText(kind: ClaudeJobKind): string { - if (kind !== 'IDEA_GRILL' && kind !== 'IDEA_MAKE_PLAN') return '' + if (kind !== 'IDEA_GRILL' && kind !== 'IDEA_MAKE_PLAN' && kind !== 'IDEA_REVIEW_PLAN') return '' return getKindPromptText(kind) } diff --git a/src/prompts/idea/review-plan.md b/src/prompts/idea/review-plan.md new file mode 100644 index 0000000..8df45f6 --- /dev/null +++ b/src/prompts/idea/review-plan.md @@ -0,0 +1,210 @@ +# 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": "", + "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: , plan_md: }) + ``` + 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": "", + "plan_after": "", + "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`). diff --git a/src/tools/wait-for-job.ts b/src/tools/wait-for-job.ts index 96c11ba..f3e11c0 100644 --- a/src/tools/wait-for-job.ts +++ b/src/tools/wait-for-job.ts @@ -508,7 +508,7 @@ export async function getFullJobContext(jobId: string) { // M12: branch on kind. Idea-jobs hebben geen task/story/pbi/sprint; ze // hebben in plaats daarvan idea + embedded prompt_text. - if (job.kind === 'IDEA_GRILL' || job.kind === 'IDEA_MAKE_PLAN') { + if (job.kind === 'IDEA_GRILL' || job.kind === 'IDEA_MAKE_PLAN' || job.kind === 'IDEA_REVIEW_PLAN') { if (!job.idea) return null const { idea } = job const { getIdeaPromptText } = await import('../lib/kind-prompts.js') @@ -569,7 +569,11 @@ export async function getFullJobContext(jobId: string) { pbi: idea.pbi, repo_url: job.product.repo_url, prompt_text: getIdeaPromptText(job.kind), - branch_suggestion: `feat/idea-${idea.code.toLowerCase()}-${job.kind === 'IDEA_GRILL' ? 'grill' : 'plan'}`, + branch_suggestion: `feat/idea-${idea.code.toLowerCase()}-${(() => { + if (job.kind === 'IDEA_GRILL') return 'grill' + if (job.kind === 'IDEA_REVIEW_PLAN') return 'review' + return 'plan' + })()}`, product_worktrees: worktrees.map((w) => ({ product_id: w.productId, worktree_path: w.worktreePath,