jumibot/documento_fundacional

Gründungsdokument

Das Gründungsdokument stellt ein Projekt oder ein Produkt einer Familie formal und kompakt dar: welcher Bedarf gedeckt wird, warum eine Entwicklung lohnt, was es ist, in welchen Situationen es Mehrwert schafft, was es untermauert und was noch nachzuweisen ist. Es ist die Referenzbeschreibung des Projekts.

Es unterscheidet sich vom Vision-Dokument (skill documento_vision) in drei Punkten:

• Ohne narrative Handlung. Kein Fallbeispiel, keine Szenen, kein Prolog. Es ist eine geordnete Beschreibung wie ein Dossier.
• Formaler. Jede Aussage aus dem Fachbereich trägt ihre Quellenangabe, und es wird stets getrennt zwischen Veröffentlichtem, Designzielen und Berechnungsannahmen.
• Für den Autor und zum Teilen. Es dient dem Autor (und Claude in späteren Sitzungen) als kompakte, ablenkungsfreie Beschreibung und kann unverändert an Mitarbeiter, Partner oder Geldgeber weitergegeben werden.

Beide Dokumente koexistieren. Die Vision erzählt die Geschichte des Projekts; das Gründungsdokument beschreibt es. Ändert sich eines, wird das andere überarbeitet.

Diese Skill legt fest, was ein Gründungsdokument enthält und wie es verfasst wird. Der Generator, die Ressourcen, die Syntax, die Themen, die Werkzeuge und die Überprüfung sind die gemeinsamen von crear_documentos, das parallel zu dieser Skill gelesen wird.

Wo es abgelegt wird

Die Gründungsdokumente eines Projekts liegen gemeinsam in docs/specs/vision/ (Methodik der SF, „Gemeinsame Dokumentstruktur“): die Vision, das Gründungsdokument und die technischen Infografiken in infografias/.

• Für das Projekt: docs/specs/vision/fundacional-<projekt>.md und dazugehöriges .html.
• Für jedes Produkt einer Familie, falls vorhanden: fundacional-<produkt>.md.

Das .md ist die Quelle. Das .html wird generiert und nicht manuell bearbeitet. Falls von einem PDF oder vorhandenen HTML ausgegangen wird, wird es in .md konvertiert, und das Original bleibt daneben oder in _respaldo/ erhalten.

Vorbild. Falls das Projekt bereits ein Gründungsdokument hat, das diese Regeln gut anwendet, wird es als Beispiel beim Schreiben oder Überprüfen eines anderen gelesen; fachspezifische Inhalte werden nicht kopiert.

Abschnitte

Es gibt einen Kern, den jedes Gründungsdokument enthält, und optionale Abschnitte, die hinzugefügt werden, wenn das Projekt sie benötigt. Sie werden in der Reihenfolge ihres Erscheinens nummeriert. Anhänge stehen am Ende mit der Bezeichnung „Anhang A · …“.

Reihenfolge: erst erklären, dann rechtfertigen. Der Leser muss wissen, was das Produkt ist, bevor er die Argumente bewertet. Nach der Einleitung (Zweck, falls vorhanden, und der Prosatext zum Entwicklungsgrund mit der Idee, dem Unterschied und der These) folgen die erklärenden Abschnitte: das System oder die Familie, das Produkt und seine Funktionsweise, die Szenarien und Alternativen. Danach die rechtfertigenden Abschnitte: der dokumentierte Bedarf und die Problemkosten, die Auswirkungen, die Dimensionierung, die Risiken und „Was nachzuweisen ist“. Die Karten zum dokumentierten Bedarf können in einem eigenen Abschnitt nach dem Produkt stehen, wenn die Einleitung die These bereits zusammenfasst.

Schlichte Titelseite. Marke, Name und Leitspruch in normaler Schrift (ein bis zwei Zeilen). Nichts weiter, damit die Kopfzeile niedrig bleibt: Die Idee mit dem Zweck eröffnet den ersten Abschnitt als Einleitung, Version und Status stehen in der Fußzeile, und es gibt keine Zahlenzeile (Karten oder Belege zu zählen ist Inventur, kein Argument; wenn eine Zahl argumentiert, steht sie im Text).

