AI-Lab-for-Cities-at-Harvard/civic-skill-exchange

Einen Skill lokalisieren

Was dabei entsteht

Ein alleinstehendes Artefakt, plus die Aufzeichnung seiner Entstehung.

<skill-name>/                 ein gewöhnlicher Skill. Läuft sofort.
  SKILL.md                    Werte fest eingetragen, keine {{slots}}, kein TODO
  references/…  scripts/…     ebenso, durchgängig
<org>.context.yml             der ausgefüllte Kontext. Aufbewahren für spätere Neulokalisierung.
<org>.profile.yml             organisationsweite Antworten, bei jedem künftigen Skill wiederverwendbar
LOCALIZE-NOTES.md             was abgeleitet, erfragt, als Standard gesetzt oder nicht bestätigt wurde

Der lokalisierte Skill liest die Kontextdatei zur Laufzeit nicht. Werte werden direkt in den Body geschrieben. Ein Skill, der zur Laufzeit einen Kontext laden muss, um seine eigenen Feldnamen zu kennen, bezahlt diesen Aufwand bei jedem Aufruf und schlägt fehl, sobald die Datei verschoben wird – der Kontext ist die Aufzeichnung einer Entscheidung, keine Laufzeitabhängigkeit.

Lies references/contract.md für das Dateiformat, references/asking.md bevor du jemanden etwas fragst, und references/verify.md bevor du etwas zurückgibst.

Der entscheidende Fehler

Nicht die Anzahl der Fragen. Fragen, die der Adoptierende nicht beantworten kann.

Ein Skill, der einen Stadtsekretär nach einer Datenkennung und einem Schemafeldnamen fragt, wird nicht langsam ausgefüllt – er wird aufgegeben, und die Aufgabe sieht nach Desinteresse aus, nicht nach einem Designfehler. Das ist es, was einen Austausch im großen Maßstab scheitern lässt, und es ist eine Eigenschaft der Fragen, nicht der adoptierenden Person.

Also: Leite ab, was abgeleitet werden kann, frage nach der Organisation statt nach dem Skill, und lass die Antworten, die eine Organisation bereits gegeben hat, für jeden nachfolgenden Skill dienen.

Der zweite Fehler ist leiser. Ein Slot, der mit einem plausiblen falschen Wert gefüllt wird, erzeugt einen Skill, der läuft, Zahlen liefert, aber falsch ist. Schreibe niemals einen unbestätigten Wert in einen exact: true-Slot. Ein leerer Slot, der blockiert, ist behebbar; ein gefüllter Slot, der irreführt, nicht.

Schritte

1. Prüfe contract_version bevor du etwas anderes liest. Es ist der erste Schlüssel in der Kontextdatei. Vergleiche ihn mit der Version in references/contract.md.

Übereinstimmung ist der Normalfall – fahre fort und erwähne es nicht. Ist die Datei älter, migriere sie anhand des Changelogs und notiere, welche Einträge geändert wurden. Ist die Datei neuer, als dieser Skill versteht, stoppe. Fülle keinen Slot. Eine unbekannte breaking change bedeutet, dass jeder Wert in der Datei falsch interpretiert werden kann, und ein falsch interpretierter Wert wird zu einem plausiblen Fehler in einem Skill, der läuft und Zahlen liefert. Benenne die Lücke und fordere einen neueren localize-skill.

Gibt es keine contract_version, nimm nicht 1 an. Eine Datei, die vor der Versionierung geschrieben wurde, hat eine unbekannte Form, keine alte. Frage, was sie erzeugt hat.

2. Lese scope und sage es laut. Stelle vor jeder Frage dem Adoptierenden in einem Satz klar, auf welcher Ebene der Skill operiert und wie weit er verallgemeinert wurde: Dieser Skill wurde für Städte geschrieben und für andere US-Städte und Gemeinden verallgemeinert.

Ob sie in diesen Bereich fallen, ist eine Einschätzung, keine Suche, also lege es ihnen vor, anstatt es zu testen. Ein Adoptierender außerhalb des Bereichs sollte neu verallgemeinern statt ausfüllen: Die Slots sind das Einzige, was portabel gemacht wurde, und was stehengelassen wurde, ist von hier aus unsichtbar. Das Ausfüllen dieser Slots produziert einen Skill, der fertig aussieht und leise ein Land, ein Rechtssystem oder eine Regierungsform voraussetzt, die sie nicht haben.

Wenn die beibehaltenen Werte lokal wirken – ein Stadtname in einem Skill auf Bezirksebene – ist das funktionierender reach, kein Versehen. Sage das, bevor sie versuchen, es zu korrigieren.

3. Lade, was bereits bekannt ist. Bevor du etwas fragst, sammle die vorhandenen Antworten:

