judge

Judge Skill

Unabhaengiger Bewertungs-Agent der die Arbeit eines Worker-Agenten prueft. Wird als separater claude -p Prozess mit frischem Context gestartet, um Confirmation Bias zu vermeiden.

Trigger-Phrases

• "ergebnis bewerten", "arbeit pruefen", "judge task"
• "evaluate result", "review task output", "acceptance check"
• "hat der agent sauber gearbeitet", "qualitaetspruefung"

Warum ein separater Agent?

Ein Agent der seine eigene Arbeit bewertet hat systematischen Confirmation Bias — er "sieht" Probleme nicht, die er selbst verursacht hat. Der Judge-Agent:

• Hat einen frischen Context (kein Wissen ueber gescheiterte Ansaetze)
• Kennt nur das Ergebnis, nicht den Weg dorthin
• Prueft gegen objektive Kriterien (Tests, Akzeptanzkriterien, Linting)
• Kann harte Entscheidungen treffen (Task als failed markieren)

Assumptions

• Wird als claude -p Subprozess vom Orchestrator gestartet
• Hat Zugriff auf das Projekt-Repository (gleicher Working Directory)
• tasks.json enthaelt den zu bewertenden Task mit Akzeptanzkriterien
• Testinfrastruktur (wenn vorhanden) ist ausfuehrbar

Aufruf durch den Orchestrator

# Der Orchestrator spawnt den Judge als separaten Prozess
TASK_ID="T003"
claude -p "$(cat <<JUDGE_PROMPT
Du bist ein Judge-Agent. Deine einzige Aufgabe: Bewerte ob Task ${TASK_ID} korrekt erledigt wurde.

REGELN:
1. Du hast den Task NICHT selbst ausgefuehrt — bewerte unvoreingenommen
2. Pruefe NUR gegen die definierten Akzeptanzkriterien
3. Fuehre Tests aus wenn moeglich — vertraue nicht auf Augenschein
4. Dein Urteil ist FINAL: pass, fail, oder partial
5. Schreibe dein Urteil nach .agent-memory/judgments/

Lies .claude/skills/judge/SKILL.md und fuehre die beschriebene Prozedur aus.
Task-ID: ${TASK_ID}
JUDGE_PROMPT
)"

Prozedur

Schritt 1: Task und Kriterien laden

# Task aus tasks.json extrahieren
TASK=$(jq --arg id "$TASK_ID" '.tasks[] | select(.id == $id)' tasks.json)

Extrahiere:

• title: Was sollte getan werden?
• acceptance_criteria: Woran messen wir Erfolg?
• started_at / completed_at: Zeitrahmen
• notes: Eventuelle Hinweise vom Worker

Schritt 2: Automatisierte Pruefungen

Fuehre alle automatisierbaren Checks aus:

2a. Test-Suite

# Teste ob die Projekt-Tests bestehen
# Erkennung: package.json (npm test), pytest.ini/setup.cfg (pytest), Makefile (make test)
# WICHTIG: Timeout von 120s um haengende Tests abzufangen
JUDGE_TEST_TIMEOUT=120

if [[ -f "package.json" ]]; then
    timeout ${JUDGE_TEST_TIMEOUT} npm test 2>&1 | tail -50 > "${TMPDIR:-/tmp}/judge_test_output.txt"
    TEST_EXIT=$?
elif [[ -f "pytest.ini" ]] || [[ -f "setup.cfg" ]] || [[ -f "pyproject.toml" ]]; then
    timeout ${JUDGE_TEST_TIMEOUT} python3 -m pytest --tb=short 2>&1 | tail -50 > "${TMPDIR:-/tmp}/judge_test_output.txt"
    TEST_EXIT=$?
elif [[ -f "Makefile" ]] && grep -q "^test:" Makefile; then
    timeout ${JUDGE_TEST_TIMEOUT} make test 2>&1 | tail -50 > "${TMPDIR:-/tmp}/judge_test_output.txt"
    TEST_EXIT=$?
else
    echo "NO_TEST_SUITE" > "${TMPDIR:-/tmp}/judge_test_output.txt"
    TEST_EXIT=-1
fi

# Exit-Code 124 = timeout wurde erreicht
if [[ $TEST_EXIT -eq 124 ]]; then
    echo "TIMEOUT after ${JUDGE_TEST_TIMEOUT}s" >> "${TMPDIR:-/tmp}/judge_test_output.txt"
fi

2b. Linting / Type-Check

# Lint-Check (wenn konfiguriert)
if [[ -f "package.json" ]] && jq -e '.scripts.lint' package.json > /dev/null 2>&1; then
    npm run lint 2>&1 | tail -30 > "${TMPDIR:-/tmp}/judge_lint_output.txt"
    LINT_EXIT=$?
elif command -v ruff &>/dev/null; then
    ruff check . 2>&1 | tail -30 > "${TMPDIR:-/tmp}/judge_lint_output.txt"
    LINT_EXIT=$?
else
    LINT_EXIT=-1
fi

2c. Git Diff Analyse

# Welche Dateien wurden geaendert?
git diff --stat HEAD~1 2>/dev/null > "${TMPDIR:-/tmp}/judge_diff.txt"

# Gibt es unerwartet grosse Aenderungen?
LINES_CHANGED=$(git diff --shortstat HEAD~1 2>/dev/null)

