From 8d6bdef57ea4e15d907bdbe50b2b7ba4c3e5cb5d Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Sun, 3 May 2026 17:09:39 +0200 Subject: [PATCH] docs(runbook): agent-flow open issues & decision log Bundelt vier valkuilen in de huidige agent-flow: PBI-ordering, schema-conflicten bij parallelle migraties, branch-naam-collisies via 8-char suffix, cross-product orchestratie. Eerste is al gedekt door de merge-policy PBI; de andere drie zijn entries onder anchor-PBI "Agent-flow: openstaande beslissingen" (prio 4). Lokaal commit; PR pas wanneer er meer aanverwante docs-changes zijn. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/INDEX.md | 1 + docs/runbooks/agent-flow-pitfalls.md | 83 ++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 docs/runbooks/agent-flow-pitfalls.md diff --git a/docs/INDEX.md b/docs/INDEX.md index 8441cfd..3f6bd26 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -97,6 +97,7 @@ Auto-generated on 2026-05-03 from front-matter and headings. | [DevPlanner — Product Backlog](./product-backlog.md) | `product-backlog.md` | active | 2026-05-03 | | [Scrum4Me — API Test Plan](./qa/api-test-plan.md) | `qa/api-test-plan.md` | active | 2026-05-03 | | [Realtime smoke-checklist — PBI / Story / Task](./realtime-smoke.md) | `realtime-smoke.md` | active | 2026-05-03 | +| [Agent-flow: open issues & decision log](./runbooks/agent-flow-pitfalls.md) | `runbooks/agent-flow-pitfalls.md` | active | 2026-05-03 | | [Branch, PR & Commit Strategy](./runbooks/branch-and-commit.md) | `runbooks/branch-and-commit.md` | active | 2026-05-03 | | [Vercel Deployment](./runbooks/deploy-vercel.md) | `runbooks/deploy-vercel.md` | active | 2026-05-03 | | [MCP Integration — Scrum4Me Tools](./runbooks/mcp-integration.md) | `runbooks/mcp-integration.md` | active | 2026-05-03 | diff --git a/docs/runbooks/agent-flow-pitfalls.md b/docs/runbooks/agent-flow-pitfalls.md new file mode 100644 index 0000000..fb54597 --- /dev/null +++ b/docs/runbooks/agent-flow-pitfalls.md @@ -0,0 +1,83 @@ +--- +title: "Agent-flow: open issues & decision log" +status: active +audience: [ai-agent, contributor, pb-owner] +language: nl +last_updated: 2026-05-03 +when_to_read: "When designing or auditing how the agent claims jobs and produces PRs across multiple stories, PBIs or products." +--- + +# Agent-flow: open issues & decision log + +Deze runbook bundelt vier valkuilen in de huidige agent-flow waarover later +een bewuste beslissing moet vallen. Elk issue is óf gedekt door een +bestaande PBI óf gekoppeld aan een story onder de anchor-PBI +[`Agent-flow: openstaande beslissingen`][anchor-pbi]. + +Status per issue is een van: `open` (nog geen besluit), `decided` (besluit +genomen, mitigatie volgt), `mitigated` (geïmplementeerd; story gesloten). +Promote een story naar een eigen prio-2 PBI zodra het issue acuut wordt. + +## 1. PBI-ordering binnen één batch — `decided` + +**Probleem**: in één batch kunnen jobs uit verschillende PBIs door elkaar +lopen, omdat `wait_for_job` FIFO claimt zonder PBI-grouping. + +**Status**: gedekt door PBI [`Agent merge-policy: geen auto-merge, +sequentieel per PBI`][merge-policy-pbi]. Daar wordt een gate ingebouwd +die voorkomt dat PBI B start zolang PBI A's PR nog open is. + +**Niet hier dupliceren**. + +## 2. Schema-conflict bij parallelle Prisma-migraties — `open` + +**Probleem**: twee stories die elk een Prisma-migratie toevoegen krijgen +elk een eigen migration-file met eigen timestamp. Mergen in willekeurige +volgorde kan de schema-state inconsistent maken; oudere timestamps die +ná nieuwere mergen geven Prisma-onverklaarbaar gedrag. + +**Mitigatie-opties**: sequential-gating (#1 lost dit grotendeels op), +migration-rename CI-hook, geen agent-migrations toelaten, of +`prisma migrate diff` als CI-gate. + +→ [Story `Schema-conflict tussen parallelle stories`][story-schema] + +## 3. Branch naam-collisie via 8-char-suffix — `open` + +**Probleem**: `feat/story-` is geen garantie tegen +botsingen. Met genoeg stories wordt botskans niet-triviaal en de +worktree-create faalt of vermengt commits. + +**Mitigatie-opties**: volledige cuid in branchnaam, `Story.code` als +branchnaam (bv. `feat/ST-1115`), suffix-lengte verhogen, of niets doen +en monitoren. + +→ [Story `Branch naam-collisie via 8-char-suffix van story-id`][story-branch] + +## 4. Cross-product orchestratie — `open` + +**Probleem**: een feature in twee producten (bv. tool in scrum4me-mcp + +gebruik in Scrum4Me) heeft een dependency-volgorde die niet door het +systeem wordt afgedwongen. Mergen in verkeerde volgorde breekt main. + +**Mitigatie-opties**: mens-discipline + description-flag, +Initiative-laag boven PBI (ADR-0010 optie C), gating per repo-pair, of +"blocked-by"-tekstuele link. + +→ [Story `Cross-product orchestratie: dependency-volgorde en +mens-tussenstappen`][story-cross-product] + +## Re-visit cadans + +Bekijk dit document maandelijks of na elke significant agent-incident. +Promote een story naar prio 2 zodra het issue concreet pijn doet. + +## Gerelateerde ADRs + +- [ADR-0010: Eén product = één repo; cross-product planning](../adr/0010-product-per-repo-cross-product-planning.md) + +[anchor-pbi]: # "PBI cmopwlxgu0016vt170ratrrur op product Scrum4Me" +[merge-policy-pbi]: # "PBI cmoppwpwu000evt17ev2c4oo4 op product Scrum4Me" +[story-schema]: # "Story cmopwmc0f0017vt17azn2aynr" +[story-branch]: # "Story cmopwmqcf0018vt17583a25q2" +[story-cross-product]: # "Story cmopwn5mc0019vt17wwrq0ib7"