Gist Share

Title

Markdown Content

# De `/solve` Skill — Documentatie voor Developers

## Wat is het?

De `/solve` skill is een gestructureerde workflow die Claude Code volgt voor het oplossen van bugs, het implementeren van feature requests, en het afsluiten van GitHub issues. Het doel: een consistent, reproduceerbaar proces van probleem tot gesloten issue met klikbare commit-links.

Er zijn **twee flows**, afhankelijk van hoe je de skill aanroept.

---

## Flow A: `/solve` (zonder argumenten)

**Wanneer**: Je hebt het probleem al onderzocht in de huidige conversatie — misschien zelfs al gefixt — en wilt het formeel afsluiten.

### Wat er gebeurt

1. **Samenvatting** — Claude vat het probleem en de (voorgestelde) fix samen in 1-2 zinnen.
2. **Implementatie** — De fix wordt doorgevoerd (als dat nog niet gebeurd is). Branching-strategie wordt automatisch bepaald:
   - Direct op `main` bij ≤5 gewijzigde bestanden in 1 repo
   - Feature branch (`fix/<beschrijving>`) bij grotere wijzigingen of meerdere repo's
3. **Test** — Unit tests worden direct gerund als ze bestaan. Bij ontbreken: vraag aan developer of er getest moet worden (handmatig of nieuwe tests schrijven).
4. **Commit & Push** — Commit met een placeholder `#XX` voor het issue-nummer (dat bestaat nog niet). Format:
   ```
   <Werkwoord> <beschrijving> (#XX)

- <gedragsverandering>
   - <gedragsverandering>
   ```
5. **GitHub Issue aanmaken** — Nu pas wordt het issue aangemaakt (zodat commit-referenties meteen in het comment staan). Daarna wordt de commit geamend om `#XX` te vervangen door het echte nummer (`fixes #<nummer>`), force-push, en het issue wordt gesloten.
6. **Samenvatting & Reflectie** — Overzicht van wat er gedaan is + skill-reflector voor eventuele verbeteringen aan de skill zelf.

### Voorbeeld use case

```
> "De KPI-berekening telt afgebroken processen mee, dat klopt niet"
> [onderzoek en fix in conversatie]
> /solve
```

Claude pakt de context op, commit, maakt een issue aan in `webwerf/wvuaw`, plakt het dicht.

---

## Flow B: `/solve <github-issue-url>` (bestaand issue)

**Wanneer**: Er staat een issue op GitHub dat opgelost moet worden. Dit is de meest volledige flow.

### Wat er gebeurt, stap voor stap

#### B1: Investigate

Claude haalt het issue op met `gh issue view` en leest de beschrijving + comments. Dan:

- Doorzoekt de codebase om de relevante code paths te begrijpen
- Voegt eerst logging/console.log toe om aannames te verifiëren (niet meteen fixen!)
- Presenteert een root cause analyse en voorgestelde oplossing
- **Vraagt bevestiging** voordat er iets geïmplementeerd wordt

Er wordt op dit punt nog **geen comment op het issue geplaatst**.

#### B2: Implement

De fix wordt doorgevoerd. Na het wijzigen van TypeScript-bestanden wordt automatisch de linter aangeroepen (`webhare-typescript-linter`).

Bij feature requests kan deze fase iteratief zijn — Claude blijft in deze fase totdat de developer tevreden is.

#### B3: Test

- Unit tests bestaan? → direct runnen zonder te vragen
- Tests falen? → fixen en opnieuw runnen tot groen
- Geen tests? → vragen of er tests toegevoegd moeten worden of handmatig getest wordt

#### B4: Commit & Push

Commit met `(fixes #<nummer>)` in het subject. Bij feature branch: `(#<nummer>)` (zonder `fixes`).

Na groene unit tests: commit gaat direct door, zonder bevestiging.
Na handmatig testen: bevestiging gevraagd aan developer.

Als er meerdere repo's gewijzigd zijn, wordt in elke repo apart gecommit met cross-repo referentie.

