Handover spec pack

Skill: Prototype/Artifact → Handover Spec Pack

Zweck

Transformiere ein exploratives Artefakt — insbesondere Code-Repo oder Excel-Datei — in ein reviewbares, übergabefähiges Spezifikationspaket für einen formalen Software- oder Einführungsprozess.

Der Skill ist tool-agnostisch und für Umgebungen wie Claude Code, Claude Cowork, OpenAI Codex, ChatGPT oder ähnliche Agenten gedacht.

Er ist ausdrücklich für Artefakte geeignet, die:

• im Rapid Discovery / Rapid Prototyping entstanden sind,
• nicht produktionsreif sein müssen,
• aber bereits viel fachliche Intention und funktionales Verhalten enthalten.

---

Kernprinzip

Behandle das Artefakt nicht als Vorgabe für produktionsreifen Code, sondern als Informationsquelle über gewünschtes Verhalten, implizite Annahmen, fachliche Ziele und Bedienlogik.

Das Ergebnis soll nicht sagen:

• „Bau es exakt so nach",

sondern:

• „Das Artefakt deutet auf folgende fachliche Funktionalität, Annahmen, Bedienlogik und Abnahmekriterien hin."

---

Primäre Artefaktklassen (v1)

Pflicht

• Quellcode / Repo
• Excel-Dateien / Tabellen

Optional

• JSON
• CSV
• SQL

Später

• PDF
• UI-Prototypen / Screenshots / Mockups

---

Zielrollen / Standard-Views

Erzeuge standardmäßig diese Ausgabe-Views:

1. Functional Spec Fachlich orientierte Spezifikation: Was das Artefakt tut, warum es das tut, welche fachliche Logik erkennbar ist.

2. End User Guide High-Level-Bedienungsanleitung für Anwender:innen.

3. Owner Guide Dokumentation für Template-/Produkt-/Prozess-Owner: Pflege, Annahmen, Betriebslogik, spätere Review- und Änderungsfähigkeit.

4. Review Pack Prüfpaket für Fachseite / Stakeholder / Entwicklung:

   • beobachtetes Verhalten
   • inferierte Intention
   • offene Fragen
   • Risiken / rote Flaggen
   • Abnahmekriterien
   • mögliche User Stories

---

Zentrale Qualitätsunterscheidung

Kennzeichne jede Aussage im Output explizit als eine der folgenden Klassen:

1) OBSERVED

Direkt aus dem Artefakt ableitbar. Beispiel:

• Formel vorhanden
• bestimmtes UI-Element vorhanden
• Funktion liefert beobachtbar Output X auf Input Y

2) INFERRED

Plausible Interpretation aus Struktur, Namensgebung, Flow oder Nutzungsmuster. Beispiel:

• „Diese Tabelle dient offenbar als zentrale Planungstabelle"
• „Diese Funktion scheint Freigabe-Logik abzubilden"

3) OPEN / UNKNOWN / RISK

Nicht sicher ableitbar, strittig, widersprüchlich oder potenziell fehlerhaft. Beispiel:

• möglicher Bug
• unklare fachliche Annahme
• harter Jahresbezug
• Bereichsdiskrepanz
• extern referenzierte, nicht sichtbare Logik

Diese Trennung ist Pflicht.

---

Output-Paket (Standard)

Erzeuge immer ein strukturiertes Handover-Paket mit festen Dateinamen.

Pflichtdateien

1. SPEC.md — Fachliche Hauptspezifikation
2. USER_GUIDE.md — Bedienungsanleitung für Endnutzer:innen
3. OWNER_GUIDE.md — Anleitung für Owner / Maintainer / Einführungsverantwortliche
4. REVIEW_PACK.md — Prüfpaket mit Annahmen, Risiken, offenen Punkten, User Stories und Abnahmekriterien
5. ASSUMPTIONS.md — Implizite Annahmen, offene Punkte, nicht sichtbare Abhängigkeiten
6. ACCEPTANCE_TESTS.md — Fachliche Abnahmekriterien und Testfälle
7. TRACEABILITY.csv — Artefakt-Entitäten → Aussagen/Regeln/Views
8. COVERAGE_REPORT.json — Coverage, UNKNOWNs, Qualitätsstatus

Optional, wenn sinnvoll