• <org>.profile.yml, falls diese Organisation bereits einen Skill adoptiert hat. Rechtsraum, die genehmigende Person, das Open-Data-Portal, das Geschäftsjahr sind für jeden Skill, den sie jemals adoptieren werden, gleich. Zweimal zu fragen ist der Weg, wie ein Austausch beim zweiten Skill Leute verliert.
• Werte, die ein anderer Slot impliziert. Eine Portal-Basis-URL und eine Datenkennung sind nicht zwei unabhängige Fragen.
• Standards, die durch scope festgelegt werden – Land, Währung, Postformat, gesetzliches System – die durch eine Ebene und Reichweite bereits bestimmt sind.

4. Leite ab, was abgeleitet werden kann, und bestätige es dann. Für Werte mit einer öffentlichen Quelle – Datenkennungen, Schemafeldnamen, Portal-Endpunkte, Abteilungsnamen – schlage sie vor. Deine 311-Eröffnungsdatum-Spalte scheint case_opened_dt zu sein. Korrekt? ist eine Frage, die jeder beantworten kann. Wie lautet deine 311-Eröffnungsdatum-Spalte? ist eine Frage, die fast niemand beantworten kann.

Das Bestätigen eines abgeleiteten Werts ist auch eine Frage, aber eine andere Art: Sie verlangt Wiedererkennen statt Erinnern, und Wiedererkennen ist es, was dies für jemanden nutzbar macht, der die Daten nicht aufgebaut hat. Ableitung entfernt niemals die Bestätigung für exact: true-Werte. Sie verschiebt die Last, nicht die Prüfung.

5. Frage nach dem Rest, einmal. Ein Batch, kein Tröpfeln. Ordne nach dem, was der Adoptierende am besten kennt: zuerst ihre Organisation, zuletzt ihre Daten. Überspringe alles, was bereits in Schritt 2 beantwortet wurde, und überspringe jeden Slot, dessen Zweig des Skills dieser Adoptierende nicht nutzen wird – ein optionaler Slot, der eifrig gefragt wird, ist von einem erforderlichen Slot nicht zu unterscheiden.

Passe die Frage an exact an. Wo es false ist, biete einen Standard an und sage, dass eine grobe Antwort in Ordnung ist; wir machen es informell, wer gerade da ist ist eine echte Antwort. Wo es true ist, sage, dass der Wert exakt übereinstimmen muss und warum, damit eine Vermutung erkennbar keine Option ist. references/asking.md enthält die Formulierungen, die funktionieren.

6. Schreibe die Werte ein. Ersetze überall – Body, Referenzen, Skripte, Dateinamen, Kommentare. Stelle dann das Frontmatter wieder her: description, civic.use-when und civic.avoid-when erhalten die organisationsspezifischen Versionen aus dem Kontext, da ein Agent diese liest, bevor ein Kontext geladen wird, und ein neutraler auf eine lokale Anfrage nicht reagieren wird.

Setze civic.localization: localized und civic.jurisdiction auf die Organisation. Entferne context.template.yml aus dem Skill-Verzeichnis. Was ausgeliefert wird, sollte wie ein Skill aussehen, den jemand für diese Organisation geschrieben hat, denn das ist es jetzt.

7. Schreibe die Aufzeichnung. <org>.context.yml mit jedem Wert und seiner Herkunft – Profil, abgeleitet, erfragt, als Standard gesetzt. <org>.profile.yml aktualisiert mit allem Organisationsweiten, damit der nächste Skill bereits größtenteils gefüllt startet. LOCALIZE-NOTES.md für das, was ohne Bestätigung als Standard gesetzt, als ungenutzt übersprungen oder vom Adoptierenden unsicher beantwortet wurde. Herkunft ist es, was es jemandem ermöglicht, später eine falsche Zahl zu prüfen, ohne das gesamte Gespräch zu wiederholen.

8. Überprüfe, bevor du es zurückgibst. references/verify.md. Ein Skill, der immer noch {{slot}} oder TODO enthält, ist nicht fertig, und ein Skill, dessen Werte nie bestätigt wurden, ist schlimmer als einer, der offensichtlich unfertig ist.

Vor dem Abschluss

• Die contract_version der Kontextdatei wurde überprüft, und kein Slot wurde aus einer Datei gefüllt, die neuer ist als dieser Skill versteht.
• Kein {{placeholder}} und kein TODO ist irgendwo erhalten geblieben, einschließlich Skripte, Referenzen, Dateinamen und Kommentare.
• Jeder exact: true-Wert wurde von einer Person bestätigt oder stammt aus den eigenen Systemen der Organisation. Keiner wurde abgeleitet und stillschweigend geschrieben.
• description, civic.use-when und civic.avoid-when nennen die Organisation und würden auf eine lokale Anfrage reagieren.
• Der Skill läuft ohne eine Kontextdatei zu lesen.
• LOCALIZE-NOTES.md listet jeden unbestätigten oder als Standard gesetzten Wert auf, und der Adoptierende hat diese Liste gesehen.
• <org>.profile.yml enthält alles Organisationsweite, damit der nächste Skill weniger fragt.