Hinweise zum Gesamtumfang (was im Dokument Designziel und was validiert ist, oder jedes Kriterium, das auf den gesamten Text angewendet wird): Sie stehen am Anfang, außerhalb aller Abschnitte. Sie werden als Zitat > zwischen # Name und dem ersten ## geschrieben; der Generator setzt sie vor die Abschnitte als Kästchen.

Kern

1. Entwicklungsgrund. Beginnt mit einem Einleitungsprosatext vor den Karten und ohne Untertitel:

   • die Idee mit dem Zweck als Einleitung;
   • der Unterschied zu vorhandenen Alternativen, in einem Absatz, mit Quellenangabe und einem Satz pro Alternative;
   • die Entwicklungsthese: was es wert ist, jetzt finanziert oder gebaut zu werden, und unter welcher Bedingung es Wert schafft. Sie wird in Prosa formuliert, nicht in einem Kästchen, und begründet: auf welche Fakten des Dokuments sie sich stützt (mit Zahlen und Quellen) und was noch unbekannt ist – das muss der Pilot messen.

   Danach zwei oder drei Karten mit dem dokumentierten Bedarf (das gemessene Problem, die Fähigkeit einzugreifen, die Konsequenz), jede mit ihrer Quellenangabe. Diese Form – argumentierender Prosatext gefolgt von begründeten Karten – ist das Modell für alle Abschnitte (siehe „Schreibregeln“).

2. Das Produkt. Was es in wenigen Zahlen ist (Kapazität, Autonomie, Reichweite …), wie es nach Subsystemen funktioniert, seine Architektur, seine Hauptfunktionen, wie es sich weiterentwickelt (Familie, Plattform, verifizieren / rekonfigurieren / neu entwerfen) und was es nicht tut.

3. Nutzungsszenarien. Die Situationen, in denen das Produkt Mehrwert bieten kann, jeweils mit einem Code (S1, S2 …), um sie im restlichen Dokument zu zitieren. In jedem: wann es Mehrwert schafft, Grenze des Arguments, was zu messen ist und die dokumentarische Basis. Die Szenarien sind miteinander kompatibel; sie werden nicht als unabhängige Populationen summiert.

4. Evidenzen. Zuerst die Methode und der Umfang der Suche. Danach eine Karte pro Evidenz: Typ (Messung, Pilot, Leitfaden, Studie …), was sie mit ihrer Zahl aussagt, welche Szenarien sie betrifft und eine Lesart für das Projekt, die sagt, was sie untermauert und was nicht.

5. Was nachzuweisen ist. Der Schritt vom Dokument zum Pilot: priorisierte Phasen, jede mit ihrem Kreislauf, ihrem Grund und ihrer Bedingung für den Fortschritt; die erforderlichen Validierungen (technisch, operativ, wirtschaftlich); die Fortschrittsentscheidungen (Tore); die vorgeschlagene Entscheidung und wie sie gemessen wird.

6. Quellen und Referenzen. Alle Quellen mit Code nach Typ (z. B. E Evidenzen, F technische Datenblätter, P Preise, D Wirtschaft, C Klinik, M Dokumente des Projekts selbst), ihrer Herkunft, ihrem Link und dem Prüfdatum.

Optional

