OpenSpec leerlijn — Deel 3 (optioneel): Retrofit een bestaande codebase

Let op — dit is een optionele, situationele tutorial. De meeste developers zullen nooit een retrofit hoeven draaien. Het dagelijkse werk in een Conduction-app — changes schrijven, tasks implementeren, PRs openen — raakt geen van de commando's hieronder. Je kunt Deel 1 + 2 afronden en direct doorgaan naar de Hydra-leerlijn of de Claude skills-leerlijn zonder iets te missen.

Dit deel is alleen relevant in één specifiek geval: een oudere Conduction-app moet alsnog onder de huidige OpenSpec-conventie gebracht worden. Een klein aantal van onze apps is gebouwd voordat openspec/specs/ en de @spec-tag-conventie bestonden — ze hebben werkende code, maar geen specs en geen annotaties die vanuit code terug wijzen naar requirements. Als zo'n app ooit in lijn met de conventie gebracht moet worden, is dit de playbook ervoor. We lopen de retrofit-playbook van begin tot eind door.

Overleg eerst met je team lead voordat je begint. Een retrofit is echt werk — geen losse opdracht die je tussendoor doet. De volledige pass op een middelgrote app kost al snel uren wandkloktijd en een flinke hoeveelheid Claude-tokens (vaak de kosten van een gewone feature-change, soms meer — zeker als Bucket 2 groot uitvalt en /opsx-reverse-spec op veel clusters moet draaien). De retrofit-playbook noemt expliciet een roll-out-volgorde over onze apps precies om die reden: niet elke app is nu aan de beurt, en niet elke app heeft het nu nodig. Draai geen retrofit op eigen initiatief — stem eerst met je team lead of product owner af of deze app de juiste kandidaat is, welk budget er is, en welke apps hogere prioriteit hebben. Daarna start je bij Stap 1.

Waarom retrofitten?

Vrijwel elke Conduction-app is gebouwd voordat de spec ↔ code annotatie-conventie uit ADR-003 bestond. Die conventie zegt: het hoofd-docblock van elk PHP-bestand én het docblock van elke public method dragen één of meer @spec openspec/changes/<change-name>/tasks.md#task-N-tags die wijzen naar de taak(en) die ze implementeren.

Apps die je spec-first bouwt met /opsx-apply krijgen die tags gratis — de builder zet de tag erbij terwijl hij de code schrijft. Bestaande apps hebben een eenmalige retrofit-pass nodig, anders valt /opsx-verify (Deel 2, Stap 11) terug op fragiele keyword-matching: elke audit wordt gokken, elke refactor een muntopgooi.

Retrofit levert drie dingen tegelijk op:

1. Traceability — voor elke methode kun je beantwoorden: welke requirement implementeert dit?
2. Een eerlijk gap-overzicht — code zonder REQ, REQs zonder code en ADR-overtredingen komen allemaal in één rapport bovendrijven.
3. Een ingang voor Specter — de spec-dashboards over al onze apps vullen zich pas goed als de cohort-vlaggen kloppen (en dat doet retrofit).

Retrofit is niet "alsnog opschrijven wat je had moeten opschrijven". Het legt geobserveerd gedrag vast, niet oorspronkelijke intentie. Lossy by design. Dat accepteren we — een ruwe kaart is nuttiger dan geen kaart, en je kunt hem later altijd nog reviewen.

Drie skills, in volgorde

Draai ze exact in deze volgorde. De audit is het contract tussen de drie: annotate leest het rapport om te weten wat hij moet taggen, en reverse-spec leest het om te weten welke clusters nog een huis nodig hebben. Sla de audit niet over — en draai annotate niet op een verouderd rapport.

Wat is een ghost change?

Legacy-code is nooit tegen een change geschreven, dus er is geen tasks.md#task-N waar @spec naar kan wijzen. Retrofit overbrugt dat met ghost changes.

Een ghost change heeft dezelfde vorm als een gewone OpenSpec-change — proposal, spec-delta (soms leeg), tasks, uiteindelijk gearchiveerd — maar bestaat puur als anker voor @spec-annotaties. Naamconventie: retrofit-{JJJJ-MM-DD}-{omschrijving}, zodat hij chronologisch met non-retrofit-changes sorteert.

Eenmaal gearchiveerd blijft het pad openspec/changes/archive/<ghost-naam>/tasks.md#task-N resolveerbaar als textual reference. @spec doet geen live lookup, dus de annotaties blijven eeuwig geldig.