#### B5: Issue Comment & Close

Dit is waar de **audience detection** belangrijk wordt (zie volgende sectie).

#### B6: Summary & Reflect

Overzicht + skill-reflector.

---

## Audience Detection: Klant vs. Developer

Bij Flow B (bestaand issue) bepaalt Claude automatisch de **toon** van het afsluitende comment op basis van wie het issue heeft aangemaakt.

### Hoe het werkt

Claude checkt de GitHub-username van de issue-auteur:

```bash
gh api repos/<owner>/<repo>/issues/<number> --jq '.user.login'
```

| Auteur | Toon |
|---|---|
| `wouterhendriks` | **Dev-toon** — mag technisch zijn, veldnamen, WRD-termen, etc. |
| Iemand anders | **Klant-toon** — beschrijf gedrag, niet implementatie; geen technische details |

### Concreet voorbeeld: Issue #14

Issue [#14](https://github.com/webwerf/wvuaw/issues/14) ("Service fee NIET van toepassing bij Duitse leads") is aangemaakt door `badelacar93` — dat is **niet** `wouterhendriks`, dus klant-toon.

Het afsluitende comment zag er zo uit:

```markdown
## Service fee uitgesloten voor Duitse leads

Duitse leads krijgen nu geen service fee meer. Dit is op de volgende plekken doorgevoerd:

- Bij het doorvoeren naar "Verkocht - factuur" wordt geen service fee meer aangemaakt
  voor Duitse processen
- De service fee tekst is verwijderd uit de bevestigingsmail naar de klant
- De service fee tekst is verwijderd uit de automatische mailflows (Connect)
- In het admin-scherm is de service fee optie verborgen bij Duitse processen

Dit is te testen op de [acceptatieserver](https://cms.accept.looping.nl/).

**Let op**: De CMS-content op de website en de Duitse Algemene Voorwaarden pagina
moeten apart worden aangepast.

---

- wvuaw@[`ba7861f`](https://github.com/webwerf/wvuaw/commit/ba7861f...) — Skip service fee voor Duitse leads
- looping@[`12924c9`](https://github.com/webwerf/looping/commit/12924c9...) — Skip service fee tekst in Connect mailflow
- wvuaw_invoices@[`623140f`](https://github.com/webwerf/wvuaw_invoices/commit/623140f...) — Safety net in task handler + unit tests
```

**Let op wat er NIET in staat**: geen WRD-veldnamen, geen `UpdateProcess`-aanroepen, geen databasekolommen. De klant leest "service fee optie verborgen bij Duitse processen" — niet "isGerman vlag toegevoegd aan fee-berekening in `wvuaw/lib/internal/process.whlib`".

### Hoe zou een dev-toon comment eruitzien?

Als `wouterhendriks` dit issue had aangemaakt, had het er meer zo uit kunnen zien:

```markdown
## Service fee uitgesloten voor Duitse leads

Service fee wordt nu overgeslagen wanneer `process.country === "DE"`:

- `CalculateServiceFee()` in `wvuaw/lib/internal/billing.whlib` checkt land en returnt
  early bij DE
- Connect mailflow condities uitgebreid met country-filter voor service-fee blokken
- Admin-scherm: service fee velden verborgen via Tollium conditionele visibility
- Safety net in `wvuaw_invoices` task handler: skip fee-generatie als land DE

---

- wvuaw@[`ba7861f`](...) — Skip service fee voor Duitse leads
- looping@[`12924c9`](...) — Skip service fee tekst in Connect mailflow
- wvuaw_invoices@[`623140f`](...) — Safety net in task handler + unit tests
```

---

## Comment structuur

Het afsluitende comment heeft altijd twee delen:

### Boven de streep: Wat er gedaan is

- `##` heading die de oplossing **beschrijft** (niet generiek "Oplossing" of "Aanpak")
- Geschreven in **voltooid tegenwoordige tijd** ("er is nu...", "krijgen nu geen...")
- Bij klant-toon: focus op gebruikerservaring
- Bij dev-toon: technische details welkom

### Onder de streep: Commit-referenties

Na een `---` separator komen klikbare commit-links:

```
- <repo>@[`<short-hash>`](https://github.com/<owner>/<repo>/commit/<full-hash>) — korte beschrijving
```

Elke gewijzigde repo krijgt een eigen regel.

---

## Acceptatieserver & Issue sluiten

### Acceptatieserver-vermelding

Claude vraagt via `AskUserQuestion` of er in het comment vermeld moet worden dat de fix te testen is op de acceptatieserver. Als ja:

> Dit is te testen op de [acceptatieserver](https://cms.accept.looping.nl/).

### Sluiten van het issue

| Situatie | Actie |
|---|---|
| Auteur is `wouterhendriks` | Issue wordt automatisch gesloten |
| Auteur is iemand anders (klant) | Issue wordt **NIET** gesloten — de klant moet eerst testen en akkoord geven |
| Developer vraagt expliciet om te sluiten | Issue wordt gesloten |

### Project board

Als het issue op een GitHub project board staat, vraagt Claude of de status aangepast moet worden (bijv. naar "Test").

---

## Verschil Flow A vs. Flow B — Samenvatting

| Aspect | Flow A (`/solve`) | Flow B (`/solve <url>`) |
|---|---|---|
| Issue bestaat al? | Nee — wordt aangemaakt | Ja — wordt opgelost |
| Onderzoeksfase? | Nee (al gedaan in gesprek) | Ja (B1: Investigate) |
| Issue-nummer in commit? | Placeholder `#XX`, later geamend | Direct `fixes #<nummer>` |
| Audience detection? | Nee (altijd dev-toon, eigen issue) | Ja (check auteur) |
| Issue sluiten? | Altijd (eigen issue) | Alleen bij dev-auteur |
| Comment format | `## Oorzaak` / `## Oplossing` | Beschrijvende `##` heading |

---

## Repo-detectie

Voor WVUAW/Looping geldt een speciale regel: **alle issues gaan naar `webwerf/wvuaw`**, ongeacht in welke module de code zit. Commits gaan wel naar de eigen repo van elke module:

| Module directory | Commit repo | Issue repo |
|---|---|---|
| `wvuaw/` | `webwerf/wvuaw` | `webwerf/wvuaw` |
| `looping/` | `webwerf/looping` | `webwerf/wvuaw` |
| `wvuaw_dashboard/` | `webwerf/wvuaw_dashboard` | `webwerf/wvuaw` |
| `wvuaw_sites/` | `webwerf/wvuaw_sites` | `webwerf/wvuaw` |
| etc. | etc. | `webwerf/wvuaw` |

---

## Branching-strategie

Wordt automatisch bepaald:

| Situatie | Strategie |
|---|---|
| ≤5 bestanden, 1 repo | Direct op `main` |
| >5 bestanden | Feature branch `fix/<beschrijving>` |
| Meerdere repo's | Feature branch |
| Developer vraagt erom | Feature branch |

Na merge van feature branch wordt de lokale branch opgeruimd, de remote branch blijft staan.

---

## Resuming across sessions

Als je een `/solve` eerder bent begonnen maar de sessie is afgelopen, pakt Claude het op waar het gebleven was. Bij het opnieuw aanroepen:

- Checkt `git log --oneline -5` voor gerelateerde commits
- Checkt `gh issue view` voor bestaande comments
- Begint bij de eerste onafgeronde fase

---

## Commit message format

Altijd een subject + bullet body:

```
Add country check for service fee calculation (fixes #14)

- Skip service fee creation for German processes
- Hide service fee fields in admin screen for DE leads
- Remove service fee text from Connect mailflow for German processes
```

Subject: imperatief, max ~72 tekens. Body: beschrijf **gedrag**, niet bestanden.

Password (optional)

Expiration