agentleFS
edrethardoedrethardo/werkbank-board/.claude/skills/werkbank-work-ticket/SKILL.md

werkbank-work-ticket

Skill0 starsChanged 3 months agoMITView on GitHub

Use this skill whenever you work a Werkbank ticket inside this repository — via chat request ("bearbeite WB-n"), via a handover from the board, or as a dispatched run. Single source of truth for the workflow; do not duplicate it elsewhere.

The file

Files
SKILL.md

Werkbank: Ein Ticket bearbeiten (einzige Quelle der Wahrheit)

Dieser Skill beschreibt den gesamten Arbeitsablauf für ein Werkbank-Ticket in diesem Repository. Er wird von drei Wegen aufgerufen — Chat-Anforderung, Übergabe an eine offene Chat-Session (WB-22), und Board-Dispatch (WB-70). Alle folgen denselben Schritten; wenn etwas hier steht, steht es sonst nirgends.

0. Voraussetzung — Ticket ist beansprucht

Vor diesem Skill beansprucht die Session das Ticket — mit EINEM Aufruf:

store.claim_ticket(tickets_dir, "WB-42", os.environ["CLAUDE_CODE_SESSION_ID"])

Das setzt Status, Session und claimed_at und leert einen Übergabe-Marker. Schreib den Status NICHT von Hand: ohne claimed_at hält das Board dein Ticket für gestrandet, übergibt es weiter und legt es fünf Minuten später zurück nach „Offen" — während du noch daran arbeitest (WB-181, live gemessen). Wer den Skill startet, ohne das Ticket zu halten, hat schon einen Fehler gemacht.

Beanspruchen heisst ANFANGEN, nicht vormerken. „In Arbeit" ist ein Versprechen an den Nutzer: die Karte wechselt die Spalte, das Board behandelt das Ticket als vergeben, und der Nutzer sieht Arbeit, die stattfindet. Wer beansprucht und dann erst etwas anderes zu Ende bringt, lässt das Board lügen — am 2026-08-17 bei WB-203 gemessen: minutenlang „in Arbeit", ohne dass irgendwer daran arbeitete. Der Nutzer hat es bemerkt und dem Board nicht mehr geglaubt. Muss ein Übergabe-Marker gehalten werden, bevor du wirklich anfangen kannst, sag das im Chat in einer Zeile — und fang direkt danach an. Seit WB-204 zählt die Karte die Minuten seit claimed_at und benennt einen zu lange stehenden Anspruch; es fällt also auf.

1. Klarheits-Prüfung — VOR dem Coden

Lies das Ticket vollständig. Frag den Nutzer, wenn irgendetwas davon zutrifft:

  • Beschreibung leer, vage oder mehrdeutig
  • widerspricht Projektregeln oder sieht zerstörerisch aus
  • „Fertig" ist nicht konkret sagbar

Interaktive Sitzung: direkt fragen, eine Frage pro Nachricht, in der Sprache des Nutzers. Nicht-interaktiver Lauf (niemand kann antworten): NICHT raten — Fragen ins ## Ergebnis schreiben, Status bleibt in_arbeit, du bist fertig. Der Nutzer weiß dann, was er klären muss (Board: „Ablehnen mit Grund").

1b. Schreibst du selbst ein Ticket für opencode?

Dann gilt der opencode-Modus aus dem create-ticket-Skill: nummerierte Schritte, exakte Namen, ## Tests / Abnahme mit kopierbaren Kommandos und erwartetem Ergebnis, ## Fertig, wenn als Haken-Liste, gate: gesetzt. Vorher prüfen mit store.opencode_ticket_gaps(...) — ein kleines Modell fragt nicht nach, es rät.

2. Arbeiten — im Zielprojekt, unter dessen Regeln

  • Änderungen NUR im Zielprojekt (t.project); nichts außerhalb anfassen.
  • CLAUDE.md dieses Projekts gilt (Commit-Disziplin, Skill-Aufrufe, Sprache).
  • Bug-Disziplin (nur type: bug): Ursache belegen (nachstellen, nicht raten) → Ursache beheben, nicht das Symptom → Regressionstest, der ohne den Fix fehlschlägt und mit ihm besteht. Der Nachweis (wie nachgestellt, welcher Test) gehört ins Ergebnis.
  • Skript-Ersetzungen prüfen (drei Vorfälle in diesem Projekt): nach jedem str.replace/sed das Ergebnis lesen ODER assert old in s — ein stiller Fehltreffer täuscht dir Erledigung vor.
  • config.json NIE roh schreiben — immer über die gesperrten Helfer (werkbank.projects.set_review_mode, add_project, …). Ein roher json.dump am laufenden Board vorbei hat am 2026-08-16 das Häkchen des Nutzers in einem anderen Projekt überschrieben (verlorenes Update, WB-116).
  • Board nie neu starten aus einem dispatchten Lauf: der Dispatcher stirbt mit, dein Abschluss geht verloren.
  • Push nur, wenn die Projektregeln das ausdrücklich vorsehen.

