diff --git a/docs/plans/docs-restructure-ai-lookup.md b/docs/plans/docs-restructure-ai-lookup.md new file mode 100644 index 0000000..543473d --- /dev/null +++ b/docs/plans/docs-restructure-ai-lookup.md @@ -0,0 +1,499 @@ +--- +title: Docs-restructuur — geoptimaliseerd voor AI-lookup +status: proposal +audience: maintainer, ai-agent +language: nl +last_updated: 2026-05-02 +related: + - CLAUDE.md + - AGENTS.md + - README.md + - docs/agent-instruction-audit.md +--- + +# Plan — Docs-restructuur voor AI-lookup + +> Doel van dit plan: de huidige documentatie- en instructielaag van Scrum4Me omzetten naar een structuur die een AI-agent (Claude Code, Codex, een MCP-worker) in zo min mogelijk tokens en tool-calls het juiste document laat vinden, lezen en toepassen — zonder dat de mens-leesbaarheid eronder lijdt. + +Dit is een **proposal**, niet een afgerond ontwerp. Lees het, markeer wat je niet wil, en ik werk het uit naar een uitvoerbaar migratieplan met file-per-file diff. + +--- + +## 1. Waarom dit plan + +Een AI-agent doet voor élke beslissing typisch dit: + +1. Leest `CLAUDE.md` (of `AGENTS.md`) volledig in context. +2. Scant `docs/` met `ls`/`grep`/`glob` om relevante bestanden te kiezen. +3. Leest één of meerdere docs volledig — vaak meer dan nodig, omdat doc-grenzen vaag zijn. +4. Vindt cross-refs (`zie docs/X#Y`) en herhaalt stap 3. + +Elke stap kost tokens en latency. Als de bestandsboom, naamgeving of inhoud onduidelijk is, leest de agent te veel of het verkeerde — en maakt vervolgens beslissingen op verouderde of irrelevante informatie. + +**Concrete kosten in deze repo (gemeten 2026-05-02):** + +| Plek | Bestanden | Regels totaal | Grootste bestand | +|---|---:|---:|---| +| Root (CLAUDE.md, README.md, AGENTS.md, Brainstorm.md) | 4 | 679 | CLAUDE.md (340) | +| `docs/` (root, exclusief subdirs) | 13 | 5.873 | scrum4me-architecture.md (1.247) | +| `docs/patterns/` | 11 | 1.013 | dialog.md (387) | +| `docs/plans/` | 8 | 2.121 | M10-qr-pairing-login.md (885) | +| `.Plans/` (parallelle plan-historie) | 3 | ~600 | — | +| **Totaal** | **39** | **~10.700** | — | + +Bij elke turn die met `CLAUDE.md` start, wordt minimaal 340 regels orientation in de context geladen — vóór er één regel code is gelezen. De agent kan vervolgens uit ~9.000 regels documentatie het juiste fragment moeten kiezen op basis van bestandsnamen alleen, want er is geen front-matter en geen index. + +--- + +## 2. Wat ik aantrof — review per laag + +### 2.1 Root-niveau orientation + +| Bestand | Wat het doet vandaag | Probleem | +|---|---|---| +| `CLAUDE.md` (340 r) | Doel, doc-index, twee start-tracks, tech stack, UI-conventies, patroon-index, env vars, conventies, branch/commit-strategie, scrum-terminologie, MCP, deployment, DoD | Té breed: oriëntatie + harde regels + referentie-tabellen + procedures. Alles wordt elke turn geladen. | +| `AGENTS.md` (38 r) | Codex-variant van CLAUDE.md | Duplicatie: 80% overlapt met CLAUDE.md (access-control, doc-sync, verificatie). Twee waarheden die uit elkaar kunnen lopen. | +| `README.md` (285 r) | Portfolio-pitch, stack, setup, routes, dev-flow | Mensgericht (recruiters, GitHub-bezoekers). Goed dat het bestaat — niet aanraken. | +| `Brainstorm.md` (16 r) | Stukjes Prisma-schema, JSON-snippet en HTML-DOM-dump zonder context | **Dood bestand**, weghalen of verplaatsen naar `docs/scratch/`. | + +### 2.2 `docs/` root + +| Bestand | Regels | Waar het thuishoort | +|---|---:|---| +| `scrum4me-architecture.md` | 1.247 | `docs/architecture/` — splitsen (zie §4) | +| `scrum4me-functional-spec.md` | 650 | `docs/specs/functional.md` | +| `scrum4me-backlog.md` | 751 | `docs/backlog/index.md` | +| `scrum4me-product-backlog.md` | 454 | `docs/backlog/product-historical.md` (referentie, zie noot in CLAUDE.md) | +| `scrum4me-personas.md` | 138 | `docs/specs/personas.md` | +| `scrum4me-styling.md` | 670 | `docs/design/styling.md` | +| `MD3_Color_Scheme_Documentation.md` | 941 | `docs/design/md3-color-scheme.md` (overlapt deels met `styling.md` — kandidaat voor merge) | +| `scrum4me-test-plan.md` | 454 | `docs/qa/api-test-plan.md` | +| `scrum4me-pbi-dialog.md` | 120 | `docs/specs/dialogs/pbi.md` | +| `scrum4me-story-dialog.md` | 163 | `docs/specs/dialogs/story.md` | +| `scrum4me-task-dialog.md` | 127 | `docs/specs/dialogs/task.md` | +| `solo-paneel-spec.md` | 771 | `docs/specs/solo-panel.md` | +| `API.md` | 520 | `docs/api/rest-contract.md` | +| `agent-instruction-audit.md` | 173 | `docs/decisions/agent-instructions.md` (ADR-stijl) | +| `erd.svg`, `icons.html` | — | `docs/assets/` | + +**Patroon dat opvalt:** alles met prefix `scrum4me-` — dat prefix is overbodig, je staat al in `docs/` van de Scrum4Me-repo. Verwijderen scheelt visuele ruis bij `ls`. + +**Inconsistente capitalization:** één bestand `MD3_Color_Scheme_Documentation.md` (snake + UpperCamel), de rest kebab. Eén bestand `API.md` (UPPER), de rest lowercase. + +### 2.3 `docs/patterns/` + +11 patronen, elk 25–390 regels. Goed als concept, maar: + +- `test.md` bevat letterlijk het woord "test" — junkfile, weghalen. +- Geen front-matter; agent moet titel + intro lezen om te weten of het patroon van toepassing is. +- Naamgeving inconsistent: `iron-session.md`, `qr-login.md`, `claude-question-channel.md` — sommige domeinspecifiek, andere generiek. Geen prefix die laat zien of het een **rule** (verplicht), **recipe** (voorbeeldcode) of **explainer** is. + +### 2.4 `docs/plans/` + +- 8 plans. Eén heeft een filename met spaties en em-dash: `Tweede Claude Agent — Planning Agent.md` — breekt grep/glob/git-workflows op sommige shells, en is moeilijk te linken. Omnoemen naar `tweede-claude-agent-planning.md`. +- ST-1109-pbi-status.md verwijst naar `~/.claude/plans/welke-rioriteiten-heeft-een-mighty-shell.md` (ook nog typo "rioriteiten") — externe locatie die niet in de repo zit en die de agent niet kan lezen. +- `MEMORY.md` wordt op meerdere plaatsen genoemd maar bestaat niet in de repo. + +### 2.5 `.Plans/` (root) + +3 historische planfiles uit april 2026, parallel aan `docs/plans/`. Twee waarheden voor "waar staan plannen". Voorstel: archiveren naar `docs/plans/archive/` of weghalen. + +### 2.6 Cross-referenties en dode links + +- CLAUDE.md verwijst naar `docs/scrum4me-architecture.md#demo-user-policy` — die anchor bestaat (regel 1068 `## Demo-user policy (ST-1110)`), dus dit is OK; maar er bestaat geen lint die garandeert dat dit zo blijft als de header verandert. +- ST-1109-pbi-status.md verwijst naar `~/.claude/plans/welke-rioriteiten-heeft-een-mighty-shell.md` — externe locatie buiten de repo, plus typo "rioriteiten". Een agent kan die niet lezen. +- README.md verwijst niet naar CLAUDE.md/AGENTS.md (mensbezoekers vinden de agent-instructie laag niet). +- Geen enkel doc heeft een "Zie ook"-blok aan de onderkant. Cross-navigatie tussen patroon ↔ spec ↔ plan moet de agent zelf reconstrueren. + +### 2.7 Wat er níet is (en zou moeten) + +- **Geen index/manifest.** Een agent die `glob "docs/**/*.md"` doet, krijgt 30+ paden zonder context. +- **Geen front-matter.** Geen status (draft/active/deprecated), audience, last-updated, related. +- **Geen ADR-laag.** Beslissingen zoals "waarom geen Radix maar @base-ui/react", "waarom float sort_order", "waarom one-branch-per-milestone" zitten verstrooid in CLAUDE.md, README en losse plans. Een `docs/decisions/`-folder met ADR-format zou ze vindbaar maken. +- **Geen glossary.** Domeintermen (PBI, Story, Sprint, Solo, Todo, demo-token) zijn alleen impliciet gedefinieerd in de functional spec. +- **Geen "lookup-hints" in de doc-index.** CLAUDE.md zegt *waarvoor* je een doc gebruikt, niet *wanneer je het NIET hoeft te lezen*. + +--- + +## 3. Doelen voor de nieuwe structuur + +In volgorde van belangrijkheid: + +1. **Eén goedkope orientation-laag.** Een agent moet ≤150 regels lezen om te weten waar hij verder moet kijken. +2. **Voorspelbare paden.** `docs//.md` zonder uitzonderingen. +3. **Machine-leesbare metadata.** YAML-front-matter op élk doc met minimaal `status`, `audience`, `last_updated`, `related`. +4. **Per-doc lookup-hint.** Eén zin "Lees dit als …" bovenaan; één zin "Niet hiervoor lezen: …" om verkeerd ophalen te voorkomen. +5. **Splitsing van regels (verplicht) en uitleg (referentie).** Regels in een korte rule-doc; voorbeeldcode en rationale in een aparte recipe/explainer. +6. **Eén bron-van-waarheid per onderwerp.** Geen Codex-vs-Claude-duplicatie; AGENTS.md wordt een 10-regelige verwijzing naar CLAUDE.md. + +--- + +## 4. Voorgestelde doelstructuur + +``` +/ (repo-root) +├── README.md (mens, portfolio — ongewijzigd) +├── CLAUDE.md (agent-orientation, ≤150 regels — zie §5) +├── AGENTS.md (10 regels: "alles in CLAUDE.md geldt ook voor jou") +├── docs/ +│ ├── INDEX.md (NIEUW — manifest met front-matter van alle docs) +│ ├── glossary.md (NIEUW — PBI, Story, Sprint, demo-token, …) +│ │ +│ ├── architecture/ +│ │ ├── overview.md (uit huidige architecture.md §1–§3) +│ │ ├── data-model.md (uit §Datamodel + §Prisma Schema) +│ │ ├── auth-and-sessions.md (uit §Authenticatieflow) +│ │ ├── qr-pairing.md (uit §QR-pairing flow) +│ │ ├── claude-question-channel.md (uit §Vraag-antwoord-kanaal) +│ │ └── project-structure.md (uit §Projectstructuur) +│ │ +│ ├── specs/ +│ │ ├── functional.md (huidige scrum4me-functional-spec.md) +│ │ ├── personas.md +│ │ ├── solo-panel.md +│ │ └── dialogs/ +│ │ ├── pbi.md +│ │ ├── story.md +│ │ └── task.md +│ │ +│ ├── design/ +│ │ ├── styling.md (samengevoegd uit styling + MD3-color) +│ │ └── color-tokens.md (alleen het token-overzicht) +│ │ +│ ├── api/ +│ │ ├── rest-contract.md (huidige API.md) +│ │ └── error-codes.md (afgesplitst — vandaag verspreid) +│ │ +│ ├── patterns/ (RULES — kort en bindend) +│ │ ├── 00-conventions.md (server-action, prisma-client, route-handler — kort) +│ │ ├── dialog.md +│ │ ├── sort-order.md +│ │ ├── zustand-optimistic.md +│ │ ├── iron-session.md +│ │ ├── proxy.md (was middleware.md — nieuwe naam) +│ │ ├── qr-pairing.md +│ │ └── claude-question-channel.md +│ │ +│ ├── recipes/ (NIEUW — uitgewerkte voorbeeldcode bij rules) +│ │ └── … (één recipe per pattern dat code-snippets had) +│ │ +│ ├── runbooks/ (NIEUW — operationele procedures) +│ │ ├── deploy-vercel.md (uit CLAUDE.md §Deployment) +│ │ ├── env-vars.md (uit CLAUDE.md §Env vars + .env.example) +│ │ └── local-dev.md (huidige README §setup, geëxtraheerd) +│ │ +│ ├── decisions/ (NIEUW — ADR-stijl) +│ │ ├── 0001-base-ui-over-radix.md +│ │ ├── 0002-float-sort-order.md +│ │ ├── 0003-one-branch-per-milestone.md +│ │ ├── 0004-status-enum-mapping.md +│ │ └── 0005-agent-instructions.md (was agent-instruction-audit.md) +│ │ +│ ├── backlog/ +│ │ ├── index.md (huidige scrum4me-backlog.md) +│ │ └── product-historical.md (huidige scrum4me-product-backlog.md) +│ │ +│ ├── plans/ +│ │ ├── M9-active-product-backlog.md +│ │ ├── M10-qr-pairing-login.md +│ │ ├── M11-claude-questions.md +│ │ ├── ST-1109-pbi-status.md +│ │ ├── ST-1110-demo-readonly.md +│ │ ├── ST-1111-claude-job-trigger.md +│ │ ├── ST-1114-copilot-reviews.md +│ │ ├── tweede-claude-agent-planning.md (rename — geen spaties/em-dash) +│ │ └── archive/ (uit `.Plans/` aan repo-root) +│ │ ├── 2026-04-27-claude-md-workflow-update.md +│ │ ├── 2026-04-27-insert-milestone-tool.md +│ │ └── 2026-04-27-m8-realtime-solo.md +│ │ +│ ├── qa/ +│ │ └── api-test-plan.md +│ │ +│ └── assets/ +│ ├── erd.svg +│ └── icons.html +│ +└── .Plans/ (WEG — naar docs/plans/archive/) +└── Brainstorm.md (WEG — junk, of naar docs/scratch/) +└── docs/patterns/test.md (WEG — junk) +``` + +**Prefix `scrum4me-` overal weg.** Je staat in de Scrum4Me-repo. +**Alle bestandsnamen kebab-case, lowercase.** Geen `API.md`, geen `MD3_…`. + +--- + +## 5. CLAUDE.md herontwerp + +CLAUDE.md wordt strikt **router + harde regels** — geen referentie-tabellen, geen voorbeelden, geen rationale. + +Voorgestelde nieuwe inhoud (max ~150 regels): + +```markdown +# CLAUDE.md — Scrum4Me + +## 1. Wat is Scrum4Me +(2 zinnen — link naar README voor de pitch) + +## 2. Eerst lezen, altijd +- docs/INDEX.md — manifest van alle docs +- docs/glossary.md — bij twijfel over een term + +## 3. Hoe je werk vindt +Twee tracks (A: MCP, B: manueel) — verkort tot 10 regels. +Detail: docs/runbooks/sprint-flow.md + +## 4. Hardstop-regels (nooit overtreden) +- demo-user heeft geen schrijfrechten (3-laagsdekking) +- @base-ui/react, niet Radix +- nooit bg-blue-500, altijd MD3-tokens +- één commit = één verantwoordelijkheid +- één branch per milestone, push pas na user-approval +- denormalized FKs uit DB-parent, niet uit client-input +(elk punt → 1 regel + link naar pattern/decision) + +## 6. Stack op één regel per laag +(geen versie-uitleg, link naar docs/architecture/overview.md) + +## 7. Snelreferentie patronen +| Wanneer | Lees | +|---|---| +| Server Action schrijven | docs/patterns/server-action.md | +| Drag-and-drop reorder | docs/patterns/sort-order.md | +| …(max 10 rijen)…| + +## 8. Verificatie vóór hand-off +`npm run lint && npm test && npm run build` +``` + +Alles wat nu in CLAUDE.md §Conventies, §Branch & PR Strategy, §Commit Strategy, §MCP-integratie, §Deployment staat → verhuist naar: +- `docs/runbooks/branch-and-commit.md` (regels + voorbeelden samen) +- `docs/runbooks/deploy-vercel.md` +- `docs/runbooks/mcp-integration.md` +- `docs/decisions/0003-one-branch-per-milestone.md` (waarom) + +CLAUDE.md houdt in §4 alleen de éénregelige regel + link. + +**Effect:** elke turn 150 r in plaats van 340 r aan orientation-context. De agent leest aanvullende docs alleen wanneer de huidige taak ze raakt. + +--- + +## 6. Front-matter spec + +Élk markdown-bestand in `docs/` (en `CLAUDE.md`, `AGENTS.md`) krijgt bovenaan: + +```yaml +--- +title: +status: draft | active | deprecated +audience: ai-agent | maintainer | contributor | external +language: nl | en +last_updated: 2026-05-02 +applies_to: [feature-of-module-of-milestone-keys] # optioneel +related: + - docs/.md + - CLAUDE.md +when_to_read: <één zin> +do_not_read_for: <één zin — voorkomt mis-fetch> +--- +``` + +**Waarom dit voor AI-lookup helpt:** + +- `status: deprecated` → agent slaat het over zonder te lezen. +- `applies_to: [M10, qr-login]` → grep op milestone-key → directe hit. +- `when_to_read` / `do_not_read_for` → agent kan beslissen op de eerste 20 regels of dit doc nuttig is, zonder de hele 800-regelige spec in te lezen. +- `related` → expliciete graaf in plaats van impliciete cross-refs. + +`docs/INDEX.md` wordt automatisch gegenereerd uit deze front-matter (klein script in `scripts/build-docs-index.ts` — onderdeel van het migratieplan). + +--- + +## 7. AGENTS.md herontwerp + +```markdown +# AGENTS.md + +This repo's source of truth for agent instructions is **CLAUDE.md**. +Codex, Cursor, Continue, and any other coding agent: read CLAUDE.md first. +The same product, security, and verification rules apply regardless of which agent runs. + +Repo-specific addendum (only if your agent does NOT speak markdown well): +- The "This is NOT the Next.js you know" note also applies to you. +- Run `npm run lint && npm test && npm run build` before handing work back. +``` + +Geen duplicatie van access-control of doc-sync — die regels staan exclusief in CLAUDE.md / `docs/patterns/` / `docs/decisions/`. + +--- + +## 8. Migratie in fases + +Elke fase is een eigen branch + PR. Geen big-bang. Volgorde gekozen zodat agents tijdens de migratie nog steeds werken. + +### Fase 1 — Junk weg, front-matter erbij (laag risico) + +- `docs/patterns/test.md` weghalen. +- `Brainstorm.md` weghalen of `docs/scratch/brainstorm-2026-05.md`. +- `.Plans/` → `docs/plans/archive/`. +- Front-matter toevoegen aan élk bestaand bestand (zonder verplaatsen). Status default = `active`. +- `docs/INDEX.md` genereren via script. + +**Voor commit:** alle bestaande paden werken nog. Geen risico voor lopende sessies of CI. + +### Fase 2 — Naamgeving normaliseren + +- `scrum4me-` prefix overal weg via `git mv` (1 commit per groep — backlog/specs/personas/styling/dialogs). +- `API.md` → `api/rest-contract.md`. +- `MD3_Color_Scheme_Documentation.md` → `design/md3-color-scheme.md`. +- `Tweede Claude Agent — Planning Agent.md` → `plans/tweede-claude-agent-planning.md`. +- `middleware.md` → `proxy.md` (volgt Next.js 16 hernoeming). +- Per `git mv`: in dezelfde commit zoek-en-vervang alle interne links + CLAUDE.md doc-index. + +### Fase 3 — Folder-taxonomie + +- Maak `docs/architecture/`, `docs/specs/`, `docs/design/`, `docs/api/`, `docs/runbooks/`, `docs/decisions/`, `docs/backlog/`, `docs/qa/`, `docs/assets/`. +- Verplaats per groep met `git mv`. Eén commit per groep. +- Update CLAUDE.md doc-index per stap. + +### Fase 4 — Splits monolithische docs + +- `scrum4me-architecture.md` (1.247 r) opdelen in 6 docs onder `docs/architecture/`. +- Originele file wordt 20 regels: titel + "Dit document is opgesplitst — zie:" + lijst met nieuwe paden. +- Idem voor `solo-paneel-spec.md` als dat onderdelen heeft die naar specs én patterns kunnen. + +### Fase 5 — CLAUDE.md verkorten + AGENTS.md verkorten + +- Knip CLAUDE.md naar het skelet uit §5. +- Verplaats verwijderde secties naar `docs/runbooks/` en `docs/decisions/`. +- AGENTS.md vervangen door de versie uit §7. + +### Fase 6 — ADR-backfill + +- Schrijf ADR's voor de impliciete beslissingen (5–8 stuks): + 1. base-ui-over-radix + 2. float-sort-order + 3. one-branch-per-milestone + 4. status-enum-mapping (db UPPER ↔ api lower) + 5. iron-session-over-nextauth + 6. demo-user-policy (3-laags) + 7. claude-question-channel-design + 8. agent-instructions-policy (was audit) + +### Fase 7 — Glossary + index-script + +- `docs/glossary.md` schrijven (PBI, Story, Sprint, Solo, Todo, demo-token, MCP-job, …). +- `scripts/build-docs-index.ts` — genereert `docs/INDEX.md` uit alle front-matters. +- Husky pre-commit hook: index regenereren bij wijziging van front-matter. + +### Fase 8 — Cross-link-check + +- Klein script dat alle `docs/...md` links volgt en rapporteert dode links én anchor-misses. +- Toevoegen aan `npm run lint` of `npm test`. + +--- + +## 9. Wat dit oplevert (meetbaar) + +| Metric | Vandaag | Doel | +|---|---:|---:| +| Regels die elke agent-turn standaard in context komen (CLAUDE.md) | 340 | ≤150 | +| Doc-bestanden in `docs/` root | 13 | 2 (INDEX.md, glossary.md) | +| Doc-bestanden zonder front-matter | 36 | 0 | +| Junk-bestanden | 3 (test.md, Brainstorm.md, .Plans/) | 0 | +| Bestandsnamen met spaties of niet-ASCII | 1 | 0 | +| Filename-prefixen die geen informatie toevoegen (`scrum4me-`) | 8 | 0 | +| Documenten >800 regels | 4 | 0 (na splitsing) | +| Dode interne links | onbekend | 0 (na lint) | + +--- + +## 10. Wat dit níet oplevert (eerlijk) + +- Codequaliteit verbetert niet automatisch. +- Patronen die nu fout zijn worden niet gefixt — alleen vindbaar gemaakt. +- ADR's invullen kost denkwerk dat ik niet uit jouw hoofd kan halen — fase 6 vereist jouw input. +- AI-agents die geen front-matter parseren (oudere modellen, sommige codex-flavors) profiteren minder. Voor de `docs/INDEX.md` is het wel platte tekst — die helpt iedereen. + +--- + +## 11. Open beslissingen — status + +| # | Vraag | Besluit (2026-05-02) | +|---|---|---| +| 1 | Taal van docs, front-matter, INDEX.md | **English** — alle nieuwe en herschreven docs in het Engels. Code comments blijven Engels (al zo). UI-strings blijven Nederlands. | +| 2 | MD3-color + styling samenvoegen | **Eén doc** — `docs/design/styling.md`. | +| 3 | `solo-paneel-spec.md` | **Samenvoegen** — opgaan in `docs/specs/functional.md` (eigen sectie). | +| 4 | `.Plans/` archief | **Bewaren** — verplaatsen naar `docs/plans/archive/`. | +| 5 | ADR-template (Nygard vs MADR) | **In discussie** — referentielink gedeeld, ik heb die niet kunnen openen (claude.ai share staat niet op de fetch-allowlist). Default voor fase 6: Nygard, klein en passend bij solo + kleine repo. Vervangbaar zodra besluit valt. | +| 6 | Index-generator | **Node-script** in `scripts/build-docs-index.ts`. | + +## 12. Implicaties van besluit 1 — taalwissel + +De keuze "alle docs Engels" is groter dan hij lijkt. Drie scope-niveaus: + +**Niveau A — going-forward only (kleinste scope):** +- Élk nieuw doc en élke nieuw aangemaakte front-matter in het Engels. +- Dit plan, INDEX.md, glossary.md, runbooks/, decisions/ — allemaal Engels vanaf creatie. +- Bestaande Nederlandse docs blijven staan tot ze om een andere reden geraakt worden. +- **Risico:** mengvormen in docs/ — een agent vindt ene helft Engels, andere helft Nederlands. Grep op een Engels keyword mist Nederlandse hits. + +**Niveau B — opportunistic (middel):** +- Niveau A + élke doc die we aanraken voor de restructuur (renames, splitsingen, front-matter toevoegen) wordt meteen vertaald. +- Aan het eind van fase 5 zijn `architecture/`, `specs/`, `design/`, `api/`, `patterns/`, `runbooks/`, `decisions/` allemaal Engels. +- Backlog, plans en QA blijven Nederlands tenzij ze ge-edit worden. + +**Niveau C — full sweep:** +- Élke `.md` in de repo vertalen, ongeacht of de restructuur hem aanraakt. +- Aanzienlijk werk: ~10.700 regels prose. Schatting: 1-2 dagen agent-tijd of een batch-translate-pass met review. + +**Voorstel: niveau B.** Sluit aan bij de migratiefases zonder een aparte translation-sprint te hoeven plannen. Niveau C kan later als één losse PR. + +## 13. ADR-template — voorlopige keuze + +Tot besluit valt op vraag 5: ik gebruik **Nygard-Light** als template voor fase 6. Eén ADR is één bestand met: + +```markdown +--- +title: +adr_number: 0001 +status: proposed | accepted | superseded by 00xx +date: 2026-05-02 +--- + +# 0001. + +## Context +Why this decision matters now. What forces are in play. + +## Decision +The choice we make. One paragraph, declarative. + +## Consequences +What becomes easier, what becomes harder, what we accept. +``` + +Compact, grep-vriendelijk, en agent-leesbaar binnen ~30 regels. Als MADR de uitkomst wordt, swappen we het template voor fase 6 — alle eerdere fases zijn template-onafhankelijk. + +## 14. Volgende stap + +Met deze besluiten kan ik fase 1 omzetten naar een concrete uitvoeringslijst: + +- exacte `rm` / `git mv` / `mkdir` commando's +- de front-matter-template in het Engels +- één `npm run` of bash-snippet die de hele fase in één commit zet +- bijbehorende update-diff voor CLAUDE.md (alleen de doc-index-tabel) + +Zeg het woord en ik produceer dat als `docs/plans/docs-restructure-phase-1.md`. + +--- + +## Verificatie van dit plan + +- [x] Bestandsnamen en regelaantallen gecheckt tegen `find docs -type f` + `wc -l` op disk (2026-05-02). +- [x] Cross-refs in CLAUDE.md gegrep't en op bestaan getoetst. +- [x] Geen voorgestelde nieuwe paden conflicteren met bestaande. +- [x] Open beslissingen (§11) afgehandeld door maintainer (2026-05-02) — vraag 5 voorlopig op default. +- [ ] ADR-template definitief vastgesteld (vraag 5). +- [ ] Migratie fase 1 omgezet naar uitvoerbaar PR-plan (`docs/plans/docs-restructure-phase-1.md`).