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

Localizar uma skill

O que isso produz

Um artefato independente, mais o registro de como foi feito.

<nome-da-skill>/                 uma skill comum. Funciona como está.
  SKILL.md                    valores escritos, sem {{slots}}, sem TODO
  references/…  scripts/…     o mesmo, em todo o lugar
<org>.context.yml             o contexto preenchido. Guarde para relocalizar depois.
<org>.profile.yml             respostas da organização, reutilizadas por toda skill futura
LOCALIZE-NOTES.md             o que foi derivado, perguntado, padronizado, não confirmado

A skill localizada não lê o arquivo de contexto em tempo de execução. Os valores vão diretamente no corpo. Uma skill que precisa carregar um contexto para saber seus próprios nomes de campo paga esse custo em toda invocação e falha de forma confusa quando o arquivo é movido — o contexto é o registro de uma decisão, não uma dependência de execução.

Leia references/contract.md para o formato do arquivo, references/asking.md antes de perguntar qualquer coisa a alguém, e references/verify.md antes de devolver qualquer coisa.

A falha que importa

Não é o número de perguntas. São as perguntas que o adotante não consegue responder.

Uma skill que pergunta a um funcionário municipal por um identificador de conjunto de dados e um nome de campo de esquema não é preenchida lentamente — é abandonada, e o abandono parece desinteresse em vez de um defeito de design. Isso é o que impede um intercâmbio de funcionar em escala, e é uma propriedade das perguntas, não do adotante.

Portanto: derive o que pode ser derivado, pergunte sobre a organização em vez de sobre a skill, e deixe que as respostas que uma organização já deu sirvam para toda skill que ela adotar depois.

A segunda falha é mais silenciosa. Um slot preenchido com um valor errado plausível produz uma skill que executa, retorna números e está errada. Nunca escreva um valor não confirmado em um slot exato: true. Um espaço em branco que bloqueia é recuperável; um preenchimento que engana não é.

Etapas

1. Verifique contract_version antes de ler qualquer outra coisa. É a primeira chave no arquivo de contexto. Compare com a versão em references/contract.md.

Correspondência é o caso comum — prossiga e não diga nada sobre isso. Se o arquivo for mais antigo, migre-o com base no changelog e anote quais entradas mudaram. Se o arquivo for mais novo do que esta skill entende, pare. Não preencha nenhum slot. Uma mudança desconhecida que quebra a compatibilidade significa que qualquer valor no arquivo pode ser mal interpretado, e um valor mal interpretado se torna um valor errado plausível em uma skill que executa e retorna números. Nomeie a lacuna e peça uma localize-skill mais recente.

Se não houver contract_version, não assuma 1. Um arquivo escrito antes do versionamento tem uma forma desconhecida, não antiga. Pergunte o que o produziu.

2. Leia scope e diga em voz alta. Antes de qualquer pergunta, diga ao adotante em que nível a skill opera e até onde foi generalizada para viajar, em uma frase: isso foi escrito para cidades e generalizado para outras cidades e vilas dos EUA.

Se eles estão dentro desse alcance é um julgamento, não uma consulta, então coloque isso para eles em vez de testar. Um adotante fora do alcance deve regeneralizar em vez de preencher: os slots são as únicas coisas tornadas portáteis, e o que foi deixado de pé é invisível daqui. Preencher esses slots produz uma skill que parece completa e assume silenciosamente um país, um sistema jurídico ou uma forma de governo que eles não têm.

Se os valores retidos parecerem locais para eles — um nome de cidade em uma skill de nível distrital — isso é o reach funcionando, não um descuido. Diga isso antes que eles tentem corrigir.

3. Carregue o que já é conhecido. Antes de perguntar qualquer coisa, monte as respostas disponíveis:

• <org>.profile.yml, se esta organização já adotou uma skill antes. Jurisdição, o oficial aprovador, o portal de dados abertos, o ano fiscal são os mesmos em todas as skills que eles adotarão. Perguntar duas vezes é como um intercâmbio perde pessoas na segunda skill.
• Valores que outro slot implica. Uma URL base de portal e um identificador de conjunto de dados não são duas perguntas independentes.
• Padrões definidos por scope — país, moeda, formato postal, regime estatutário — que um nível e alcance já fixam.

4. Derive o que pode ser derivado, depois confirme. Para valores com uma fonte pública — identificadores de conjunto de dados, nomes de campos de esquema, endpoints de portal, nomes de departamentos — pesquise e proponha eles. Sua coluna de data de abertura do 311 parece ser case_opened_dt. Correto? é uma pergunta que qualquer um pode responder. Qual é a sua coluna de data de abertura do 311? é uma pergunta que quase ninguém consegue responder.

Confirmar um valor derivado também é uma pergunta, mas é um tipo diferente: pede reconhecimento em vez de lembrança, e o reconhecimento é o que torna isso utilizável por alguém que não construiu os dados. A derivação nunca remove a confirmação para valores exato: true. Ela move o fardo, não a verificação.

5. Pergunte pelo resto, de uma vez. Um lote, não um gotejamento. Ordene pelo que o adotante conhece melhor: sua organização primeiro, seus dados por último. Pule qualquer coisa já respondida na etapa 2, e pule qualquer slot cujo ramo da skill este adotante não usará — um slot opcional perguntado ansiosamente é indistinguível de um obrigatório.

Combine a pergunta com exato. Onde for false, ofereça um padrão e diga que uma resposta aproximada está ok; fazemos informalmente, quem estiver por perto é uma resposta real. Onde for true, diga que o valor deve corresponder exatamente e por quê, para que um palpite seja reconhecidamente não uma opção. references/asking.md tem as formas que funcionam.

6. Escreva os valores. Substitua em todo o lugar — corpo, referências, scripts, nomes de arquivos, comentários. Em seguida, restaure o frontmatter: description, civic.use-when e civic.avoid-when recebem as versões específicas da organização do contexto, porque um agente lê esses antes de qualquer contexto ser carregado e um neutro não será acionado em uma solicitação local.

Defina civic.localization: localized e civic.jurisdiction para a organização. Remova context.template.yml do diretório da skill. O que é enviado deve parecer uma skill que alguém escreveu para esta organização, porque agora é o que é.

7. Escreva o registro. <org>.context.yml com cada valor e de onde veio — perfil, derivado, perguntado, padronizado. <org>.profile.yml atualizado com qualquer coisa da organização, para que a próxima skill comece quase preenchida. LOCALIZE-NOTES.md para o que foi padronizado sem confirmação, o que foi pulado como não utilizado, e qualquer coisa sobre a qual o adotante estava inseguro. Proveniência é o que permite que alguém audite um número errado depois sem refazer a entrevista.

8. Verifique antes de devolver. references/verify.md. Uma skill que ainda contém {{slot}} ou TODO não está terminada, e uma skill cujos valores nunca foram confirmados é pior do que uma que está obviamente inacabada.

Antes de terminar

• A contract_version do arquivo de contexto foi verificada, e nenhum slot foi preenchido a partir de um arquivo mais novo do que esta skill entende.
• Nenhum {{placeholder}} e nenhum TODO sobrevive em nenhum lugar, incluindo scripts, referências, nomes de arquivos e comentários.
• Todo valor exato: true foi confirmado por uma pessoa ou veio dos próprios sistemas da organização. Nenhum foi inferido e escrito silenciosamente.
• description, civic.use-when e civic.avoid-when nomeiam a organização e seriam acionados em uma solicitação local.
• A skill executa sem ler nenhum arquivo de contexto.
• LOCALIZE-NOTES.md lista todo valor não confirmado ou padronizado, e o adotante viu essa lista.
• <org>.profile.yml contém tudo que é da organização, para que a próxima skill pergunte menos.