Schritt 3: Kriterienbasierte Bewertung

Gehe JEDES Akzeptanzkriterium einzeln durch:

| # | Kriterium | Pruefmethode | Ergebnis | Evidenz |
|---|-----------|-------------|----------|---------|
| 1 | {CRITERION_1} | {test/manual/lint} | {pass/fail} | {DETAILS} |
| 2 | {CRITERION_2} | ... | ... | ... |

Pruefmethoden:

• test: Automatisierter Test vorhanden und bestanden
• lint: Linting/Type-Check bestanden
• diff: Code-Review des Diffs
• manual: Manuelle Inspektion (z.B. Datei existiert, Format stimmt)
• untestable: Kriterium kann nicht automatisch geprueft werden

Schritt 4: Urteil faellen

PASS:    Alle Kriterien erfuellt, Tests gruen, kein offensichtlicher Defekt
PARTIAL: Mindestens 1 Kriterium nicht erfuellt, aber substantieller Fortschritt
FAIL:    Kernfunktionalitaet fehlt, Tests rot, oder kritischer Defekt

Schwellenwerte:

• PASS: 100% der Kriterien erfuellt
• PARTIAL: >= 50% der Kriterien erfuellt
• FAIL: < 50% der Kriterien erfuellt ODER Tests rot

Schritt 5: Judgment schreiben

Speichere als .agent-memory/judgments/judgment_{TASK_ID}_{TIMESTAMP}.json:

{
  "task_id": "T003",
  "timestamp": "2026-03-24T14:30:00Z",
  "verdict": "pass|partial|fail",
  "criteria_results": [
    {
      "criterion": "API endpoint returns 200 for valid input",
      "method": "test",
      "result": "pass",
      "evidence": "pytest test_api.py::test_valid_input PASSED"
    },
    {
      "criterion": "Error handling for invalid JSON",
      "method": "manual",
      "result": "fail",
      "evidence": "No try/catch around JSON.parse in handler.py:42"
    }
  ],
  "automated_checks": {
    "tests": {"exit_code": 0, "summary": "14 passed, 0 failed"},
    "lint": {"exit_code": 0, "summary": "No issues found"},
    "diff_stats": "+142 -23 across 5 files"
  },
  "notes": "Hauptfunktionalitaet korrekt implementiert, aber Edge-Case bei Invalid-JSON nicht abgedeckt.",
  "recommendation": "Task als partial markieren. Neuen Task T003a erstellen: Error-Handling fuer invalid JSON in handler.py"
}

Zusaetzlich als Markdown-Report .agent-memory/judgments/judgment_{TASK_ID}_{TIMESTAMP}.md:

# Judgment: {TASK_ID} — {TASK_TITLE}

**Verdict: {PASS|PARTIAL|FAIL}**
**Datum:** {TIMESTAMP}

## Kriterien-Bewertung

| # | Kriterium | Ergebnis | Evidenz |
|---|-----------|----------|---------|
| 1 | ... | PASS | ... |
| 2 | ... | FAIL | ... |

## Automatisierte Checks
- Tests: {PASS/FAIL} ({SUMMARY})
- Lint: {PASS/FAIL/SKIP}
- Diff: {STATS}

## Empfehlung
{RECOMMENDATION}

Schritt 6: tasks.json aktualisieren

Basierend auf dem Urteil:

Verdict	Aktion
PASS	Status → done, completed_at setzen
PARTIAL	Status bleibt in_progress, notes mit fehlenden Kriterien aktualisieren
FAIL	Status → blocked, blocked_reason mit Begruendung, ggf. neuen Fix-Task erstellen

Error-Handling

Fehlerfall	Reaktion
Task-ID nicht in tasks.json	Abbruch mit Fehler
Keine Akzeptanzkriterien definiert	Warnung, nur automatisierte Checks ausfuehren
Test-Suite nicht ausfuehrbar	Als "untestable" markieren, nur manuelle Pruefung
Git-History nicht verfuegbar	Diff-Analyse ueberspringen
Judge kann Kriterium nicht bewerten	Als "inconclusive" markieren, nicht als pass zaehlen
Test-Suite haengt (Timeout)	Als "timeout" markieren, Ergebnis als FAIL werten, Hinweis in notes

Abgrenzung

• code-reviewer: Prueft Code-Qualitaet generisch (Style, Patterns, Security). Judge prueft spezifisch gegen Task-Akzeptanzkriterien.
• test-validator: Prueft ob Tests korrekt geschrieben sind. Judge prueft ob Tests BESTEHEN.
• quality-gate: Generischer Qualitaets-Check. Judge ist Task-spezifisch und unabhaengig vom Worker.

Designentscheidung: Warum claude -p statt inline?

Der Judge MUSS als separater Prozess laufen, weil:

1. Frischer Context: Kein Wissen ueber gescheiterte Ansaetze oder Workarounds
2. Keine Sunk-Cost-Fallacy: Kein emotionaler Bias nach langem Debugging
3. Unabhaengigkeit: Kann den Task ehrlich als FAIL bewerten ohne "eigene Arbeit" zu verteidigen
4. Context-Budget: Der Worker hat moeglicherweise das Context-Window ausgereizt — der Judge startet mit vollem Budget