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

Localizar una habilidad

Qué produce esto

Un artefacto que se sostiene por sí solo, más el registro de cómo se hizo.

<nombre-habilidad>/                 una habilidad ordinaria. Funciona tal cual.
  SKILL.md                    valores escritos, sin {{slots}}, sin TODO
  referencias/…  scripts/…     lo mismo, en todo
<org>.context.yml             el contexto completado. Consérvalo para volver a localizar después.
<org>.profile.yml             respuestas a nivel de la organización, reutilizadas en cada habilidad futura
LOCALIZE-NOTES.md             lo que se derivó, preguntó, usó valores por defecto, no confirmó

La habilidad localizada no lee el archivo de contexto en tiempo de ejecución. Los valores se incorporan en el cuerpo. Una habilidad que debe cargar un contexto para conocer sus propios nombres de campo paga ese costo en cada invocación y falla de manera confusa cuando el archivo se mueve — el contexto es el registro de una decisión, no una dependencia en tiempo de ejecución.

Lee referencias/contract.md para conocer el formato del archivo, referencias/asking.md antes de preguntar algo a alguien, y referencias/verify.md antes de entregar cualquier cosa.

El fallo que importa

No la cantidad de preguntas. Preguntas que el adoptante no puede responder.

Una habilidad que le pide a un secretario municipal un identificador de conjunto de datos y un nombre de campo de esquema no se completa lentamente — se abandona, y el abandono parece desinterés en lugar de un defecto de diseño. Esto es lo que impide que un intercambio funcione a gran escala, y es una propiedad de las preguntas, no del adoptante.

Así que: deriva lo que se pueda derivar, pregunta sobre la organización más que sobre la habilidad, y deja que las respuestas que una organización ya ha dado sirvan para cada habilidad que adopte después.

El segundo fallo es más silencioso. Un espacio llenado con un valor plausible pero incorrecto produce una habilidad que se ejecuta, devuelve números y es incorrecta. Nunca escribas un valor no confirmado en un espacio exacto: true. Un espacio en blanco que bloquea es recuperable; un llenado que engaña no lo es.

Pasos

1. Verifica contract_version antes de leer cualquier otra cosa. Es la primera clave en el archivo de contexto. Compárala con la versión en referencias/contract.md.

Si coinciden es el caso normal — continúa y no digas nada al respecto. Si el archivo es más antiguo, migra según el registro de cambios y anota qué elementos cambiaron. Si el archivo es más nuevo de lo que esta habilidad entiende, detente. No llenes ningún espacio. Un cambio de ruptura desconocido significa que cualquier valor en el archivo podría malinterpretarse, y un valor malinterpretado se convierte en uno plausiblemente incorrecto en una habilidad que se ejecuta y devuelve números. Nombra la brecha y solicita una localizar-habilidad más reciente.

Si no hay contract_version, no asumas 1. Un archivo escrito antes de versionar tiene una forma desconocida, no una antigua. Pregunta qué lo produjo.

2. Lee scope, y dila en voz alta. Antes de cualquier pregunta, dile al adoptante en qué nivel opera la habilidad y qué tan lejos se generalizó para viajar, en una oración: esto fue escrito para ciudades y generalizado para otras ciudades y pueblos de Estados Unidos.

Que ellos estén dentro de ese alcance es un juicio, no una búsqueda, así que ponlo a su consideración en lugar de probarlo. Un adoptante fuera del alcance debería re-generalizar en lugar de llenar: los espacios son lo único que se hizo portable, y lo que quedó de pie es invisible desde aquí. Llenar esos espacios produce una habilidad que parece terminada y que asume silenciosamente un país, un sistema legal o una forma de gobierno que no tienen.

Si los valores retenidos parecen locales para ellos — un nombre de ciudad en una habilidad a nivel de distrito — eso es alcance funcionando, no un descuido. Dilo antes de que intenten corregirlo.

3. Carga lo que ya se sabe. Antes de preguntar nada, reúne las respuestas disponibles:

• <org>.profile.yml, si esta organización ha adoptado una habilidad antes. Jurisdicción, el funcionario aprobador, el portal de datos abiertos, el año fiscal son los mismos en cada habilidad que adopten. Preguntar dos veces es cómo un intercambio pierde gente en la segunda habilidad.
• Valores que otro espacio implica. Una URL base del portal y un identificador de conjunto de datos no son dos preguntas independientes.
• Valores por defecto determinados por scope — país, moneda, formato postal, régimen legal — que un nivel y alcance ya fijan.

4. Deriva lo que se pueda derivar, luego confírmalo. Para valores con una fuente pública — identificadores de conjuntos de datos, nombres de campos de esquema, endpoints del portal, nombres de departamentos — búscalos y propónlos. Tu columna de fecha de apertura del 311 parece ser case_opened_dt. ¿Correcto? es una pregunta que cualquiera puede responder. ¿Cuál es tu columna de fecha de apertura del 311? es una pregunta que casi nadie puede responder.

Confirmar un valor derivado también es una pregunta, pero es de otro tipo: pide reconocimiento en lugar de recuerdo, y el reconocimiento es lo que hace que esto sea utilizable por alguien que no construyó los datos. La derivación nunca elimina la confirmación para valores exacto: true. Mueve la carga, no la verificación.

5. Pregunta por el resto, una vez. Un solo lote, no un goteo. Ordena según lo que el adoptante conoce mejor: su organización primero, sus datos al final. Omite cualquier cosa ya respondida en el paso 2, y omite cualquier espacio cuya rama de la habilidad este adoptante no vaya a usar — un espacio opcional preguntado ansiosamente es indistinguible de uno obligatorio.

Haz coincidir la pregunta con exacto. Donde sea false, ofrece un valor por defecto y di que una respuesta aproximada está bien; lo hacemos informalmente, quien esté cerca es una respuesta real. Donde sea true, di que el valor debe coincidir exactamente y por qué, para que una suposición sea claramente no una opción. referencias/asking.md tiene las formas que funcionan.

6. Escribe los valores. Sustituye en todo — cuerpo, referencias, scripts, nombres de archivo, comentarios. Luego restaura el frontmatter: description, civic.usar-cuando y civic.evitar-cuando reciben las versiones específicas de la organización desde el contexto, porque un agente lee esos antes de que se cargue cualquier contexto y un neutro no se activará con una solicitud local.

Establece civic.localization: localizado y civic.jurisdiction a la organización. Elimina context.template.yml del directorio de la habilidad. Lo que se entregue debe verse como una habilidad que alguien escribió para esta organización, porque eso es lo que es ahora.

7. Escribe el registro. <org>.context.yml con cada valor y de dónde vino — perfil, derivado, preguntado, por defecto. <org>.profile.yml actualizado con cualquier cosa a nivel de la organización, para que la próxima habilidad comience casi completada. LOCALIZE-NOTES.md para lo que se usó por defecto sin confirmación, lo que se omitió como no utilizado, y cualquier cosa de la que el adoptante no estuviera seguro. La procedencia es lo que permite que alguien audite un número incorrecto más tarde sin rehacer la entrevista.

8. Verifica antes de entregarlo. referencias/verify.md. Una habilidad que aún contiene {{slot}} o TODO no está terminada, y una habilidad cuyos valores nunca se confirmaron es peor que una que está obviamente incompleta.

Antes de finalizar

• La contract_version del archivo de contexto fue verificada, y ningún espacio se llenó desde un archivo más reciente de lo que esta habilidad entiende.
• No sobrevive ningún {{placeholder}} ni TODO en ningún lugar, incluyendo scripts, referencias, nombres de archivo y comentarios.
• Cada valor exacto: true fue confirmado por una persona o provino de los sistemas propios de la organización. Ninguno fue inferido y escrito en silencio.
• description, civic.usar-cuando y civic.evitar-cuando nombran a la organización y se activarían con una solicitud local.
• La habilidad se ejecuta sin leer ningún archivo de contexto.
• LOCALIZE-NOTES.md lista cada valor no confirmado o usado por defecto, y el adoptante ha visto esa lista.
• <org>.profile.yml contiene todo lo a nivel de la organización, para que la próxima habilidad pregunte menos.