Hydra leerlijn — Deel 6: Troubleshooting & escalatie

In deel 5 stond de pijplijn. Nu het laatste deel: wat doe je als hij niet groen wordt? Dit deel geeft je de keuzeboom — geordend van goedkoopste interventie naar duurste — en de patronen waarmee je needs-input-issues weer in beweging krijgt.

Wat betekent needs-input?

needs-input is geen failure-state in de zin van "Hydra heeft gefaald". Het is een expliciete escalatie: Hydra heeft gedaan wat hij kon, één run, en is tot een terminaal punt gekomen waar hij niet zelf verder kan zonder een menselijke beslissing.

Mogelijke oorzaken:

• Beide reviewers pass maar de quality-recheck na hun fixes is rood (een fix introduceerde een nieuwe overtreding).
• Eén van beide reviews :fail.
• Applier Axel Pliér :fail.
• Build crashed mid-stage (container OOM, rate-limit op alle accounts, …).
• Agent-maxed-out: een persona heeft zijn turn-budget opgemaakt.

Je rol als mens: bepaal welke van de vier opties hieronder het meest passend is en pas die toe. Niet een nieuwe retry:queued blind plakken in de hoop dat het deze keer wel werkt.

De interventie-ladder

Volgorde: altijd 1 → 2 → 3 → 4. Pak het goedkoopste herstel eerst. Reach voor rebuild:queued alleen als de build zelf fundamenteel verkeerd was.

retry:queued in detail

1. Jij (of een automated rule) plakt retry:queued op het issue. Met label-prefix wordt dat <prefix>-retry:queued — scripts/hydra-label.sh regelt dat automatisch.
2. Supervisor pakt het op als reguliere queue-job.
3. Orchestrator vindt de open PR op feature/<issue>/*.
4. Orchestrator cloned development, kopieert openspec/changes/<slug>/hydra.json en draait scripts/lib/build-feedback-brief.py → schrijft feedback.md met (a) applier-blockers, (b) unfixed reviewer-findings, (c) reeds-gefixed items, (d) Scope-lijst van alle geflagde files.
5. Orchestrator flipped retry:queued → retry:running, dispatcht de builder met HYDRA_MODE=fix en feedback.md gemount op /workspace/feedback.md.
6. Builder leest de brief, fixed álle bevindingen in één pass, beperkt zich tot Scope-files (plus nieuwe files die expliciet door een blocker geëist worden), commit met fix (retry): messages, pusht.
7. Succes: orchestrator strip alle review/applier-labels + retry:running + needs-input, zet code-review:queued. Reviewers draaien opnieuw tegen de gefixede code.
8. Faal: retry:running → needs-input, comment op het issue legt uit waarom en wijst naar rebuild:queued als de volgende hefboom.

Geen loop. Eén retry:queued = één iteratie. Als de fix-builder pusht en de volgende review weer faalt, kun je opnieuw retry:queued aanvragen — maar dat is dan een nieuwe single-shot, niet een auto-retry.

Wanneer is het de gate, en wanneer is het de builder?

Een terugkerende valkuil uit eigen retrospectives: het issue gaat 3 keer naar needs-input om dezelfde reden — typisch spdx-headers: fail of een gelijksoortige mechanische gate. Iedere retry:queued reproduceert hetzelfde patroon.

In dat geval is een vierde retry niet de juiste move. Wees discplineerd:

1. Sanity-check de gate zelf. Is dit een fout-positief? (Zie deel 3.) Een klassieker: een grep zonder word-boundary die meer matcht dan bedoeld. Fix in dat geval scripts/run-quality.sh of de gate-skill.
2. Hand-fix de mechanische overtreding. Soms is het sneller om zelf de SPDX-headers toe te voegen, te committen op de feature branch en de reviewers opnieuw aan te roepen via label-reset (situatie 2 hierboven). Tijd: minuten.
3. Overweeg een sterkere agent. Als hetzelfde klasse-fout op meerdere repos dezelfde "blind spot" vertoont, is dat een signaal dat de huidige builder-prompt of de mechanische gate niet voldoende is. Open een issue in hydra/ om de gate aan te scherpen of een "housekeeping"-agent te bouwen.

Watch-list patronen

Patronen die we al hebben gezien en die het waard zijn om eerst tegen je situatie te leggen:

Diagnostics: waar kijk je?

Snelle checklist als een issue naar needs-input gaat:

# 1. Welke labels staan er nu?
gh issue view <N> --repo ConductionNL/<app> --json labels --jq '[.labels[].name]'

# 2. Wat zegt hydra.json (mits aanwezig op de feature branch)?
gh api repos/ConductionNL/<app>/contents/openspec/changes/<slug>/hydra.json?ref=feature/<N>/<slug> \
    --jq '.content' | base64 -d | jq '.cycles[-1] | {outcome, outcome_reason, pattern_tags}'

# 3. De supervisor-log van de relevante tijdspanne
grep "issue/<N>" logs/supervisor.log | tail -50

# 4. Pipeline-logs (per stage) op de feature branch
gh api repos/ConductionNL/<app>/contents/openspec/changes/<slug>/pipeline-logs?ref=feature/<N>/<slug>

hydra.json is je belangrijkste bron. De outcome_reason en pattern_tags van de laatste cycle leggen meestal in één regel uit wat er misging.

Wanneer is "menselijk overnemen" gewoon goed?

Niet elk needs-input-issue verdient een geautomatiseerd fix-pad. Soms is de meest pragmatische actie: mens neemt over, los het op in een eigen commit op de feature branch, push, mark resolved.

Voorbeelden:

• Een kleine semantische beslissing die de Builder niet kan maken zonder context buiten de change (bijv. "moet dit veld optional of required zijn?").
• Een interactie met een externe partij (open ticket bij een leverancier).
• Een gate die fout-positief is en een fix in hydra/ zelf vereist (waarover je niet binnen één retry-cyclus uit bent).

Hydra is een fabriek, geen ideologie. Pak de menselijke shortcut als die billijker is.

Test jezelf

Vier korte vragen om te checken of je dit deel begrepen hebt. Vastgelopen? Klik Hint. Curieus naar het antwoord? Klik Antwoord.