2b. Lange Stille vorher ansagen

Die Werkbank beendet einen Lauf, der 20 Minuten lang NICHTS meldet — sie hält ihn für hängengeblieben, und das ist meistens richtig. Ein grosser Download, ein langer Build oder ein Test-Durchlauf über Stunden ist die Ausnahme.

Wenn du weisst, dass du länger schweigen wirst, sag es vorher in einer eigenen Zeile:

STILLE ERWARTET: 4h — laedt 30 GB Modelldaten

Stunden und/oder Minuten (4h, 90m, 2h30m), Grund ist Pflicht — ohne Grund gilt die Ansage nicht. Der Nutzer sieht auf der Karte „⏸ Stille angekündigt bis 14:30", statt einen stummen Lauf für kaputt zu halten. Mehrfach ansagen ist erlaubt; die letzte Ansage gilt. Nach Ablauf greift die normale Grenze wieder.

Sag es, BEVOR du still wirst. Eine Ansage nach dem Abschuss gibt es nicht.

2c. Nachschlagen statt suchen — Züge sind der teure Teil

Am 30.08.2026 nachgemessen: Nicht geerbter Kontext treibt die Kosten, sondern die Zuganzahl. Vier Läufe starteten bei denselben 16.026 Token; WB-400 brauchte 624 Züge und 15,91 USD, WB-403 96 Züge und 3,30 USD. Jeder Zug schickt den ganzen bisherigen Verlauf erneut mit — doppelt so viele Züge kosten grob das Vierfache.

Daraus folgt: Jede Frage, die du ohne das Modell beantworten kannst, spart nicht ein bisschen Kontext, sondern einen ganzen Zug.

Dieses Repository ist für graft indiziert — ein Symbolgraph, der ohne Modell antwortet:

graft grep "resume_target"        # wo steht das, mit Zeilen und Kanten
graft callers attempt_modes       # wer ruft das auf
graft skeleton src/werkbank/store.py   # die API einer Datei, ohne sie zu lesen

Ein graft callers ersetzt fünf bis zehn Züge aus grep, Lesen und Weiterverfolgen. Nimm es, BEVOR du anfängst, Dateien zu durchsuchen.

Zwei Dinge, die dabei gelten:

  • Immer /home/USER/.local/bin/graft, nie npx. Die veröffentlichte Fassung zerstört den Graphen (am 08.08.2026 gemessen: 16.944 Knoten auf 865). Die Aufforderung zum Aktualisieren, die das Programm selbst ausgibt, NICHT befolgen.
  • Ein leeres Ergebnis ist kein Beweis. callers findet nicht jeden Aufruf; wer daraus „das ruft niemand auf" schliesst, irrt. Mit graft grep gegenprüfen, bevor du etwas löschst.

Nach grösseren Änderungen ist graft build billig (Sekunden, kein Modell) und hält den Index ehrlich. Ein veralteter Index lügt selbstbewusst.

3. Prüfen — vor dem Ergebnis

Fakten sammeln, bevor du zusammenfasst:

  • Passende Tests laufen lassen, Ergebnis lesen (nicht raten).
  • Wenn die Änderung sichtbar ist und du sie nicht selbst sehen kannst (Browser, Handy), sag das ehrlich — nicht behaupten.
  • Bug-Tickets: zeigen, dass der Test ohne Fix rot war und jetzt grün ist.

3b. Erst das Ticket, dann die Nachricht

Bevor du einer anderen Sitzung schreibst, frag dich: Gehört das ins Ticket? Fast immer ja.

Was du sagen willstWohin es gehört
„das muss vor meinem laufen"Feld nach
„das darf nicht gleichzeitig laufen"Feld nicht_mit
„so ist es ausgegangen"## Ergebnis
„ich brauche eine Entscheidung"Status rueckfrage
„ich arbeite gerade daran"claim_ticket (Status in_arbeit)

Warum das nicht Förmelei ist — diese Woche gemessen:

  • Eine Sitzung schrieb „nicht gleichzeitig mit WB-400" als Fliesstext. Das Board liest keine Prosa. Es startete beide, und ein Lauf arbeitete 1:46 lang über der ungespeicherten Arbeit des anderen.
  • Eine Sitzung löschte einen Zustandseintrag, statt ein Feld zu setzen — und verlor damit nebenbei den Schutz ihrer eigenen Tickets vor der Aufräumroutine.

