BuildStory

Was macht BuildStory?

BuildStory hilft einer Person zu sehen, wie ein Projekt gebaut wurde, nicht nur, was ausgeliefert wurde. Es rekonstruiert eine kleine Menge an Wendepunkten, deckt wiederholte Nacharbeit und wahrscheinliche Zeitfresser auf, prüft die nachweisgestützte Mensch-KI-Ausrichtung, wenn Transkripte autorisiert sind, und verwandelt die Belege in Lernerfahrungen und Karrierematerial.

Unverhandelbare Prinzipien

• Behandle Git- und Sitzungslogs als Beweise, nicht als Gedankenlesen. Kennzeichne Schlussfolgerungen und Konfidenz.
• Führe mit der Geschichte des Projekts. Behalte rohe Commit-Zahlen, die gesamte Historie und numerische Berechnungen als unterstützende Beweise.
• Zeige den Projektrythmus als beobachtbare Aktivität, niemals als Maß für Fleiß oder Produktivität. Verwende „aktivster Tag“, nicht „härtester Arbeitstag“.
• Wähle standardmäßig höchstens sieben Wendepunkte aus. Ein vollständiges Git-Log ist ein Beweis, keine Erzählung.
• Reduziere das Projekt niemals auf eine einzige Gesamtpunktzahl. Zeige ein unebenes Profil über verschiedene Dimensionen hinweg.
• Setze Iteration nicht mit Verschwendung gleich. Bezeichne verdächtige Muster so lange als „Schleifen-Kandidaten“, bis die Beweise oder der Benutzer sie bestätigen.
• Bevorzuge eine Erkenntnis auf Themenebene gegenüber einer Datei-Level-Statistik. Ein Pfad und eine Änderungsrate sind Beweise; sie sind nicht die Schlussfolgerung.
• Klassifiziere wiederholte Arbeit nur vorläufig als blocked-loop, necessary-exploration oder direction-change und bitte dann den Benutzer, die Ursache zu bestätigen.
• Erfinde keine geschäftlichen Auswirkungen, Verantwortlichkeiten, Teamgrößen, Leistungssteigerungen oder Lebenslauf-Kennzahlen.
• Überprüfe die Interaktion, bewerte oder diagnostiziere niemals die Kommunikationsfähigkeit des Benutzers. Berechne keine Gesamtpunktzahl für die Prompt-Qualität.
• Ein wiederholter Prompt ist kein Beweis für unklare Formulierung. Verlange eine Kette Benutzer → Assistent → Benutzer-Korrektur innerhalb derselben Sitzung, bevor du eine Kommunikationserkenntnis erstellst.
• Halte KI-Ausführungsfehler, Begriffsklärungsprobleme, sich ändernde Anforderungen und unzureichende Beweise getrennt. Schreibe die Zuschreibung niemals standardmäßig dem Benutzer zu.
• Behandle Git-Commits in der Nähe einer Klarstellung als nahegelegene Beweise, nicht als Beweis dafür, dass die Klarstellung den Commit verursacht hat.
• Lies standardmäßig nur das aktuelle Projekt. Frage, bevor du Sitzungsdateien außerhalb des autorisierten Arbeitsbereichs liest.
• Halte die Analyse lokal, es sei denn, der Benutzer fordert explizit einen externen Dienst an.
• Lade niemals ein vollständiges Transkript hoch oder reproduziere es. Behalte nur die kurzen Auszüge, die zur Erklärung einer Schlussfolgerung erforderlich sind.
• Ändere keine Projekt-Quelldateien. Schreibe Ergebnisse in ein dediziertes Ausgabeverzeichnis.

Standard-Workflow

1. Umfang festlegen

Identifiziere das Repository-Root und das Ziel des Benutzers. Standardmäßig wird der aktuelle Branch und die gesamte Git-Historie verwendet, die von HEAD aus erreichbar ist.

Verwende Sitzungsprotokolle nur, wenn sie bereits bereitgestellt wurden oder der Benutzer ihre Pfade autorisiert hat. Nur-Git-Berichte sind nützlich, müssen aber Zeitschätzungen und Schlussfolgerungen auf Absichtsebene als niedrige Konfidenz kennzeichnen.

2. Deterministische Beweise sammeln

Führe den gebündelten Analysator aus:

python3 <skill-dir>/scripts/build_story.py <repo-path> \
  --output <repo-path>/build-story-report \
  --language <zh|en>

Füge eine oder mehrere Transkriptquellen hinzu, wenn autorisiert:

python3 <skill-dir>/scripts/build_story.py <repo-path> \
  --session <authorized-session-file-or-directory> \
  --output <repo-path>/build-story-report \
  --language <zh|en>

Wenn vom Benutzer bestätigter Kontext verfügbar ist, speichere ihn im Berichtsausgabeverzeichnis und führe ihn mit --context erneut aus:

{
  "de": {
    "role": "Deine tatsächliche Verantwortung im Projekt",
    "outcome": "Das tatsächlich erzielte Ergebnis",
    "key_decision": "Die Entscheidung, die deine Fähigkeiten am besten zeigt",
    "summary": "Die Projektgeschichte in einem Satz",
    "resume_bullets": ["Bestätigte Lebenslauf-Punkte"],
    "insight_confirmations": {
      "path:src/sync.py": {
        "classification": "direction-change",
        "reason": "Die automatische Synchronisation widersprach der Einfachheit für Anfänger.",
        "lesson": "Wenn eine Funktion ständig Wiederherstellungsmechanismen einführt, überlege zuerst, ob sie überhaupt existieren sollte."
      }
    },
    "communication_confirmations": {
      "communication:example-id": {
        "attribution": "ai-ignored-explicit-requirement",
        "reason": "Die ursprüngliche Anforderung hat klar festgelegt, dass der Sprachwechsel erhalten bleiben muss.",
        "analysis": "Dies scheint eher ein Ausführungsfehler der KI zu sein, als dass der Benutzer seine Worte länger fassen müsste.",
        "lesson": "Wenn eine klare Grenze dennoch übersehen wird, überprüfe zuerst die KI-Ausführung."
      }
    },
    "translations": {
      "Initialize project": "Projekt initialisieren",
      "Add the requested feature": "Die angeforderte Funktion hinzufügen"
    }
  },
  "en": {
    "role": "your real responsibility",
    "outcome": "the verified result",
    "key_decision": "the decision that best demonstrates your ability",
    "summary": "the one-line project story",
    "resume_bullets": ["a confirmed resume bullet"]
  }
}

python3 <skill-dir>/scripts/build_story.py <repo-path> \
  --context <repo-path>/build-story-report/context.json \
  --output <repo-path>/build-story-report \
  --language <zh|en>

Das Skript generiert einen Standardbericht plus englische und chinesische Varianten:

• evidence.json: maschinenlesbare Beweise und transparente Metriken
• report.md: portabler Textbericht
• report.html: eigenständiger visueller Bericht mit einem Schalter DE / EN
• evidence.en.json, report.en.md, report.en.html: Englische Ausgaben
• evidence.zh.json, report.zh.md, report.zh.html: Chinesische Ausgaben

3. Beweise vor dem Erzählen prüfen

Lies evidence.json und überprüfe:

• zuerst journey_insights: Thema, vorläufige Klassifizierung, Beweiskette, Konfidenz und Bestätigungsfrage;
• communication_insights, wenn Transkripte autorisiert sind: maximal drei Karten, jede basierend auf einer geordneten Benutzeranfrage, Assistentenantwort und späteren Benutzerkorrektur;
• jede Kommunikationszuschreibung bleibt eindeutig: später geklärte Informationen, KI ignorierte explizite Anforderung, Begriffsklärungsproblem, geänderte Anforderung oder unzureichende Beweise;
• Datenquellen und angegebene Einschränkungen;
• Projektdaten, Commit-Anzahlen, Autoren und Dateianzahlen;
• ob die Geschichte auf dem ersten Bildschirm durch die ausgewählten Wendepunkte gestützt wird;
• ob Projektlaufzeit, aktive Tage, längster Durchlauf und aktivster Tag mit den zugrunde liegenden datierten Beweisen übereinstimmen;
• explizite Reverts im Vergleich zu abgeleiteten Hochwechselraten-Schleifen;
• ob Zeitschätzungen von Git oder zeitgestempelten Sitzungen stammen;
• die Beweise und Konfidenz hinter jeder Dimensionspunktzahl.

Beginne den Chat nicht mit src/foo.py, Commit-Anzahlen oder Änderungsraten. Übersetze die stärkste Erkenntnis zuerst in einfache Sprache:

1. was der Benutzer offenbar versucht hat;
2. ob es derzeit wie eine blockierte Schleife, notwendige Erkundung oder Richtungsänderung aussieht;
3. welche Commits diese Interpretation stützen;
4. die eine fehlende menschliche Tatsache, die die Schlussfolgerung ändern könnte.

Wenn die Daten der Beschreibung des Benutzers widersprechen, zeige die Diskrepanz und frage, anstatt stillschweigend eine Version auszuwählen.

Überprüfe für einen deutschen Bericht die sichtbaren Wendepunkt-Titel und Gesprächsauszüge. Wenn das Quellmaterial in einer anderen Sprache vorliegt, füge genaue Quell-zu-Deutsch-Einträge unter de.translations hinzu und führe erneut aus. Behalte den Originaltext in den Beweisdaten, aber zwinge den Benutzer nicht, eine englische Entwicklungsgeschichte in einer deutschen Oberfläche zu lesen.