Hoe verschilt een retrofit-change van een gewone feature-change? Een gewone change start vanuit intentie ("Ik wil een full-text zoekfunctie toevoegen") en eindigt in code. Een retrofit-ghost start vanuit code ("deze methode doet al X") en eindigt in een gedocumenteerd anker. Zelfde artefacten op schijf, tegenovergestelde pijlrichting.

Stap 1: de app voorbereiden

Vóór de eerste scan:

cd /pad/naar/openregister
git checkout development        # of 'beta' bij apps die de specs daar houden
git pull
git status                       # MOET schoon zijn

Optioneel maar aanbevolen — maak .opsx-ignore aan in de app-root voor paden die je bewust niet gescand wil hebben (vendor-code, gegenereerde bestanden, bewust niet-gespecde interne tools). Eén glob per regel, # voor commentaar. Zie openregister/.opsx-ignore voor een uitgewerkt voorbeeld.

Specter-prereq (eenmalig, idempotent):

python3 concurrentie-analyse/scripts/migrate_app_specs_retrofit.py

Die voegt de kolommen retrofit, retrofit_extensions en spec_hash aan de app_specs-tabel toe. Zonder die kolommen weigert /opsx-reverse-spec te syncen.

Stap 2: scannen met /opsx-coverage-scan

In Claude Code, in de app-map:

/opsx-coverage-scan openregister

Dit draait read-only. Er worden geen @spec-tags geschreven, geen specs aangepast, geen commits gemaakt. De skill loopt elk PHP-bestand af, identificeert elke public method, en probeert hem te matchen tegen een bestaande REQ in openspec/specs/. De output is twee bestanden:

• openspec/coverage-report.md — menselijk leesbaar
• openspec/coverage-report.json — parseable sidecar, gebruikt door de volgende twee skills

Open het markdown-rapport. Het bevat een header, zes bucket-secties en twee meta-secties.

Stap 3: het rapport lezen — de zes buckets

De hele retrofit draait om deze buckets, dus loont het de moeite om ze uit het hoofd te kennen.

Plus twee meta-buckets die het rapport noemt maar waar geen retrofit-actie nodig is:

• annotated — methodes die al een @spec-tag dragen. Een tweede scan zou deze bucket moeten laten groeien en Bucket 1 moeten laten krimpen.
• plumbing — framework-glue, lege constructors, listener-dispatch, dunne controllers. Krijgt nooit een @spec.

Lees het rapport eerst handmatig door. De scan is heuristisch — foute Bucket 1-entries leveren foute annotaties op die downstream veel lastiger ongedaan zijn te maken dan vooraf te voorkomen.

Stap 4: Bucket 1 annoteren met /opsx-annotate

Vertrouw je het rapport:

/opsx-annotate openregister

Wat de skill in volgorde doet:

1. Maakt een ghost change retrofit-{JJJJ-MM-DD}-annotate-openregister/ met een lege spec-delta en één task per REQ in Bucket 1.
2. Loopt elk Bucket 1-bestand + -methode af en voegt @spec openspec/changes/retrofit-{datum}-annotate-openregister/tasks.md#task-N toe aan het docblock.
3. Archiveert de ghost change voordat de PR opent (hij hoeft geen eigen review-ronde te krijgen).
4. Update .git-blame-ignore-revs zodat de annotatie-commit git blame niet kapot maakt.
5. Opent een annotatie-only PR.

Een paar dingen om te weten:

• Idempotent. Opnieuw draaien zonder code-wijzigingen levert geen nieuwe annotaties op. Als er al een gedateerde ghost change voor vandaag staat, vraagt de skill of je die wil hergebruiken of een verse wilt. Volgende week opnieuw draaien levert een nieuwe gedateerde ghost change op.
• Annotatie-only PR. De diff voegt alleen docblock-commentaar toe. Reviewers hoeven het niet regel voor regel te lezen — ze hoeven steekproefsgewijs te checken of de matches kloppen tegen het rapport.
• PHPCS weigert de tag-volgorde? Stop. Fix de PHPCS-config, herorder nooit de tags. Het ADR-003 + hydra-gate-spdx-formaat ligt vast.
• .git-blame-ignore-revs werkt lokaal alleen als developers het eenmaal aanzetten: git config blame.ignoreRevsFile .git-blame-ignore-revs. De skill suggereert het, maar zet het niet zelf aan.

Stap 5: Bucket 2 reverse-speccen — één cluster per keer

Hier zit het echte werk. Voor elke Bucket 2-entry in het rapport één run:

# Bucket 2a — bestaande capability uitbreiden
/opsx-reverse-spec openregister --extend admin-settings