• Zweck und Werte (Mission, Vision und Werte), am Anfang, als eigener Abschnitt oder als Karten innerhalb des ersten. Für Projekte, die ein Team oder Mitarbeiter ausrichten möchten.
• Problemkosten, wenn es eine wirtschaftliche Dimension gibt: dokumentierte Fälle mit ihrer Zahl und ihrer „Implikation und Reichweite“, was vermieden werden kann und das Wirtschaftsmodell (eine Formel). Steht nach dem Entwicklungsgrund.
• Markt- oder Gebietsdimensionierung: was die Quellen zu sagen erlauben und was nicht, welche Daten fehlen (Nenner, Exposition, Wirtschaft), ein transparentes Szenario (kann einen eigenen Taschenrechner als Komponente enthalten) und wie daraus eine vertretbare Schätzung wird. Steht vor „Was nachzuweisen ist“.
• Vergleichsanhang mit einer vorhandenen Referenz: eine Karte pro Dimension, mit zwei Spalten („Referenz · veröffentlicht“ und „Projekt · Design“) und dem Beitrag jedes Ansatzes. Am Ende die Werte, die der Vergleich bewahren muss, und wie der Mehrwert überprüft wird.
• Datenblattanhang pro Element (Medikamente, Materialien, Komponenten, typische Kunden …): ein Datenblatt pro Element mit seinen Daten und Szenarien. Der Generator fügt eine Suchfunktion und einen Szenarienfilter hinzu.
• Auswirkungen: Was sich ändern würde, wenn das Produkt funktioniert, stets abhängig davon, was der Pilot zeigt. Eine Karte pro Dimension (wirtschaftlich, für die Menschen, für das Gebiet oder die Umgebung) mit „Was sich ändern kann“ und ihrem Indikator, messbar vorher und nachher. Der Einleitungsprosatext nennt die bereits existierende Basislinie und was noch zu messen ist; keine Einsparungszahl wird dem Projekt ohne diesen Vergleich zugeschrieben. Die SDGs, falls genannt, mit ihrem offiziellen Namen und ihrer Quelle. Steht nach den Problemkosten oder dem Bedarf.
• Risiken: Was schiefgehen kann und wie es gemindert wird. Eine Karte pro Risiko, mit seiner Klasse als Etikett (technisch, operativ, wirtschaftlich, regulatorisch), „Minderung“ und „Wird überprüft in“, das auf eine Phase oder ein Tor von „Was nachzuweisen ist“ verweist. Der Einleitungsprosatext nennt das Hauptrisiko und wie der Plan es früh erkennt. Was noch nicht analysiert wurde (z. B. die regulatorische Passung), wird als offenes Risiko deklariert, mit seinen Quellen, falls vorhanden. Steht unmittelbar vor „Was nachzuweisen ist“.
• Einladung zur Zusammenarbeit: Welche Profile gesucht werden, was geboten wird und was erwartet wird. Für Dokumente, die geteilt werden.

Schichtenlesung. Zuerst wird das Wichtigste kommuniziert, und jede folgende Schicht geht tiefer: Wer nur den ersten Teil liest, bekommt das Wesentliche, und wer mehr möchte, liest weiter. Die Reihenfolge ist nach Wichtigkeit, nicht nach der Entstehung der Schlussfolgerungen. Dies gilt für das gesamte Dokument und für jeden Abschnitt, der mit seiner Schlussfolgerung beginnt (siehe „Schreibregeln“) und die Details den Karten, den eingeklappten ####-Abschnitten und den Anhängen überlässt.

Falls das Projekt einen Abschnitt benötigt, der hier nicht aufgeführt ist, wird er dem Autor vorgeschlagen, bevor er geschrieben wird. Falls er für andere Projekte nützlich ist, ist er eine Verbesserung dieser Skill, die zur SF gehört: Sie wird nicht im Projekt notiert, sondern in einer Zeile erwähnt; in der SF selbst gehört sie zum Projekt.

Schreibregeln

