EvolveHQ/docflow

add-convention

Añade una convención — pero solo tras evaluar si debe existir y dónde pertenece. Este skill es un guardián y un enrutador, no un mero transcriptor.

Paso 0 — Precondiciones y contexto

1. Confirma que el repositorio está inicializado.
2. Lee CONVENTIONS.md y AGENTS.md por completo para detectar solapamientos con reglas existentes y juzgar la idoneidad.

Paso 0.5 — Evaluación (ejecutar primero)

Ejecuta el protocolo de evaluación compartido; las preguntas de triaje (Paso 1) y enrutamiento (Paso 2) se formulan bajo él:

• Reutiliza las respuestas proporcionadas primero. Trata las opciones aplicables ya suministradas en la solicitud o en esta sesión, incluida la profundidad, como respondidas. Resúmelas sin volver a preguntar; los valores predeterminados nunca reemplazan opciones explícitas. Si se proporciona toda elección material, procede. Pregunta solo sobre una elección material faltante o conflictiva. Una preferencia del repositorio por sí sola no es una respuesta actual ni una concesión de ejecución.

• Selector de profundidad para elecciones no resueltas. Si no se proporciona la profundidad y quedan elecciones, pregunta qué tan profunda debe ser esta evaluación: exprés — cada elección toma su valor predeterminado recomendado; solo se siguen preguntando aquellas sin valor predeterminado derivable (los datos esenciales de texto libre); guiada — solo las preguntas marcadas como de alto impacto a continuación, más los datos esenciales de texto libre; completa — todas las preguntas a continuación. Si el CONVENTIONS.md del repositorio registra un Assessment depth:, preselecciónalo como la opción recomendada al preguntar; una profundidad registrada nunca se aplica silenciosamente. En caso contrario, recomienda completa cuando la solicitud llegue con poco o ningún contexto y exprés cuando ya esté completamente especificada. En cualquier pregunta, el operador puede responder "valores predeterminados desde aquí" o "ir más profundo"; respeta el cambio de inmediato.

• Haz las preguntass una a la vez, cada una con una opción recomendada y una razón de una línea; espera cada respuesta.

• Usa selección estructurada (opción única o múltiple). Si el anfitrión expone una herramienta de pregunta estructurada de selección única/múltiple, úsala y marca la opción recomendada; de lo contrario, enumera las opciones A/B/C en texto plano y nombra la recomendada. Usa solo texto libre cuando un conjunto enumerable sea imposible (por ejemplo, la redacción exacta).

• El operador decide. Nunca avances más allá de una pregunta sin una respuesta, y nunca adivines el alcance cuando se invoque sin contexto.

Preguntas (salta cualquiera que la solicitud ya responda):

1. ¿Vale la pena codificarla? — sí (recurrente, estable, comprobable) o no (puntual, duplicada, propensa a cambios, vaga). Recomendado: según el triaje del Paso 1; esta pregunta es la puerta de entrada al resto. (Alto impacto — se pregunta en guiada.)
2. Ubicación — regla estricta en AGENTS.md / guía en CONVENTIONS.md / término en GLOSSARY.md / en realidad es una decisión (pasar al skill new-adr). Recomendado: según la naturaleza de la regla (ver Paso 2). (Alto impacto — se pregunta en guiada: una ubicación incorrecta implica trabajo para moverla).
3. ¿Aplicar en la puerta de verificación? — sí / no. Recomendado: no, a menos que la regla sea mecánicamente comprobable.
4. Redacción — texto libre (el enunciado de la regla en sí; se pregunta en todas las profundidades).

Paso 1 — Evaluar: ¿vale la pena codificarla?

Aplica el triaje. Recomienda en contra de añadir cuando:

• Ya está cubierta (explícita o implícitamente) por una convención existente — señálala en lugar de duplicar.
• Es una decisión puntual, no recurrente — codificarla añade ruido.
• Es propensa a cambios — las reglas prematuras se convierten en lastre obsoleto.
• Es demasiado vaga para ser comprobable o accionable tal como está escrita.

Recomienda a favor de añadir cuando es una decisión recurrente cuya ambigüedad causa retrabajo, es estable y puede enunciarse de modo que un agente pueda seguirla sin interpretación adicional. Indica tu recomendación y la razón antes de hacer cualquier otra cosa.

Paso 2 — Enrutar: ¿dónde pertenece?

Decide la ubicación y explica la elección:

• Regla estricta que los agentes deben obedecer → un punto en AGENTS.md §Hard rules, con el contenido en CONVENTIONS.md. Úsalo para restricciones no negociables.
• Guía de autoría / proceso → una sección en CONVENTIONS.md. Úsalo para "cómo hacemos las cosas" que informa pero no es restrictivo.
• Término / definición compartido → GLOSSARY.md (crearlo si no existe — añadir el primer término habilita la capa de glosario; colócalo en la raíz del artefacto registrado). Lee la sección §Glossary de CONVENTIONS.md del repo e inspecciona la regla que realmente declara; la estructura canónica es un encabezado H1 opcional y prosa introductoria opcional, luego exactamente una tabla Markdown de dos columnas cuyo encabezado es Term | Definition. Cada término es su propia fila. Nunca registres un término como encabezado, viñeta o párrafo, y nunca añadas una segunda tabla o una forma de columna diferente. Un §Glossary que indique una convención de glosario más antigua o no relacionada no es adopción de esta tabla: usa la forma canónica y ofrece la migración de regla y archivo separadamente consentida del skill audit en lugar de copiar la forma antigua. Un GLOSSARY.md ausente sigue siendo un estado válido; este skill lo crea solo porque realmente se está añadiendo un término.
• En realidad es una decisión, no una convención (una elección arquitectónica, de producto o tecnológica con alternativas y consecuencias) → esto es un ADR. Detente y ofrece el skill new-adr; no entierres una decisión en CONVENTIONS.