Wenn autorisierte Transkripte vorliegen, verwende die kurze Benutzeranfrage und KI-Antwort, die jedem Wendepunkt zugeordnet sind. Bevorzuge diesen lesbaren Dialog gegenüber der Darstellung eines Commit-Betreffs als gesamte Geschichte.

4. Reise vor dem Verfassen der Leistung bestätigen

Stelle insgesamt höchstens drei Bestätigungsfragen. Wähle sie aus den höchstkonfidenten unbestätigten journey_insights und, nur wenn der Benutzer eine Kommunikationsüberprüfung angefordert hat, ein oder zwei communication_insights. Bitte den Benutzer nicht, eines der Bestätigungsobjekte manuell zu bearbeiten. Nachdem der Benutzer geantwortet hat, schreibe die Reisebestätigung in insight_confirmations oder die Kommunikationsbestätigung in communication_confirmations, führe den Analysator erneut aus und überprüfe, ob der Bericht die bestätigte Interpretation zeigt.

Erst nachdem die Reise bestätigt ist, frage nach verbleibendem Karrierekontext. Verwandle den Workflow nicht in ein Vorstellungsgespräch. Die üblichen fehlenden Fakten sind:

1. Was war die tatsächliche Verantwortung des Benutzers?
2. Welches Ergebnis hat das Projekt für den Benutzer oder für sich selbst geschaffen?
3. Welche Entscheidung zeigt die Fähigkeiten des Benutzers am besten?

Überspringe Fragen, deren Antworten bereits im Repository dokumentiert sind.

Hinterlasse diese Antworten nicht als reine Chat-Kontext, wenn es um Karriere, Portfolio, Leistung oder Vorstellungsgespräche geht. Speichere sie in context.json, führe den Analysator erneut aus und überprüfe das resultierende wiederverwendbare Material. Der HTML-Bericht ist das dauerhafte Artefakt, kein Ersatz für das Bestätigungsgespräch.

5. Die angeforderte Geschichte erstellen

Verwende die Beweise für eine oder mehrere der folgenden Ausgaben:

• Projekt-Retrospektive: Zeitstrahl, Wendepunkte, Reibungspunkte, Lernerfahrungen, Änderungen für den nächsten Durchlauf.
• Kommunikationsüberprüfung: Originalformulierung, Interpretation des Assistenten, spätere Korrektur, neutrale Zuschreibung und, nur wenn gestützt, eine kopierfertige Neufassung und ein wiederverwendbares Muster. Zeige höchstens drei Karten und vergebe niemals eine Prompt-Punktzahl.
• Portfolio-Fallstudie: Problem, Einschränkungen, Entscheidungen, Implementierung, Validierung, Ergebnis.
• Lebenslauf-Punkte: Aktion + Umfang + Methode + überprüftes Ergebnis. Hinterlasse einen expliziten Platzhalter, wenn die Auswirkung unbekannt ist.
• Interview-Geschichte: STAR-Struktur basierend auf Commits, Diffs, Tests, Veröffentlichungen und vom Benutzer bestätigtem Kontext.
• Leistungsnachweis: dauerhafte Beweiskarten, die erklären, was der Benutzer tatsächlich getan hat.

Lies references/narrative-guide.md, wenn du Karriere- oder Portfolio-Texte erstellst. Lies references/methodology.md, wenn du Punktzahlen, Zeitschätzungen oder Schleifenerkennung erklärst.

Qualitätsbarriere für die Ausgabe

Ein fertiger BuildStory-Bericht sollte dem Benutzer erlauben, zu beantworten:

1. Wie lautet die Ein-Satz-Geschichte dieses Projekts?
2. Über welchen Kalenderzeitraum erstreckte sich die beobachtbare Arbeit, an wie vielen Tagen, und was geschah am aktivsten Tag?
3. Welche fünf bis sieben Wendepunkte haben seine Richtung, sein Risiko, sein Verständnis oder seinen Auslieferungszustand verändert?
4. Wo wiederholte oder kehrte sich die Arbeit um?
5. War jeder wiederholte Bereich eine blockierte Schleife, notwendige Erkundung oder Richtungsänderung, und was muss noch bestätigt werden?
6. Welche Bereiche haben die meiste Aufmerksamkeit absorbiert, und wie konfident ist diese Schätzung?
7. Was hat der Benutzer nachweislich gelernt oder verbessert?
8. Welche glaubwürdige Leistung kann in einem Lebenslauf, Portfolio, Vorstellungsgespräch oder persönlichen Nachweis wiederverwendet werden?
9. Welche Details wurden erst klar, nachdem die KI bereits gehandelt hatte, wie sollte die Ursache zugeschrieben werden, und was könnte beim nächsten Mal früher gesagt werden?

Wenn die verfügbaren Beweise eine dieser Fragen nicht beantworten können, gib an, was fehlt. Eine kleinere ehrliche Geschichte ist besser als eine beeindruckende erfundene.