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

Localiser une compétence

Ce que cela produit

Un artefact autonome, plus l'enregistrement de sa création.

<nom-compétence>/                 une compétence ordinaire. Fonctionne telle quelle.
  SKILL.md                    valeurs écrites, pas de {{slots}}, pas de TODO
  references/…  scripts/…     pareil, partout
<org>.context.yml             le contexte rempli. Conservez-le pour re-localiser plus tard.
<org>.profile.yml             réponses à l'échelle de l'org., réutilisées pour chaque future compétence
LOCALIZE-NOTES.md             ce qui a été dérivé, demandé, par défaut, non confirmé

La compétence localisée ne lit pas le fichier de contexte à l'exécution. Les valeurs sont écrites directement dans le corps. Une compétence qui doit charger un contexte pour connaître ses propres noms de champs paie ce coût à chaque appel et échoue de manière confuse lorsque le fichier est déplacé — le contexte est l'enregistrement d'une décision, pas une dépendance d'exécution.

Lisez references/contract.md pour le format du fichier, references/asking.md avant de poser des questions, et references/verify.md avant de remettre quoi que ce soit.

L'échec qui compte

Pas le nombre de questions. Les questions auxquelles l'adoptant ne peut pas répondre.

Une compétence qui demande à un secrétaire de mairie un identifiant de jeu de données et un nom de champ de schéma ne sera pas remplie lentement — elle sera abandonnée, et l'abandon ressemblera à un désintérêt plutôt qu'à un défaut de conception. C'est ce qui empêche un échange de fonctionner à grande échelle, et c'est une propriété des questions, pas de l'adoptant.

Donc : dérivez ce qui peut être dérivé, interrogez sur l'organisation plutôt que sur la compétence, et laissez les réponses déjà données par une organisation servir à chaque compétence qu'elle adoptera par la suite.

Le second échec est plus discret. Un emplacement rempli avec une valeur plausible mais erronée produit une compétence qui s'exécute, renvoie des chiffres, et est fausse. N'écrivez jamais une valeur non confirmée dans un emplacement exact: true. Un blanc qui bloque est récupérable ; un remplissage qui induit en erreur ne l'est pas.

Étapes

1. Vérifiez contract_version avant de lire quoi que ce soit d'autre. C'est la première clé du fichier de contexte. Comparez-la à la version dans references/contract.md.

Si elle correspond, c'est le cas normal — continuez, et ne dites rien. Si le fichier est plus ancien, migrez-le en fonction du journal des modifications et notez les entrées qui ont changé. Si le fichier est plus récent que ce que cette compétence comprend, arrêtez-vous. Ne remplissez aucun emplacement. Un changement non rétrocompatible inconnu signifie que toute valeur du fichier peut être mal interprétée, et une valeur mal interprétée devient une valeur plausible mais erronée dans une compétence qui s'exécute et renvoie des chiffres. Nommez l'écart et demandez une version plus récente de localize-skill.

S'il n'y a pas de contract_version, ne supposez pas 1. Un fichier écrit avant le versionnage a une forme inconnue plutôt qu'ancienne. Demandez ce qui l'a produit.

2. Lisez scope et énoncez-le à voix haute. Avant toute question, dites à l'adoptant à quel niveau la compétence opère et à quel degré elle a été généralisée pour voyager, en une phrase : celle-ci a été écrite pour les villes et généralisée pour d'autres villes et communes américaines.

S'ils se situent dans ce périmètre est un jugement, pas une recherche, donc soumettez-le-leur plutôt que de le tester. Un adoptant en dehors du périmètre devrait re-généraliser plutôt que remplir : les emplacements sont les seules choses rendues portables, et ce qui a été laissé de côté est invisible d'ici. Remplir ces emplacements produit une compétence qui a l'air terminée et suppose silencieusement un pays, un système juridique ou une forme de gouvernement qu'ils n'ont pas.

Si les valeurs conservées semblent locales pour eux — un nom de ville dans une compétence de niveau quartier — c'est le reach qui fonctionne, pas un oubli. Dites-le avant qu'ils n'essaient de le corriger.

3. Chargez ce qui est déjà connu. Avant de poser des questions, rassemblez les réponses disponibles :