• Nur die letzte Entscheidung. Das Dokument beschreibt den aktuellen Stand ohne Historie.
• Drei Arten von Aussagen, stets getrennt: veröffentlichte Fakten (mit Quellenangabe), Designziele des Projekts (was es tun soll) und Berechnungsannahmen (als illustrativ markiert). Ein Umfangskästchen am Anfang erklärt dies, und die Etiketten „veröffentlicht“ und „Design“ erinnern daran, wo sie verglichen werden.
• Jede Zahl oder Fachaussage wird vor dem Schreiben mit Quellen abgeglichen, niemals aus dem Gedächtnis, und trägt ihre Quellenangabe im selben Satz. Bei der Websuche ist die Erlaubnis des Autors einzuholen, falls nicht bereits erteilt.
• Jede Evidenz sagt auch, was sie nicht belegt. „Lesart für das Projekt“, „Grenze des Arguments“, „Implikation und Reichweite“: Das Dokument gewinnt an Glaubwürdigkeit, wenn es seine eigenen Grenzen markiert.
• Kompakt. Absätze von zwei bis drei Sätzen, Sätze mit etwa 20 Wörtern oder weniger, Abkürzungen werden beim ersten Mal erklärt. Der Kern wird in einem Zug gelesen; ausführliche Details gehen in die Anhänge.
• Ohne Füllwörter. Nichts über das Dokument selbst („Dieses Dokument muss aktualisiert werden …“, „Dieses Dokument enthält nicht …“) noch Selbstverständlichkeiten: Jeder Satz bringt etwas zum Projekt.
• Jeder Abschnitt beginnt mit argumentierender Prosa, wie der erste: etwa zwei bis drei Absätze, vor jeder Karte und ohne Untertitel, mit der Schlussfolgerung des Abschnitts, den sie stützenden Fakten mit Zahlen und Quellen, und dem, was noch unbekannt ist. Ein einleitender Satz („Sechs Erfahrungen erlauben …“) reicht nicht. Die These oder die Gesamtlesart steht in dieser Prosa, nicht in einem Kästchen. Die Karten kommen danach und liefern die nachschlagbaren Details, ohne das Argument zu wiederholen.
• Vollständige Sätze, keine Aufzählungen. Innerhalb jedes Unterabschnitts (###) wird mit Sätzen mit Verb geschrieben, die erklären, wie etwas funktioniert und warum, nicht mit verbindungslosen Aufzählungen („Identifikation, Inventar, Rückverfolgbarkeit …“). Die Unterabschnitte werden nach der Frage benannt, die sie beantworten („Wie es die Kälte hält“), nicht nach dem Muster „Thema: Unterthema“, und sie werden nicht in ####-Teile eines Absatzes zerlegt: #### bleibt für das Detail, das eingeklappt wird.
• Sichtbare Struktur, ohne den Lesefluss zu unterbrechen: Wann Karten, Prosa, Unterabschnitte, Kästchen, Tabellen oder Listen verwendet werden, sowie Fettdruck, wiederholte Felder und Typografie, sind in crear_documentos („Wann welche Ressource verwenden“) festgelegt. In einem Gründungsdokument sind typische Karten: Erfahrungen, Szenarien, Evidenzen, Phasen, Tore, Dimensionen eines Vergleichs, Datenblätter und die wichtigsten Zahlen des Produkts; in einer Bilanz wird das Funktionierende in Prosa erzählt, und Mängel werden in einer Tabelle mit dem, was passiert, und ihrem Status festgehalten.
• Keine Codes, die der Leser noch nicht kennt. Interne Codes (S1, S2 …) werden erst nach dem Abschnitt verwendet, der sie definiert, und dort, wo sie helfen, Querverweise herzustellen. Zuvor, und in der argumentierenden Prosa, wird mit Worten beschrieben („der Transport nach Hause und die Lagerung zu Hause“).
• Jede Schlüsselaussage wird an derselben Stelle begründet. Eine These oder wichtige Schlussfolgerung gibt an, worauf sie sich stützt (die Fakten des Dokuments mit Zahlen und Quellen) und was noch nicht nachgewiesen ist.
• Vorschläge, keine Vorgaben. „Es wird vorgeschlagen“, „zu bewerten“, „entscheidet, wer zuständig ist“.
• Respektiert die Empfindlichkeiten des Fachbereichs. Die Regeln des Projektfachbereichs sind in den Regeln seiner Identität (den gleichen, die documento_vision liest).

Wie gearbeitet wird

1. Lesen, bevor Vorschläge gemacht werden: die Vision des Projekts, seine Identität und Regeln, die Spezifikation, falls vorhanden, den Code oder den Zwilling, falls sie Zahlen liefern, und das vom Autor mitgebrachte Material. Inventarisieren aller Argumente des Projekts. Ein Gründungsdokument eines Produkts sammelt alle Argumente, die das Projekt hat, und mehr, wenn es mit anderen Produkten verglichen wird: die anderer Gründungsdokumente, der Vision, der Spezifikation und bereits Gebautem (ein digitaler Zwilling, ein Prototyp, Tests). Vor dem Schreiben oder Überprüfen wird ein Inventar dessen erstellt, was fehlt, mit seiner Quelle und seiner Klasse (veröffentlichter Fakt, Designziel, Annahme oder nur in Simulation verifizierter Fortschritt), sowie der Widersprüche zwischen Dokumenten, die vor der Weitergabe einer betroffenen Zahl beim Autor erfragt werden. Bereits Gebautes wird mit seinen deklarierten Grenzen berücksichtigt.
2. Das Inhaltsverzeichnis und die Werkzeuge vorschlagen: Fragen, ob das Dokument ein Artefakt für das Projekt oder für den Benutzer ist und welche Werkzeuge es enthalten soll (Suche, Notizen, „Lesart“, Einklappfunktion, Legende, Bearbeitung …), mit einer Empfehlung für diesen Zweck, in einer einzigen Frage mit Optionen; die Antwort in der Kopfzeile notieren. Das Inhaltsverzeichnis vorschlagen: den Kern, die zutreffenden optionalen Abschnitte mit Begründung, die Kandidatenszenarien mit ihrem Code und die Deckblattzahlen. Den Autor dies vor dem Schreiben verfeinern lassen.
3. Die fehlenden Evidenzen recherchieren (mit Erlaubnis zur Suche), mit genauer Quelle.
4. Das .md mit den untenstehenden Ressourcen schreiben und das .html generieren. Vor dem Ersetzen einer Version wird ein Backup in _respaldo/ erstellt (crear_documentos, „Backup“).
5. Überprüfen (siehe „Überprüfung“) und mit einer Zusammenfassung ausliefern: was es enthält, was illustrativ ist, welche Evidenzen fehlen und was ein Experte validieren sollte.
6. Mit dem Autor verfeinern. Jede allgemeine Korrektur wird den Regeln des Projekts hinzugefügt (über crear_documentos).

Überprüfung

Vor der Übergabe prüfen:

• Jede Zahl und jede Fachaussage hat eine Quellenangabe. Fehlt eine, wird sie entweder hinzugefügt oder die Aussage wird als Designziel oder Annahme markiert.
• Jede Evidenz sagt, was sie nicht belegt („Lesart“, „Grenze“ oder „Implikation“).
• Die argumentierende Prosa steht vor den Karten, enthält die Schlussfolgerung, die sie stützenden Fakten mit Zahlen und Quellen, und das, was noch unbekannt ist. Die Karten wiederholen das Argument nicht.
• Das Dokument ist kompakt – keine Füllwörter, keine Selbstverständlichkeiten, keine Verweise auf das Dokument selbst.
• Die Reihenfolge der Abschnitte folgt dem Schema: erklären (Produkt, Szenarien), dann rechtfertigen (Evidenzen, Pilot, Quellen).
• Es gibt keinen Widerspruch zwischen diesem und anderen Dokumenten (Vision, Spezifikation, anderen Gründungsdokumenten). Falls vorhanden, im Text als Designziel, Annahme oder offenes Risiko markiert.
• Der Pilot („Was nachzuweisen ist“) ist priorisiert, jede Phase hat eine Bedingung für den Fortschritt, und die Tore sind definiert.
• Die Quellen sind vollständig: Code, Herkunft, Link, Prüfdatum.
• Das .html wird aus dem .md generiert und das Backup vor dem Ersetzen gespeichert.
• Alles, was der Autor nicht vor dem Schreiben genehmigt hat, wird als Vorschlag markiert („zu bestätigen“), nicht als Tatsache.

Ressourcen

• Generator: crear_documentos
• Syntax, Variablen, Layout: crear_documentos („Syntax und Variablen“, „Layout und Typografie“)
• Wann Karten, Prosa, Tabellen, Kästchen, Listen und Abbildungen verwendet werden: crear_documentos („Wann welche Ressource verwenden“)
• Thema der Projektidentität: crear_documentos (Thema des Projekts, Marke, Farben usw.)