9. INTERFACE.md — Inputs, Outputs, Datenfelder, Einheiten, erlaubte Werte
10. USER_STORIES.md — Abgeleitete User Stories / Epic-/Story-Input
11. CHANGELOG_HINTS.md — Typische spätere Änderungsstellen / Wartungsrisiken
12. IR.json — Intermediate Representation als Maschinen-/Agenten-Zwischenschicht
13. DECISIONS.md — Design-Entscheidungen, die das Artefakt impliziert, als vorgeschlagene ADRs (siehe Modul „SDLC-Einstieg")
14. EFFORT.md — Grobschätzung je Funktion für eine Produktivumsetzung (siehe Modul „SDLC-Einstieg")

---

Was der Skill leisten soll

A. Fachliche Extraktion

Extrahiere aus dem Artefakt:

• zentrale Geschäftsobjekte / Arbeitsobjekte
• beobachtbares Verhalten
• Bedienlogik
• Datenflüsse
• Regeln
• Statuslogik
• Filterlogik
• Berechnungslogik
• implizite Prozesslogik

B. Handover-Fähigkeit

Übersetze das Artefakt in eine Form, die für den formalen Prozess nutzbar ist:

• für Review
• für Übergabe an Softwareentwicklung
• für organisatorische Einführung
• für spätere Wartung / Review

C. Unsicherheitsdisziplin

Alles, was nicht sicher aus dem Artefakt hervorgeht:

• nicht verstecken
• nicht still ergänzen
• explizit als INFERRED oder OPEN / UNKNOWN / RISK markieren

---

Nicht-Ziele

Der Skill soll nicht:

• Produktionscode bewerten
• Code-Qualität im Sinne von Clean Code auditieren
• Architektur freigeben
• Deployment-/Infra-Fragen lösen
• aus Proto-Code ungeprüft technische Vorgaben machen

Er darf auf technische Strukturen hinweisen, aber der Fokus ist fachliche Übergabefähigkeit, nicht Engineering-Politur.

---

Operationalisierte Vollständigkeit

„Vollständigkeit" bedeutet hier nicht absolute Wahrheit, sondern:

1) Artifact-Complete

Alle relevanten Artefakt-Entitäten wurden inventarisiert.

2) Behavior-Complete

Das beobachtbare Verhalten wurde hinreichend vollständig beschrieben:

• Inputs, Outputs, Regeln, Fehler-/Leerverhalten, zentrale Workflows

3) Intent-Reviewable

Die aus dem Artefakt abgeleitete Intention wurde so beschrieben, dass ein Mensch sie reviewen und bestätigen oder korrigieren kann.

Wichtig: Intent-Reviewable ist möglich. Intent-Certain ist meist nicht möglich.

---

Intermediate Representation (IR)

Nutze intern ein kanonisches Zwischenmodell. Die verschiedenen Outputs sind Views auf dieses IR.

Minimale IR-Bestandteile

• Artefakt-Metadaten
• Inventar
• Inputs / Outputs
• Regeln
• Workflows
• Abhängigkeiten
• Annahmen
• Risiken
• offene Punkte
• Traceability
• Coverage

---

Inventar-Regeln nach Artefaktklasse

Für Excel

Inventarisiere mindestens:

• Sheets, editierbare Flächen, berechnete Flächen
• Validierungen, Formeln oder Formel-Pattern, Named Ranges
• Tabellenobjekte, Pivot/Charts (wenn sichtbar)
• Conditional Formatting, Schutz-/Freigabelogik
• Abhängigkeiten zwischen Reitern
• sichtbare Eingabeparameter und Output-Flächen
• UI-/Bedienhinweise im Workbook

Extrahiere zusätzlich:

• zentrale Steuerungslogik, Berechnungslogik, Filterlogik
• fachliche Struktur, Hinweise auf SSOT
• Owner-relevante Änderungsstellen, potenzielle Bruchstellen

Für Code / Repo

Inventarisiere mindestens:

• Entry Points, zentrale Funktionen / Module / Klassen
• I/O-Schnittstellen, Konfigurationsparameter
• Datenmodelle / Strukturen
• UI-relevante Strukturen, wenn im Repo sichtbar
• beobachtbare User-Flows, Status-/Regellogik
• Fehlerbehandlung, implizite Constraints
• externe Abhängigkeiten

Extrahiere dabei ausdrücklich:

• nicht nur die Implementierung,
• sondern die fachliche Absicht, soweit beobachtbar oder plausibel inferierbar.

Wenn UI-Strukturen im Repo enthalten sind:

• nimm UI-Constraints und Interaktionslogik in die Spezifikation auf.

---

Standard-Gliederung der Outputs

SPEC.md

Inhalt:

• Zweck / Problemstellung
• Scope
• erkannte fachliche Kernobjekte
• zentrale Funktionen
• Workflows
• Regeln
• beobachtete Inputs/Outputs
• fachliche Invarianten
• Nicht-Ziele
• offene fachliche Fragen

Jede Aussage möglichst markieren als: [OBSERVED], [INFERRED], [OPEN]

USER_GUIDE.md

Ziel: Für Anwender:innen, die das Artefakt nur benutzen wollen.

Inhalt:

• Wofür das Artefakt da ist
• Welche Bereiche/Reiter/Funktionen wofür genutzt werden
• Quickstart
• typische Arbeitsabläufe
• häufige Fehler
• Troubleshooting
• DoD-Checkliste für Nutzung

Keine Formeln, kein Code, keine unnötigen technischen Details.

OWNER_GUIDE.md

Ziel: Für Personen, die das Artefakt verantworten, einführen, pflegen oder reviewbar halten müssen.

Inhalt:

• zentrale Pflegepunkte
• editierbare vs. berechnete Bereiche
• kritische Annahmen
• Parametrisierungsstellen
• Änderungsrisiken
• typische Bruchstellen
• Jahreswechsel-/Pflegehinweise
• was bei Übergabe an Dritte erklärt werden muss

REVIEW_PACK.md

Ziel: Für Fachreview, Stakeholder-Abgleich und Übergabe in den Entwicklungsprozess.

Inhalt:

• Executive Summary
• was sicher beobachtet wurde
• was plausibel inferiert wurde
• welche Fragen offen bleiben
• welche Stellen fragwürdig oder riskant sind
• rote Flaggen
• aus dem Artefakt ableitbare User Stories
• Abnahmekriterien
• Empfehlungen für Übergabe an Entwicklung

ASSUMPTIONS.md

Inhalt:

• explizite implizite Annahmen
• offene Definitionslücken
• vermutete Geschäftsregeln
• nicht sichtbare Abhängigkeiten
• TODO-Fragen für fachliche Klärung

Trenne sauber: Ableitbar / Plausibel inferiert / Unklar

ACCEPTANCE_TESTS.md

Inhalt:

• fachliche Testfälle (Given/When/Then)
• Positivfälle, Negativfälle, Edge Cases
• leere / ungültige / Grenzwerte
• User-Flow-Tests
• wo sinnvoll: Ableitung aus User Stories
• Test-ID und Referenz auf Funktion / Workflow / Regel

USER_STORIES.md (optional, aber empfohlen)

Format:

• Als <Rolle>
• möchte ich <Ziel>
• damit <Nutzen>

Wichtig: nicht fantasieren, nur aus erkennbarer Nutzung / Struktur / Flow ableiten. Bei Unsicherheit als [INFERRED] markieren.

---

Traceability

Für jede relevante Artefakt-Entität muss gelten:

• sie ist in mindestens einem Output reflektiert,
• oder explizit als out of scope markiert,
• oder als unknown/open erfasst.

Die TRACEABILITY.csv soll mindestens enthalten:

• Entity ID, Typ, Ort / Referenz, Kurzbeschreibung
• Status (observed, inferred, open, out_of_scope)
• Referenzen auf betroffene Dateien/Abschnitte

---

Coverage Report

Der COVERAGE_REPORT.json soll mindestens ausweisen:

• Anzahl inventarisierter Entitäten
• Anzahl gemappter Entitäten
• Coverage-Quote
• Anzahl offener Punkte
• Anzahl inferierter Aussagen
• Anzahl kritischer Risiken / roter Flaggen
• Qualitätsstatus

Empfohlene Statuswerte

• DRAFT: viele OPENs / schwache Coverage
• REVIEWABLE: gute Coverage, aber offene fachliche Fragen
• HANDOVER_READY: gute Coverage + offene Punkte sauber benannt + ausreichende Test-/Story-Basis

---

Pflichtdisziplin bei Unsicherheit

Wenn etwas nicht klar ist:

1. Nicht verschweigen
2. Nicht als sicher formulieren
3. Als [INFERRED] oder [OPEN] markieren
4. Wenn relevant: als Rote Flagge hervorheben

---

Pflichtdisziplin bei Bugs vs. Business Rules

Der Skill muss ausdrücklich unterscheiden zwischen:

• beobachtetem Verhalten
• vermuteter fachlicher Absicht
• möglichem Fehler / Bug / Workaround

Beispiel: Ein harter Jahresfilter in Excel kann gewollte Business Rule, temporäre Annahme oder unbeabsichtigter Bug sein. Das darf nicht einfach still als fachliche Wahrheit übernommen werden.

---

Default-View-Logik

Wenn keine weiteren Präzisierungen vorliegen:

• Sprache: Deutsch
• Dateinamen: Englisch
• standardmäßig alle vier Haupt-Views plus Pflichtdateien erzeugen

---

Empfohlener Arbeitsmodus

1. Artefakt klassifizieren (Repo / Excel / Mischform)
2. Inventar erzeugen
3. Beobachtbares Verhalten extrahieren
4. Implizite Annahmen sammeln
5. Workflows und Regeln formulieren
6. Observed / Inferred / Open markieren
7. User Stories und Acceptance Tests ableiten
8. Rollen-Views rendern
9. Traceability und Coverage prüfen
10. Rote Flaggen explizit ausweisen