• <org>.profile.yml, si cette organisation a déjà adopté une compétence. La juridiction, le responsable approbateur, le portail de données ouvertes, l'exercice fiscal sont les mêmes pour toutes les compétences qu'ils adopteront. Poser deux fois une question, c'est ainsi qu'un échange perd des gens dès la deuxième compétence.
• Les valeurs qu'un autre emplacement implique. Une URL de base de portail et un identifiant de jeu de données ne sont pas deux questions indépendantes.
• Les valeurs par défaut fixées par scope — pays, devise, format postal, régime légal — qu'un niveau et un périmètre déterminent déjà.

4. Dérivez ce qui peut être dérivé, puis confirmez-le. Pour les valeurs ayant une source publique — identifiants de jeux de données, noms de champs de schéma, points d'accès de portail, noms de départements — cherchez-les et proposez-les. Votre colonne de date d'ouverture du 311 semble être case_opened_dt. Correct ? est une question à laquelle tout le monde peut répondre. Quelle est votre colonne de date d'ouverture du 311 ? est une question à laquelle presque personne ne peut répondre.

Confirmer une valeur dérivée est aussi une question, mais d'un type différent : elle demande une reconnaissance plutôt qu'un rappel, et la reconnaissance est ce qui rend cela utilisable par quelqu'un qui n'a pas construit les données. La dérivation ne supprime jamais la confirmation pour les valeurs exact: true. Elle déplace la charge, pas la vérification.

5. Demandez le reste, en une seule fois. Un lot, pas un goutte-à-goutte. Ordre par ce que l'adoptant connaît le mieux : d'abord leur organisation, puis leurs données en dernier. Sautez tout ce qui a déjà été répondu à l'étape 2, et sautez tout emplacement dont la branche de la compétence ne sera pas utilisée par cet adoptant — un emplacement optionnel demandé avec empressement est impossible à distinguer d'un obligatoire.

Faites correspondre la question à exact. Quand c'est false, proposez une valeur par défaut et dites qu'une réponse approximative est acceptable ; nous faisons ça de manière informelle, avec qui est là est une vraie réponse. Quand c'est true, dites que la valeur doit correspondre exactement et pourquoi, afin qu'une supposition soit clairement reconnue comme non une option. references/asking.md contient les formes qui fonctionnent.

6. Écrivez les valeurs. Substituez partout — corps, références, scripts, noms de fichiers, commentaires. Puis restaurez le préambule : description, civic.use-when et civic.avoid-when obtiennent les versions spécifiques à l'organisation issues du contexte, car un agent lit ceux-ci avant tout chargement de contexte et un neutre ne se déclenchera pas sur une demande locale.

Définissez civic.localization: localized et civic.jurisdiction sur l'organisation. Supprimez context.template.yml du répertoire de la compétence. Ce qui est livré doit ressembler à une compétence que quelqu'un a écrite pour cette organisation, car c'est désormais ce que c'est.

7. Écrivez l'enregistrement. <org>.context.yml avec chaque valeur et sa provenance — profil, dérivée, demandée, par défaut. <org>.profile.yml mis à jour avec tout ce qui est à l'échelle de l'organisation, pour que la prochaine compétence commence déjà presque remplie. LOCALIZE-NOTES.md pour ce qui a été mis par défaut sans confirmation, ce qui a été sauté comme inutilisé, et tout ce dont l'adoptant n'était pas sûr. La provenance est ce qui permet à quelqu'un de vérifier un nombre erroné plus tard sans refaire l'entretien.

8. Vérifiez avant de remettre. references/verify.md. Une compétence qui contient encore {{slot}} ou TODO n'est pas terminée, et une compétence dont les valeurs n'ont jamais été confirmées est pire qu'une compétence qui est manifestement inachevée.

Avant de terminer

• La contract_version du fichier de contexte a été vérifiée, et aucun emplacement n'a été rempli à partir d'un fichier plus récent que ce que cette compétence comprend.
• Aucun {{placeholder}} ni TODO ne subsiste nulle part, y compris dans les scripts, références, noms de fichiers et commentaires.
• Chaque valeur exact: true a été confirmée par une personne ou provient des propres systèmes de l'organisation. Aucune n'a été déduite et écrite silencieusement.
• description, civic.use-when et civic.avoid-when nomment l'organisation et se déclencheraient sur une demande locale.
• La compétence s'exécute sans lire de fichier de contexte.
• LOCALIZE-NOTES.md liste chaque valeur non confirmée ou mise par défaut, et l'adoptant a vu cette liste.
• <org>.profile.yml contient tout ce qui est à l'échelle de l'organisation, afin que la prochaine compétence pose moins de questions.