Umsetzungsplan erstellen

Skill: Umsetzungsplan erstellen (propose-implementation-plan)

Zweck

Erstellt einen TOML-Umsetzungsplan, der den implement-commit-Skill steuert. Der Plan muss maschinenlesbar sein – der Orchestrator liest ihn mechanisch aus.

Wann verwenden

• Funktionsentwurfsdokument existiert und ist genehmigt
• Bereit zur Umsetzung
• Koordination der Arbeit oder Verfolgung des Fortschritts erforderlich

Voraussetzungen

• Funktionsentwurf existiert in docs/features/NNNN-feature-name/design.md
• Testplan existiert in docs/features/NNNN-feature-name/test-plan.md

Ausgabeformat

Erstelle docs/features/NNNN-feature-name/implementation-plan.toml:

[meta]
feature = "feature-name"
feature_dir = "docs/features/NNNN-feature-name"
workspace = "./path/to/workspace"

[dependencies]
1 = []
2 = []
3 = [1, 2]

[[commits]]
id = 1
title = "Kurzbeschreibung"
message = "feat(scope): Conventional-Commit-Nachricht"
files = ["path/to/file.rs"]  # Relativ zum Arbeitsbereich
acceptance = ["Kriterium aus CC-Tabelle (CC-N)"]
anti_patterns = ["Was NICHT getan werden soll"]
tests = ["testname_aus_testplan"]  # ERFORDERLICH: Verweist auf test-plan.md

Vorgehen

1. Entwurfsdokument studieren

Lese design.md gründlich und notiere:

• Modulstruktur und betroffene Dateien
• Abhängigkeiten zwischen Komponenten
• Tabelle der kritischen Einschränkungen (CC-1, CC-2, usw.)

2. Testplan studieren (KRITISCH)

Lese test-plan.md und erstelle eine Zuordnung:

• Liste ALLER Testnamen aus der Tabelle der Anforderungsabdeckung auf
• Jeder Test MUSS genau einem Commit zugewiesen werden
• Tests sind die Quelle der Wahrheit für Akzeptanzkriterien

3. Fähigkeitsgrenzen identifizieren

Suche nach Fähigkeitsgrenzen, nicht nach Code-Artifakt-Grenzen.

Gute Grenzen:

• Ein neues Modul mit seinen Typen, Implementierung und Tests zusammen
• Eine für Benutzer sichtbare Fähigkeit (z. B. ein neuer CLI-Befehl)
• Eine durchgängig erfüllte Anforderung

Anti-Pattern: Aufteilung nach Artifakt (Typen in einem Commit, Implementierung in einem anderen, Tests in einem dritten).

4. Abhängigkeitsgraph erstellen

Für jeden Commit liste auf, welche Commits zuerst abgeschlossen sein müssen. Kodiere als Tabelle [dependencies], wobei der Schlüssel die Commit-ID und der Wert eine Liste von Abhängigkeits-IDs ist.

Der Orchestrator verwendet dies, um die parallele Ausführung zu bestimmen.

5. Tests Commits zuordnen

Für jeden Commit liste die spezifischen Testnamen aus test-plan.md auf, die ihn verifizieren:

tests = [
  "test_protocol_encode_acquire_request",
  "test_protocol_decode_roundtrip",
]

Jeder Test in test-plan.md muss genau einmal im tests-Array eines Commits erscheinen.

Dies erstellt eine prüfbare Rückverfolgbarkeit: test-plan.md → implementation-plan.toml → Code.

6. Kritische Einschränkungen extrahieren

Für jeden Commit kopiere die relevanten Einträge aus der Tabelle der kritischen Einschränkungen des Entwurfs:

• acceptance = Kriterien, die ERFÜLLT sein MÜSSEN (Verweis auf CC-N und Testnamen)
• anti_patterns = Was Prüfer ablehnen sollten

7. Commit-Einträge schreiben

Für jeden Commit:

[[commits]]
id = N                    # Fortlaufende Ganzzahl
title = "..."             # Was dieser Commit bewirkt
message = "..."           # Vollständige Conventional-Commit-Nachricht
files = ["..."]           # Pfade relativ zum Arbeitsbereich
acceptance = ["..."]      # Aus CC-Tabelle + Testbeschreibungen
anti_patterns = ["..."]   # Aus CC-Tabelle, oder leer []
tests = ["..."]           # Testnamen aus test-plan.md (ERFORDERLICH)

8. Mit unabhängigem Agenten verifizieren

Nach dem Erstellen des Planentwurfs starte einen Verifizierungsagenten:

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "Überprüfe, ob der Umsetzungsplan alle Tests aus test-plan.md abdeckt"
    )),
    context_files=[
        f"{skill_dir}/agents/verifier.md",
        f"{feature_dir}/test-plan.md",
        f"{feature_dir}/implementation-plan.toml",
    ],
    response_model=VerificationResult,
    read_only=True,
)

if not result.parsed.valid:
    # Lücken vor dem Fortfahren beheben
    agent_feedback(f"Plan unvollständig: {result.parsed.gaps}")

Der Verifizierer prüft:

• Jeder Test in test-plan.md ist einem Commit zugewiesen
• Kein Test ist mehreren Commits zugewiesen
• Akzeptanzkriterien verweisen auf spezifische Tests

9. TOML validieren

# Prüfen, ob TOML parst
python3 -c "import tomllib; tomllib.load(open('implementation-plan.toml', 'rb'))"

Richtlinien zur Commit-Größe

Ziel: 200–400 geänderte Zeilen pro Commit

Zu klein:

• Typen ohne Implementierung
• Traits ohne mindestens eine Implementierung
• Implementierung ohne Tests

Zu groß:

• Mehrere nicht zusammenhängende Fähigkeiten
• Mehr als 500 Zeilen
• Betrifft mehr als 5–6 Dateien

Genau richtig:

• Ein Modul mit Typen, Implementierung und Tests (~200–400 Zeilen)
• Ein CLI-Befehl mit Handler und Tests (~150–350 Zeilen)
• Ein vollständiger Adapter mit Tests (~200–400 Zeilen)

Verifizierungsmodell

from pydantic import BaseModel

class VerificationResult(BaseModel):
    valid: bool
    total_tests_in_plan: int
    tests_assigned: int
    gaps: list[str]  # Tests, die keinem Commit zugewiesen sind
    duplicates: list[str]  # Tests, die mehreren Commits zugewiesen sind

Beispiel

Siehe docs/features/0000-templates/implementation-plan.toml für ein vollständiges Beispiel.

Nächste Schritte

Nachdem der Plan erstellt und verifiziert wurde:

1. Auf Machbarkeit und Größe prüfen
2. implement-commit-Skill ausführen, um den Plan umzusetzen