---

Empfohlene Ausgabequalität

Antworten sollen:

• kompakt, aber belastbar sein
• zwischen Fakt, Interpretation und Unsicherheit sauber trennen
• fachlich verständlich formuliert sein
• explizit reviewbar sein
• keine Pseudo-Sicherheit erzeugen

---

Modul: SDLC-Einstieg aus einem Prototyp-Repo

Dieses Modul greift, wenn das Artefakt ein lauffähiger Prototyp ist und das Paket den Einstieg in einen formalen Entwicklungsprozess bilden soll — der Prototyp-Code wird danach verworfen, nur die Spezifikation geht weiter.

Zusätzlich zu den Standardregeln gilt dann:

Black-Box-Prinzip

Analysiere, was das System tut (Verhalten, Funktionen, Grenzfälle) — nicht, wie es implementiert ist. Ignoriere Code-Qualität. Formuliere so, als spezifiziertest du ein System, das von Grund auf neu gebaut wird.

Konsequenz für das Paket: kein Prototyp-Code im Output, keine Verweise auf Klassen, Dateien oder Funktionsnamen als Vorgabe. Ein fremdes Team muss ohne Zugriff auf den Prototyp arbeiten können — das ist das Abnahmekriterium für dieses Modul.

Granularität der funktionalen Anforderungen

Im SPEC.md bekommt jede Funktion eine stabile Kennung und diese fünf Felder:

• FA-{n}: {Name}
  • Auslöser — was das Verhalten initiiert
  • Eingabe — akzeptierte Daten/Parameter
  • Ausgabe — was produziert oder zurückgegeben wird
  • Seiteneffekte — berührte externe Systeme, Zustandsänderungen
  • Abnahmekriterien — testbare Bedingungen, einzeln aufgezählt

Grenzfälle und Geschäftsregeln als „WENN {Bedingung} DANN {Verhalten}" formulieren. Die ACCEPTANCE_TESTS.md referenziert die FA-Kennung, damit die Rückverfolgung ohne Umweg über Dateinamen funktioniert.

DECISIONS.md — implizierte Entscheidungen

Der Prototyp trifft Entscheidungen, ohne sie zu begründen: Auth-Ansatz, Datenhaltung, API-Stil, Fehlerbehandlung. Dokumentiere sie als ADRs im Format:

• ADR-{n}: {Entscheidung}
  • Status: Vorgeschlagen (nie „Akzeptiert" — der Skill gibt keine Architektur frei, siehe Nicht-Ziele)
  • Kontext: warum die Entscheidung überhaupt ansteht
  • Entscheidung: was der Prototyp impliziert
  • Konsequenzen: was daraus folgt, inklusive der Option, es anders zu machen

EFFORT.md — Grobschätzung

Je Funktion eine T-Shirt-Größe (S/M/L/XL) für die Produktivumsetzung, mit Begründung (Unbekannte, externe Abhängigkeiten, Datenmigration, Regulatorik). Eine Größe ohne Begründung ist wertlos; im Zweifel eine Nummer größer und die Unsicherheit als [OPEN] benennen.

Bündelung

Lege die Ergebnisse dieses Moduls in einem eigenen Ordner ab (Vorschlag: HANDOVER/), damit klar getrennt ist, was übergeben wird und was Arbeitsstand des Prototyps ist.

---

Kompakter One-Shot-Arbeitsauftrag

Nutze diesen Skill, um aus dem vorliegenden Artefakt ein vollständiges Handover Spec Pack zu erzeugen.

Arbeitsregeln:

• Behandle das Artefakt als fachliche Informationsquelle, nicht als technische Vorgabe.
• Trenne jede Aussage in OBSERVED, INFERRED oder OPEN.
• Erzeuge standardmäßig: SPEC.md, USER_GUIDE.md, OWNER_GUIDE.md, REVIEW_PACK.md, ASSUMPTIONS.md, ACCEPTANCE_TESTS.md, TRACEABILITY.csv, COVERAGE_REPORT.json
• Leite, soweit sinnvoll, zusätzlich USER_STORIES.md ab.
• Markiere Bugs, mögliche Fehlannahmen und harte Artefakt-Constraints explizit als Risiken.
• Liefere kein Architektur- oder Produktionscode-Review, außer wenn ausdrücklich verlangt.
• Ziel ist eine reviewbare Übergabe an Fachseite, Owner und/oder Softwareentwicklung.
• Ist das Artefakt ein lauffähiger Prototyp und soll das Paket den formalen Entwicklungsprozess eröffnen: zusätzlich das Modul „SDLC-Einstieg" anwenden (FA-Granularität, DECISIONS.md, EFFORT.md, kein Prototyp-Code im Output).