# Bucket 2b — gloednieuwe capability slaan
/opsx-reverse-spec openregister --cluster app-lifecycle

Wat de skill per run doet:

1. Leest de code van het cluster.
2. Draft REQs die het waargenomen gedrag beschrijven (max 5 REQs per run — heeft het cluster er meer nodig, splits het op in kleinere clusters en draai opnieuw).
3. Maakt een ghost change met de spec-delta + één task per nieuwe REQ.
4. Roept /opsx-ff aan om design.md te vullen (zodat reviewers ook het hoe zien, niet alleen het wat).
5. Annoteert de methodes van het cluster inline (roept niet /opsx-annotate aan — dat zou een parallelle ghost change opleveren).
6. Draait python3 concurrentie-analyse/scripts/sync_spec_content.py openregister om de spec bij Specter te registreren.
7. Archiveert de ghost change.
8. Opent één PR per run.

Bias naar --extend. Een bestaande capability uitbreiden is voor de reviewer goedkoper dan een nieuwe slaan — zelfde vocabulaire, zelfde grens. Pak --cluster alleen als het cluster echt nieuw gedragsgebied is dat geen huidige capability dekt.

Elke PR is een eigen review-cyclus omdat de REQ-taal de review-oppervlakte is. Reviewers focussen op: beschrijven deze REQs wat de code echt doet? Niet: werkt de code goed? (De code leeft al; correctheid is downstream.)

Documentatie-only retrofits

Soms blijkt een Bucket 2-cluster helemaal geen nieuwe REQs nodig te hebben. Drie sub-patronen:

In alle drie de gevallen heeft de ghost change geen specs/-map, en moet de proposal expliciet zeggen "no new REQs" / "no new REQs needed" / "behaviors are fully covered". App Mode (Stap 7) leest die zin om het patroon te detecteren.

Stap 6: Buckets 3 en 4 oppakken

Niet écht onderdeel van de retrofit, maar ze vallen uit hetzelfde rapport en je wilt ze niet laten liggen.

• Bucket 3a — REQ wees, history-match: open aparte PRs om de stukke code te repareren of te verwijderen. Niet bundelen met annotatie-PRs.
• Bucket 3b — REQ wees, geen spoor: één PR die elke REQ status: deferred in spec.md zet of helemaal verwijdert. Wat je ook kiest, documenteer het in de PR-body.
• Bucket 4 — ADR-conformance: open één follow-up issue "ADR cleanup pass — zie openspec/coverage-report.md Bucket 4" en pak het in een aparte cyclus op.

Stap 7: bevestig met App Mode dat de retrofit klaar is

Als je denkt klaar te zijn:

/opsx-verify --app openregister

Dit is de App Mode van /opsx-verify — de canonical retrofit-DoD-audit. Hij loopt elke retrofit-ghost change af onder openregister/openspec/changes/archive/retrofit-*, scant op dangling @spec-paden, audit de cohort-frontmatter, en print één pass/fail-rapport.

Niet hetzelfde als /opsx-verify <change-name>. Die mode verifieert één (actieve) change tegen openspec status en ziet gearchiveerde retrofit-changes helemaal niet.

Een retrofit is klaar als App Mode op elke regel ✅ geeft:

• Retrofit ghost changes — allemaal gearchiveerd
• Tasks completion — alle retrofit-tasks [x]
• Dangling @spec-paden — 0
• Symlinks onder openspec/changes/ — 0
• Naamconventie — elke retrofit-map past op retrofit-{JJJJ-MM-DD}-{omschrijving}
• Cohort-frontmatter — elke retrofitted capability draagt retrofit: of retrofit_extensions: op zijn master spec, in block-YAML met bare REQ-IDs
• Frontmatter-format — block YAML, geen inline lists, geen full-text values

Plus de workflow-items die App Mode níet checkt (die doe je zelf):

• Annotatie-PR + per-cluster reverse-spec-PRs allemaal gemerged
• Bucket 3-issues getriaged
• Bucket 4-follow-up issue geopend
• Eén afsluitende sync_spec_content.py openregister zodat Specter's cohort-kolommen voor elke retrofitted capability gevuld zijn

Test jezelf

Vijf vragen om te checken of dit deel is geland. Vastgelopen? Klik op Hint. Benieuwd naar het antwoord? Klik op Antwoord.

/opsx-reverse-spec {app} --extend <capability>

/opsx-reverse-spec {app} --cluster <nieuwe-naam>

/opsx-verify --app {app}