§ 1Cuándo usarlos, y cuándo no
Para consultar los dieciséis parlamentos no hacen falta: el servidor MCP descarga los conjuntos ya construidos. Los skills sirven para otra cosa:
- Un corpus que no existe. Otra cámara (un senado, un parlamento regional), otro país u otro periodo, a partir de sus diarios de sesiones.
- Reproducir o auditar uno publicado. Los skills son el método con el que se construyeron los dieciséis, y cada decisión de la construcción quedó registrada con su evidencia.
- Una pieza suelta. El OCR local de unos PDF escaneados, o el etiquetado de oradores de unas actas, sin llegar a la matriz.
Antes de empezar, tres cosas. Claude Code es quien orquesta: lee cada SKILL.md, ejecuta el código de diaries-lib,
razona sobre los casos ambiguos y te pregunta. No es un programa que se lanza y termina: cada país del corpus pasó por
revisiones a mano y por decisiones que hubo que tomar y registrar. Y los skills recogen la experiencia de construir los
dieciséis corpus y conservan referencias a ese proceso: identificadores de decisiones como tr-0109, países de
ejemplo y scripts propios de algunos países que no están en el repositorio. Son el método tal como se aplicó, no un
producto genérico, y están escritos en español.
§ 2El recorrido
Las fuentessource/{iso2}/raw/ PDF escaneado o digital, HTML, XML, DOCX o texto
Preparar el país
Del documento al texto
Sesiones y oradores
Diputados y vinculación
La entrega
Se publica{ISO2}_interventions.csv {ISO2}_deputies.csv en Harvard Dataverse, de donde los carga download_country
Trece skills en orden, agrupados en cinco tramos. Cada uno lee una carpeta de source/{iso2}/ y escribe otra, y
ninguno sobrescribe lo anterior: si un paso falla, se corrige y se repite desde ahí. extracted/ es la capa fiel, el
texto tal como salió de la fuente, y no se limpia nunca; la limpieza es solo cosa de correct.
El orden tiene tres matices que conviene saber antes de empezar:
ocrsolo trabaja si el PDF es una imagen. Con un PDF digital, HTML o XML, se salta.metaydedupevan antes detag. El etiquetado ordena las formas de los marcadores de orador por su frecuencia en todo el corpus para decidir cuáles entran en su léxico; una sesión duplicada las cuenta dos veces, y deduplicar después ya no corrige esa decisión.deputiespuede ir antes detagsi las actas traen pase de lista nominal: el registro sale entonces del texto corregido y ayuda a reconocer a los oradores.
La entrega son dos archivos: {ISO2}_interventions.csv, con las 16 columnas canónicas, y {ISO2}_deputies.csv, el
registro de diputados, que se une al primero por id_dep y la legislatura. Son los que se publican en Harvard
Dataverse y los que download_country carga en tu ordenador:
id_session · id_int · legislature · legislative_session · session_number · date · session_type · intervention_order
speaker_raw · id_dep · speaker_name · sex · party · district · dm_speech · textLos otros ocho skills no tienen turno. Se usan en cualquier momento para ver el estado, revisar y corregir, validar, registrar una decisión, escribir el informe, aprender el sistema o mejorar un skill.
§ 3AUTO, FLAG, HALT: cuándo te pregunta
Casi todos los pasos calculan una confianza entre 0 y 1 y la comparan con dos umbrales. Por encima del primero, AUTO: sigue sin
preguntar. Entre los dos, FLAG: sigue, pero apunta el caso para que lo revises. Por debajo del segundo, HALT: se
detiene hasta que intervengas. Los umbrales están en la configuración de cada país (country_config/{iso2}.yaml) y
pueden ajustarse; estos son los de la plantilla:
| Skill | AUTO | FLAG | HALT |
|---|---|---|---|
diaries-tag |
≥ 0,80 | ≥ 0,60 | < 0,60 |
diaries-match |
≥ 0,90 | ≥ 0,70 | < 0,70 |
| los demás | ≥ 0,85 | ≥ 0,65 | < 0,65 |
Dos pasos tienen umbrales propios. match exige más: una vinculación equivocada pone las palabras de una persona a
nombre de otra, con su partido y su sexo. tag admite una confianza algo menor, pero tiene una regla que no depende de
ella: una sola marca de orador sin etiquetar detiene la sesión, porque atribuiría en silencio
la intervención entera al orador anterior. Cada ficha del § 6 dice qué mide la confianza de su paso.
Los casos pendientes se revisan con /diaries-review: para cada FLAG muestra la evidencia y la confianza, y tú
aceptas, corriges, lo escalas a HALT o lo dejas para más tarde. Un error que se repite se corrige una sola vez con
/diaries-feedback: para una sesión, como regla desde una fecha o para todo el skill.
/diaries-status --country {iso2}
/diaries-review --country {iso2}§ 4El registro de decisiones
Las decisiones importantes de un corpus se toman en el momento y se olvidan después: un umbral, una definición, unas
filas que se apartan, una fuente que se prefiere a otra. /diaries-decide las guarda cuando se toman, con cuatro
campos: la decisión, las alternativas, la evidencia y la consecuencia. La evidencia es obligatoria y dice qué se midió,
sobre qué y qué salió; si no se midió nada, se dice así, y eso también sirve. Lo que no se guarda es una preferencia
presentada como hallazgo:
- ✗ «Se eligió este umbral.»
- ✓ «Se eligió este umbral porque, en una muestra leída a mano, separaba las filas que había que apartar de las que había que dejar; con uno más bajo se apartaban filas buenas.»
Una decisión superada no se borra: --supersede la marca y la enlaza con la que la corrige, y esa cadena es la
historia de las correcciones del corpus. Las decisiones de un país van a state/{iso2}/decisions.jsonl, y las que
valen para todos, a state/_transversal/. Al final, /diaries-report escribe el informe interno del proceso,
docs/{iso2}/pipeline_report.md: cronología, confianzas, correcciones, tasa de automatización y lo que queda abierto.
Tres skills registran cosas distintas:
| Skill | Qué registra |
|---|---|
/diaries-decide |
el razonamiento: por qué se hizo algo y con qué evidencia |
/diaries-feedback |
la acción: una corrección que el pipeline aplica |
/diaries-refine |
el comportamiento: un cambio en un SKILL.md |
§ 5Por dónde empezar
- Instala los skills y prepara la carpeta del proyecto, con los dos comandos del principio de la página.
- Copia los diarios de un país en
source/{iso2}/raw/, un archivo por sesión. Si se llaman por su fecha (AAAA-MM-DD.pdfo.html), te ahorras preguntas. - Abre Claude Code en la carpeta del proyecto y pide la guía con
/diaries-teach. Su camino 2, «Nuevo país desde cero», recorre los cinco tramos y se ofrece a acompañarte en el primer paso. - Configura el país con
/diaries-bootstrap --country {iso2}, que examina de tres a cinco documentos y te pregunta solo lo que no pudo inferir. - Sigue la cadena, y revisa con
/diaries-reviewcada vez que un paso deje casos en FLAG:
/diaries-ocr --country {iso2} --all
/diaries-extract --country {iso2} --all
/diaries-correct --country {iso2} --all
/diaries-meta --country {iso2} --all
/diaries-dedupe --country {iso2}
/diaries-tag --country {iso2} --all
/diaries-matrix --country {iso2} --all
/diaries-deputies --country {iso2}
/diaries-match --country {iso2}
/diaries-merge --country {iso2}
/diaries-standardize --country {iso2}
/diaries-document --country {iso2}
/diaries-report --country {iso2}Si la cadena se detiene, /diaries-status dice dónde y cuál es el siguiente paso pendiente; /diaries-review resuelve
los casos abiertos, y se sigue desde el skill que se detuvo.
La guía Un país desde cero recorre esta cadena entera sobre cuatro sesiones de Bolivia, un país que no está en ParlaIbero: lo que preguntó cada skill, lo que se comprobó a mano y lo que salió mal.
La documentación técnica completa de los skills, escrita durante la construcción y solo en español, detalla cada
fórmula de confianza, cada control y cada regla de parada: el índice de los 21 skills
y el árbol de procedimiento. Conservan referencias al
proyecto en que se construyó el corpus, como scripts que no están en el repositorio; donde algo no coincida, mandan los
SKILL.md.
§ 6Las 21 fichas
Cada ficha dice qué hace el skill, qué lee y qué escribe, qué mide su confianza y cómo se invoca, junto a la
descripción con la que Claude Code decide cuándo usarlo: por eso un skill también se puede pedir con palabras
(«revisa los casos pendientes de Chile»). Las rutas son relativas a la carpeta del proyecto; {iso2} es el código del
país en minúsculas, {ISO2} en mayúsculas, e {id}, el de la sesión.
Ningún skill coincide.
Paso 1 · Preparar el país
/diaries-bootstrapExamina de tres a cinco documentos, infiere la configuración del país y te pregunta solo lo que no pudo inferir.
Lo que lee el agenteConfigura un país nuevo: detecta trabajo ya realizado en carpetas intermedias, infiere la config desde archivos fuente, entrevista al usuario para confirmar lo que falta, e inicializa el estado del pipeline reflejando la situación real.
- Paso
- 1 de 13
- Lee
source/{iso2}/raw/- Escribe
country_config/{iso2}.yamlstate/{iso2}/pipeline_state.jsondocs/{iso2}/onboarding_report.md- Confianza
- La parte de los campos que infirió con una confianza de 0,80 o más.
Infiere el formato (PDF de imagen o digital, HTML…), los marcadores de orador, las fechas y la numeración, y muestra la evidencia antes de preguntar. Detecta el trabajo ya hecho en las carpetas intermedias. Una vez por país; --force regenera la configuración.
Se invoca
/diaries-bootstrap --country {iso2}Pasos 2–4 · Del documento al texto
/diaries-ocrOCR local con Ollama para los PDF escaneados; se salta cuando el PDF ya trae texto o la fuente es HTML. solo PDF escaneados
Lo que lee el agenteAplica OCR con Ollama a sesiones en formato pdf_image o pdf_poor_ocr y actualiza el estado del pipeline.
- Paso
- 2 de 13
- Lee
source/{iso2}/raw/{id}.pdf- Escribe
source/{iso2}/ocr/{id}/page_NNNN.txt- Confianza
- 0,7 × la media de las páginas + 0,3 × la peor página: una sola página muy degradada baja la sesión.
El modelo principal es LightOnOCR-2:1b y el de respaldo glm-ocr, los dos configurables por país. Tras cada lote mide la «ñ» rota (seflor, sefior, senor…): si pasa del 1 o 2 %, conviene pasar al modelo de respaldo en esas sesiones y registrar las variantes para que correct y tag las toleren.
Se invoca
/diaries-ocr --country {iso2} --all
/diaries-ocr --country {iso2} --session {id}/diaries-extractReúne el OCR, el PDF digital, el HTML, el XML, el DOCX o el texto en un texto de trabajo fiel, con las marcas de página. No limpia nada.
Lo que lee el agenteConsolida el raw (OCR/PDF digital/HTML/XML/DOCX/texto) en un texto de trabajo FIEL con marcadores de página. NO limpia: la limpieza (cabeceros, mobiliario, hifenización, reflujo) es de diaries-correct.
- Paso
- 3 de 13
- Lee
source/{iso2}/raw/{id}.*source/{iso2}/ocr/{id}/- Escribe
source/{iso2}/extracted/{id}.txt- Confianza
- La proporción de caracteres Unicode válidos. Además mide, sin corregirlos, la fragmentación por columnas y los prefijos de orador ilegibles.
extracted/ es la capa a la que siempre se puede volver, y por eso no se limpia nunca: cabeceros, guiones y párrafos son cosa de correct.
Se invoca
/diaries-extract --country {iso2} --all/diaries-correctEl único limpiador: quita cabeceros y pies de página, aísla los marcadores de orador, deshace los guiones de final de línea y rehace los párrafos.
Lo que lee el agenteCorrige párrafos e hifenaciones en texto extraído: pase determinista vía script + resolución LLM de saltos ambiguos.
- Paso
- 4 de 13
- Lee
source/{iso2}/extracted/{id}.txt- Escribe
source/{iso2}/corrected/{id}.txt- Confianza
- 0,95 si conserva al menos el 80 % de los caracteres; si no, 0,60, y la sesión queda en revisión.
Lo que se quita se descubre por frecuencia, década a década, y se guarda en la configuración del país: descubrir, aplicar, medir lo que queda, refinar. Si en una sesión desaparece más del 2 % de los marcadores de orador, se detiene. El preámbulo de la sesión no se borra nunca.
Se invoca
/diaries-correct --country {iso2} --allPasos 5–8 · Sesiones y oradores
/diaries-metaSaca de cada cabecero la fecha, el número, el tipo de sesión, la legislatura y quién preside, por tramos: la apertura y cada relevo. antes de tag
Lo que lee el agenteExtrae metadatos de sesión (fecha, número, tipo, legislatura y la PRESIDENCIA — uno o varios presidentes por TRAMO) y escribe el JSON por sesión. NO asume formato: usa la heurística registrada del país o la DESCUBRE y la registra.
- Paso
- 5 de 13
- Lee
source/{iso2}/extracted/{id}.txt- Escribe
source/{iso2}/meta/{id}.json- Confianza
- Los campos extraídos de cinco: fecha, número, tipo, presidencia y legislatura.
Lee extracted/ porque correct borra los cabeceros. No supone un formato: usa la regla registrada del país o la descubre y la registra. Sin fecha, deriva al menos el año del identificador; nunca inventa el día ni el mes.
Se invoca
/diaries-meta --country {iso2} --all/diaries-dedupeAparta las sesiones duplicadas: la misma sesión bajo dos identificadores, o una sesión con las filas dobladas. antes de tag
Lo que lee el agenteDetecta y pone en cuarentena sesiones DUPLICADAS, en sus dos clases: (A) la misma sesión catalogada bajo >1 session_id, y (B) una sola sesión con las filas dobladas por ingesta multi-track. Se ejecuta DESPUÉS de diaries-meta y ANTES de diaries-tag: evita el doble conteo y que el inventario estructural del tagging se calibre sobre formas contadas dos veces.
- Paso
- 6 de 13
- Lee
source/{iso2}/corrected/source/{iso2}/meta/- Escribe
source/{iso2}/_quarantine_duplicates/- Confianza
- No puntúa: aplica una regla. Clase A, mismo boletín y misma fecha real; clase B, filas dobladas con un solapamiento del 25 % o más.
Sin --write solo informa. La cuarentena es reversible y la clase B pide confirmación. Va antes de tag porque el etiquetado calibra su léxico con la frecuencia de cada forma, y un duplicado la cuenta dos veces.
Se invoca
/diaries-dedupe --country {iso2}
/diaries-dedupe --country {iso2} --write/diaries-tagMarca dónde empieza cada intervención y quién habla: expresiones regulares en dos niveles, y Claude para los casos dudosos. crítico · 0,80 / 0,60
Lo que lee el agenteEtiqueta oradores en texto corregido: pase regex determinista + resolución LLM de spans sospechosos. Skill crítico con umbrales más bajos.
- Paso
- 7 de 13
- Lee
source/{iso2}/corrected/{id}.txt- Escribe
source/{iso2}/tagged/{id}.txt- Confianza
- Las intervenciones etiquetadas por regla frente al total, contando en contra las que quedan sin etiqueta y la duda de las que resolvió Claude. AUTO ≥ 0,80 · FLAG ≥ 0,60
Las formas de los marcadores se descubren en el corpus, no se suponen. Una sola marca sin etiquetar detiene la sesión, sea cual sea la confianza: atribuiría en silencio la intervención entera al orador anterior.
Se invoca
/diaries-tag --country {iso2} --all
/diaries-tag --country {iso2} --session {id} --dry-run/diaries-matrixConvierte cada intervención etiquetada en una fila con los metadatos de su sesión; lo anterior al primer orador entra como fila 0.
Lo que lee el agenteConvierte texto etiquetado en matriz de intervenciones CSV
- Paso
- 8 de 13
- Lee
source/{iso2}/tagged/{id}.txtsource/{iso2}/meta/{id}.json- Escribe
source/{iso2}/matrix/interventions_raw.csv- Confianza
- 1 − bloques sin orador / bloques.
No arranca mientras una sesión de tag esté detenida. Si más del 0,1 % de las filas llevan dentro el marcador de otro orador, no se parchea la tabla: se corrige el origen y se repite desde correct. Los anexos solo dejan de contar como discurso donde el acta los separa.
Se invoca
/diaries-matrix --country {iso2} --allPasos 9–11 · Diputados y vinculación
/diaries-deputiesConstruye el registro de diputados: de un archivo externo, del pase de lista nominal o de los oradores de la matriz. o antes de tag
Lo que lee el agenteConstruye o actualiza la base de datos de diputados
- Paso
- 9 de 13
- Lee
source/{iso2}/matrix/interventions_raw.csv- Escribe
source/{iso2}/deputies/deputies.csvsource/{iso2}/standardize/{ISO2}_deputies.csv- Confianza
- 1 − diputados ambiguos / diputados.
El archivo externo se declara en la configuración del país (deputies.external_file). El sexo es una variable derivada y declara de dónde sale. Si las actas traen pase de lista, el registro puede salir de corrected/ antes de tag y mejorar su puntuación.
Se invoca
/diaries-deputies --country {iso2}/diaries-matchVincula cada nombre de orador con un diputado: coincidencia exacta, después difusa y, para lo que queda, Claude con el contexto de la sesión. crítico · 0,90 / 0,70
Lo que lee el agenteVincula nombres de oradores con la base de datos de diputados
- Paso
- 10 de 13
- Lee
source/{iso2}/matrix/interventions_raw.csvsource/{iso2}/deputies/deputies.csv- Escribe
source/{iso2}/match/matching_table.csv- Confianza
- Oradores distintos vinculados de forma automática / oradores distintos. AUTO ≥ 0,90 · FLAG ≥ 0,70
Las decisiones humanas quedan congeladas y se vuelven a imponer al final de cada ejecución. Solo la forma femenina de un cargo (la presidenta) permite vincular por sexo. Una intervención nunca se borra porque su orador no se vincule.
Se invoca
/diaries-match --country {iso2}
/diaries-match --country {iso2} --force/diaries-mergeUne la matriz, la vinculación y el registro según el periodo, y atribuye a quien preside las intervenciones que el acta firma solo con el cargo.
Lo que lee el agenteJoin de intervenciones con matching y diputados para producir CSV enriquecido
- Paso
- 11 de 13
- Lee
source/{iso2}/matrix/interventions_raw.csvsource/{iso2}/match/matching_table.csvsource/{iso2}/deputies/deputies.csv- Escribe
source/{iso2}/merge/interventions_enriched.csv- Confianza
- Filas con diputado / filas, sobre la tabla final.
Con varias presidencias del mismo sexo, o titular y «en funciones», no atribuye: el acta nombra a quienes presidieron, no cuándo fue el relevo. Comprueba que cada diputado exista en el registro para esa legislatura.
Se invoca
/diaries-merge --country {iso2}Pasos 12–13 · La entrega
/diaries-standardizeOrdena las 16 columnas canónicas, valida cada fila y asigna los identificadores de sesión y de intervención. la entrega
Lo que lee el agenteAplica el esquema canónico final a interventions_enriched.csv
- Paso
- 12 de 13
- Lee
source/{iso2}/merge/interventions_enriched.csv- Escribe
source/{iso2}/standardize/{ISO2}_interventions.csvsource/{iso2}/standardize/{ISO2}_deputies.csv- Confianza
- 1 − errores de validación / filas.
No sobrescribe el archivo canónico sin --force, y un --force puede borrar correcciones hechas después: compara siempre el recuento de filas vinculadas antes y después.
Se invoca
/diaries-standardize --country {iso2}/diaries-documentTe entrevista sobre el corpus y escribe el README, el diccionario de datos y los metadatos JSON-LD.
Lo que lee el agenteGenera la documentación del corpus para un país (entrevista al procesador + README canónico)
- Paso
- 13 de 13
- Lee
country_config/{iso2}.yamlsource/{iso2}/standardize/- Escribe
docs/{iso2}/README.mddocs/{iso2}/data_dictionary.mddocs/{iso2}/dataset.jsonld- Confianza
- 1: es determinista.
Da dos tasas de vinculación: la bruta y la efectiva, que deja fuera lo que no se puede vincular (la Mesa sin persona, lo que no es discurso). Guarda tus respuestas para la próxima vez.
Se invoca
/diaries-document --country {iso2}Control · Seguir y corregir
/diaries-statusUna tabla con los trece pasos: cuántas sesiones están completas, en revisión, detenidas o pendientes, y cuál es el siguiente paso.
Lo que lee el agenteMuestra el estado actual del pipeline para un país
- Lee
state/{iso2}/pipeline_state.json
Se invoca
/diaries-status --country {iso2}/diaries-reviewRecorre los casos FLAG y HALT: para cada uno, la evidencia, la confianza y tu decisión.
Lo que lee el agenteRevisión interactiva de casos FLAG y HALT en el pipeline
- Lee
state/{iso2}/pipeline_state.json- Escribe
state/{iso2}/pipeline_state.json
Ante cada FLAG: [A]ceptar, [C]orregir, [E]scalar a HALT o [S]altar para más tarde. Los HALT se listan con su error y se marcan resueltos tras arreglarlos a mano.
Se invoca
/diaries-review --country {iso2}/diaries-feedbackInyecta una corrección en el estado: para una sesión, como regla desde una fecha, o como estrategia para todo un skill.
Lo que lee el agenteInyecta correcciones y reglas en el estado del pipeline
- Lee
state/{iso2}/pipeline_state.json- Escribe
state/{iso2}/pipeline_state.json
Tres tipos: punctual, rule (reprocesa desde la fecha) y strategy (todo el skill, con --force). Registra la acción; el porqué va en /diaries-decide.
Se invoca
/diaries-feedback --country {iso2} --skill diaries-tag --type rule --description "…" --from {id}/diaries-validateMide por muestreo qué parte del corpus está bien estructurada y bien atribuida, con la tasa de error acotada.
Lo que lee el agenteValida la integridad estructural del corpus por muestreo, con auto-filtro PASS/FLAG y calibración empírica de la tasa de fuga. Produce la cifra de calidad que el corpus puede afirmar, no la que se supone.
- Lee
source/{iso2}/standardize/{ISO2}_interventions.csv- Escribe
docs/validacion/{ISO2}_muestra.csv
Un filtro deja pasar solo lo que no admite duda y manda el resto a lectura humana. Sus detectores no comparten código ni léxico con los del pipeline: un control que comparte léxico con lo que vigila hereda sus puntos ciegos.
Se invoca
/diaries-validate --country {iso2}Control · Registrar e informar
/diaries-decideRegistra una decisión metodológica en el momento en que se toma, con la evidencia medida; sin evidencia no se guarda.
Lo que lee el agenteRegistra una decisión metodológica del pipeline con su evidencia, para que el informe del corpus pueda explicar QUÉ se hizo, POR QUÉ y CON QUÉ PRUEBA. Captura en el momento; sin evidencia medida no se guarda.
- Escribe
state/{iso2}/decisions.jsonlstate/_transversal/decisions.jsonl
Cuatro campos: decisión, alternativas, evidencia (qué se midió, sobre qué y qué salió) y consecuencia. Una decisión superada no se borra: --supersede la marca y la enlaza con la que la corrige.
Se invoca
/diaries-decide/diaries-reportEscribe el informe interno del proceso: cronología, confianzas, correcciones, tasa de automatización y lo que queda abierto.
Lo que lee el agenteGenera el informe completo del proceso de construcción del corpus
- Lee
state/{iso2}/pipeline_state.jsoncountry_config/{iso2}.yaml- Escribe
docs/{iso2}/pipeline_report.md
Se invoca
/diaries-report --country {iso2}Control · Aprender y mejorar
/diaries-teachLa guía interactiva: ocho caminos, de qué es el sistema a cómo dejar constancia de una decisión.
Lo que lee el agenteExplica cómo funcionan los skills diaries-* y guía al usuario por los caminos de uso típicos del pipeline ParlaIbero.
El camino 2, «Nuevo país desde cero», recorre los cinco tramos del pipeline y se ofrece a acompañarte en el primer paso.
Se invoca
/diaries-teach/diaries-refineMejora un SKILL.md a partir de un fallo observado en un caso real y anota el cambio.
Lo que lee el agenteMejora un SKILL.md a partir de una observación de testing real. Edita directamente el skill en ~/.claude/skills/ y registra el cambio en REFINEMENTS.md.
- Lee
~/.claude/skills/diaries-*/SKILL.md- Escribe
~/.claude/skills/diaries-*/SKILL.mdREFINEMENTS.md
Edita los skills instalados: el cambio rige desde la siguiente ejecución.
Se invoca
/diaries-refine --skill diaries-tag --issue "…"