Si una convención es una regla de triaje/proceso (por ejemplo, cómo se tria el trabajo entrante), prefiere CONVENTIONS.md con un punto de regla estricta en AGENTS.md solo para las partes que son no negociables.

Paso 3 — Redactar y confirmar

Redacta la redacción exacta para su archivo de destino. Mantenla concisa, comprobable y en el idioma del repositorio. Muestra el diff. Confirma antes de escribir.

Paso 4 — Escribir y confirmar

Aplica las ediciones. Si una convención se eleva a regla estricta, asegúrate de que AGENTS.md y CONVENTIONS.md sigan siendo coherentes. Commit convencional (docs: ...); si no se toca ningún ADR, no se requiere un pie Rationale:, pero agrega uno si el contrato del repositorio lo solicita para cambios de convención.

Añadir o extender un glosario. Usa la estructura canónica definida a continuación y las comprobaciones de regla declarada; la forma no debe desviarse entre ejecuciones.

• De dónde viene la regla. Si CONVENTIONS.md no tiene una sección §Glossary (un repositorio heredado que la precede, o una capa habilitada antes de que la regla se registrara), recurre a la forma canónica predeterminada del producto anterior: encabezado opcional # Glossary y prosa introductoria, luego una tabla Term | Definition. No inventes una forma diferente para ese repositorio y no edites silenciosamente convenciones no relacionadas.
• Leer la regla declarada. Cuando exista un §Glossary, lee lo que realmente declara. Si describe la tabla canónica de dos columnas Term | Definition, síguela y cámbiala solo si hay una solicitud explícita. Si indica una convención de glosario diferente o más antigua (viñetas, prosa, otra forma de columna), el repositorio no ha adoptado esta tabla: no copies la forma antigua y no reescribas silenciosamente la regla. Usa la forma canónica para el término y ofrece la migración del skill audit, que cubre la regla y el archivo juntos como un único diff consentido separadamente.
• Registrar la convención. Cuando un §Glossary esté ausente, ofrece — como su propia edición confirmada, separada del término que se añade — registrar una sección ## Glossary en CONVENTIONS.md indicando la forma realmente utilizada. Muestra ese diff y escríbelo solo si el usuario lo acepta; nunca reescribas ni reordenes otras secciones de CONVENTIONS.md para hacer espacio, y si el usuario rechaza, mantén el glosario canónico pero deja CONVENTIONS.md sin cambios.
• Crear el archivo. Escribe el encabezado opcional # Glossary y cualquier prosa introductoria breve que el repositorio necesite, luego la única tabla de dos columnas con encabezado Term | Definition y el nuevo término como su primera fila. No inventes términos de relleno.
• Extender un archivo existente. Preserva el encabezado, la prosa introductoria, el orden de las entradas y cada fila existente byte por byte. Añade el nuevo término como una nueva fila; nunca reconstruyas, reordenes ni reformatees el archivo, y nunca introduzcas una segunda tabla.
• Anclas. Si la fila del nuevo término es alcanzable desde un ancla de encabezado que un enlace entrante ya usa, mantén ese ancla en la fila en lugar de eliminar el destino; si el ancla no puede preservarse, detente y señálalo en lugar de adivinar.
• Preserva el significado. Mantén la ortografía del término, alias, enlaces y código en línea exactamente como se proporcionaron. Escapa una barra vertical literal como \|. Si una definición es genuinamente multilínea, mantenla en una sola celda con <br> para el salto duro en lugar de derramarse en filas adicionales.
• Duplicados y ambigüedad. Si el término ya existe, muestra las definiciones existente y propuesta y pregunta si se debe actualizar o dejar la fila existente. Nunca combines, reemplaces ni añadas silenciosamente una segunda fila para el mismo término, y nunca adivines una definición.
• Archivo no canónico. Si el GLOSSARY.md existente tiene viñetas, prosa, encabezados o una forma mixta, no añadas una fila competidora y no reescribas el archivo como efecto secundario de añadir un término. Expón la estructura no canónica y ofrece la migración consentida del skill audit; aplícala solo si el usuario acepta el diff concreto. Una migración rechazada deja el archivo como el usuario lo mantiene.

Nombra la regla y la propagación realizada; enumera los repositorios no actualizados.

Informe de cierre

Termina cada ejecución, incluidas las bloqueadas, fallidas y detenidas, con una sección encabezada exactamente Estado de un vistazo, que contenga estas tres etiquetas:

• Esta ejecución: solo las acciones realmente intentadas y sus resultados; cita la salida exacta y el código de salida de cada puerta de verificación, incluidos tiempos de espera o interrupciones.
• General: implementado, parcialmente verificado, verificado, bloqueado, fallido o desconocido. Un subpaso exitoso no es un éxito general; la evidencia incompleta o faltante nunca se convierte en éxito.
• Pendiente: cada acción restante, hallazgo no resuelto, verificación, limpieza o entrada requerida. Escribe Ninguno solo cuando toda la tarea esté verificablemente completa; nunca omitas trabajo porque un presupuesto terminó.

Los mensajes de progreso rutinarios no necesitan bloque. Mantén los resultados finales breves y distingue el trabajo preparado en un PR del trabajo confirmado como enviado.