Beides waren gut gemeinte Umgehungen des Boards. Beide kosteten Arbeit.

Dazu kommt der Preis: Eine Karte zu lesen kostet Kilobyte. Eine Nachricht landet im Verlauf der anderen Sitzung und wird von ihr in jedem weiteren Zug erneut mitgeschickt.

Eine Nachricht ist richtig, wenn es um kein Ticket geht (ein Fund, der die andere Sitzung sofort betrifft), oder wenn du etwas kaputtgemacht hast und sie es wissen muss, bevor sie sucht. Dann kurz, mit Belegen, ohne Wiederholung des Tickets.

4. Doku- und Journal-Pflicht (nur wenn das Zielprojekt sie hat)

Zielprojekt hat docs/journal/INDEX.md → Journal-Eintrag ist Pflicht (prüfen, nicht annehmen: in einer frisch geklonten Kopie kann der Ordner fehlen — dann gilt der Fall „kein Journal“ weiter unten) (journaling-Skill), im selben Commit wie die Änderung; das Ticket-Ergebnis darf dann kurz sein und aufs Journal verweisen. Kein Journal → das Ticket-Ergebnis IST der vollständige Bericht.

Nutzer-sichtbare Änderungen zusätzlich in CHANGELOG.md des Zielprojekts, documenting-Skill regelt den Rest.

5. Abschluss — ehrliches Ergebnis, dann Review

Regeln für das Ergebnis, ohne Ausnahme:

  • Was tatsächlich getan wurde, nicht was geplant war.
  • Was tatsächlich geprüft wurde (Tests, echte Läufe) — mit Zahlen.
  • Was NICHT geprüft werden konnte (Bildschirmaufnahme, Windows ohne Windows-Rechner …) explizit benannt statt kaschiert.
  • Was fehlgeschlagen ist, mit Beweis (Fehlermeldung, Log-Pfad). Ein fehlgeschlagenes Ticket, das still in in_arbeit bleibt, ist ein Bug — gehört nach review mit dem Grund im Ergebnis.
  • Nie erledigt setzen — das ist die Spalte des Nutzers.

Bei dispatchten Läufen liefert die letzte Nachricht das Ergebnis; die Werkbank setzt Status und Ergebnis dann selbst.

Bei Chat-Läufen — Nie set_result auf ein fremdes Ergebnis — es ERSETZT still (WB-231). Kein Zusammenführen, keine Versions-Prüfung, keine Warnung: vorhandener Text ist einfach weg. Am 2026-08-18 gemessen — ein Schreibvorgang löschte das 49-zeilige Review einer anderen Sitzung, ein anderer einen 73-Zeilen-Bericht; beides fiel nur durch git diff auf. store.append_result hängt unter dem Store-Lock an (Lesen und Schreiben in EINEM Lock — ein selbstgebautes Lesen-dann-Schreiben hat genau diese Lücke). Ein leeres Ergebnis wird ersetzt, nicht ergänzt.

WERKBANK=/pfad/zur/werkbank WB=WB-42 \
ERGEBNIS="Kurz, ehrlich, auf Deutsch." python3 - <<'EOF'
import os, sys
sys.path.insert(0, os.path.join(os.environ["WERKBANK"], "src"))
from werkbank import dispatch, store
tickets = os.path.join(os.environ["WERKBANK"], "tickets")
store.append_result(tickets, os.environ["WB"], os.environ["ERGEBNIS"])
store.update_ticket(tickets, os.environ["WB"], {"status": "review"})
# WB-314: `finished_at` stempelt der Store selbst beim Endzustand — und
# `claimed_at` beim Uebergang nach in_arbeit. Beide NICHT von Hand setzen.
sid = os.environ.get("CLAUDE_CODE_SESSION_ID")
if sid: dispatch.register_ticket_session(os.environ["PWD"], sid)
EOF

Danach committen (nicht pushen — die Werkbank-Session pusht):

git -C "$WERKBANK" add tickets/ && git -C "$WERKBANK" commit -m "Work tickets: <id> …"

Fallen, in die dieses Projekt tatsächlich getappt ist

  • Skript-Ersetzungen scheiterten still (WB-43, WB-48, WB-57).
  • Aus einem Lauf das Board neu gestartet — Abschluss weg (WB-17).
  • Chat-Änderungen stoßen die Warteschlange nicht an (WB-59, Taktgeber).
  • „Frisch installiert" gegen das eigene laufende Board getestet — der antwortet für den Klon mit (WB-46).
  • Wachposten erst nach Abschluss neu gestartet — Übergabe geht verloren (WB-66; siehe werkbank-pull-ticket §5).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.