olonok69/cursor_code_ml_engineer

day — abrir y cerrar la jornada laboral

Por qué esto es una skill y no solo un documento. La regla "traer al empezar, subir al terminar" estuvo en un documento de operaciones durante meses y no se seguía en la máquina de publicación — nada registraba una sincronización, así que nada podía mostrar la deriva. La documentación no puede imponer un hábito; una rutina invocable sí puede. Lee esto por la forma, no por los comandos: cada paso peligroso responde primero a una pregunta, y cuando la respuesta es ambigua se detiene y pregunta.

El registro compartido bajo data/ solo está tan actualizado como la última sincronización, y nada más lo provoca. Dos momentos, empaquetados:

day start     # trae lo último del equipo, luego un breve briefing de orientación
day end       # publica el trabajo de hoy, y marca el KG si el corpus se movió
day status    # quién ha traído/subido recientemente, entre máquinas; quién tiene el testigo del KG
day baton     # entrega el rol de publicador a otra máquina (viaje, baja, traspaso)

Todo lo siguiente funciona en macOS, Linux y WSL — bash simple, nada de PowerShell. Copia de los scripts: ejemplos/metodologia/s3-sync/ (empezar desde config.env.example — nunca enviar un config.env real).

Paso 1 — encontrar la carpeta de sincronización y leer el rol de esta máquina

El rol decide lo que se puede hacer. Léelo antes de cualquier escritura en el bucket.

S3=""
d="$PWD"
while [ "$d" != "/" ]; do
  if [ -f "$d/data/changes/s3-sync/data-pull.sh" ]; then S3="$d/data/changes/s3-sync"; break; fi
  d="$(dirname "$d")"
done
if [ -z "$S3" ]; then echo "No hay sincronización de registro compartido en este repositorio (abre la raíz de <tu-repositorio>)."; fi
sed -n '1,20p' "$S3/IDENTITY.md"

¿No hay IDENTITY.md, o parece desactualizado? Regenera — es lo que el agente lee para aprender su rol, y una tarjeta desactualizada una vez nombró un perfil de AWS que había sido eliminado:

(cd "$S3" && ./identity.sh --write)

Si S3 está vacío, dile al usuario que este repositorio no tiene registro compartido y DETENTE.

Paso 2 — day start

1. ⚠️ Comprobar trabajo local no publicado PRIMERO — una traída puede sobrescribirlo. aws s3 sync transfiere cuando el tamaño difiere, no solo cuando el remoto es más reciente, así que una traída reemplaza un archivo editado localmente con la copia más antigua del bucket y recrea cualquier cosa que hayas renombrado localmente con su nombre antiguo. No se necesita --delete.

   (cd "$S3" && ./data-push.sh --root changes)   # ejecución en seco — cualquier cosa listada es trabajo solo local
   

   --root changes limita el barrido a la única raíz que se mueve día a día (medido 212s → 123s: un recorte, no un orden de magnitud). Suficiente para esta comprobación; usa el barrido completo al publicar.

   Nada listado → continúa. Algo listado → di qué es y ofrece publicarlo primero; no traigas por encima sin la autorización explícita del usuario.

2. Traer. Nunca --delete. El script ahora te protege, pero DEBES LEER lo que dice.

   (cd "$S3" && ./data-pull.sh --go)
   

   Antes de aplicar cualquier cosa, hace una instantánea de cada archivo local que la traída reemplazaría en data/_prepull/<timestamp>/, y los lista. Dos resultados en los que actuar:

   • "⚠️ N archivo(s) local(es) existente(s) serán REEMPLAZADOS" — lee esa lista en voz alta al usuario. Los archivos compartidos del hub (STATUS.md, FOLLOWUPS.md, SHARP_EDGES.md, TEST_MAP.md, _RESUME_*.md) que aparecen ahí significa que la copia de un colega está cayendo sobre la tuya, y cada lado puede tener contenido que al otro le falta — eso necesita una fusión, no un ganador. Compara la instantánea con el nuevo archivo antes de hacer cualquier otra cosa: diff data/_prepull/<ts>/changes/STATUS.md data/changes/STATUS.md Para deshacer toda la traída: cp -a data/_prepull/<ts>/. data/
   • Código de salida 3, "ARCHIVOS CON COLISIÓN DE MAYÚSCULAS/MINÚSCULAS" — dos objetos del bucket difieren solo en mayúsculas/minúsculas y se asignan a un solo archivo en esta máquina. Detente. La traída elegiría un ganador al azar. Borra primero la clave con mayúsculas/minúsculas incorrecta en el bucket; la forma canónica para documentos de ticket es minúsculas sst-NNNN.md (patrón de marcador de posición).

   ¿Error de credenciales? Vuelve a iniciar sesión antes de concluir nada — un token en caché caducado se ve exactamente como un problema de permisos: aws sso logout && aws sso login.

3. Ver quién más ha estado activo: (cd "$S3" && ./activity.sh)

3b. Actualizar la tabla de estado de tickets (segundos; ≤ 5 líneas — pégalas en el briefing). Opcional: solo si el proyecto mantiene una tabla de estado generada desde el rastreador y el host de Git.

(cd "$(dirname "$S3")/tools" && uv run -q --with openpyxl python ticket_status/sync.py)

Publicador: reescribe el libro de estado y el .md generado a partir de él, desde Jira (estado, tipo, enlaces) y GitHub (PR, fecha de fusión, primera versión). Contribuidor: mismo resumen, no escribe nada — un libro binario con dos escritores es el último que escribe gana. skipped — workbook is open → pide al usuario que lo cierre y lo re-ejecute. CANARY FAILED → no se escribió nada; lee el registro de ejecución antes de cualquier otra cosa.

3c. Fallos de servicio en las últimas 24 h (≈1 min; solo cuenta, no descarga nada — pega las líneas de grupo en el briefing):

T="$(dirname "$S3")/tools/evidence"
(cd "$T" && uv run -q --with boto3 python evidence.py discover --env dev --since 24h --list; \
            uv run -q --with boto3 python evidence.py discover --env stg --since 24h --list)

--list existe porque la primera ejecución en producción encontró ~240 ejecuciones problemáticas en 24 h en dev: un descubrimiento que descargara activaría su propia protección --max-runs cada mañana. Salida 2 → vuelve a iniciar sesión primero. Salida 6 → el bucket dejó de mantener versiones antiguas: díselo al usuario. Para recopilar evidencia de un grupo, usa la skill evidence (fetch --doc <id>, o discover --since 2h sin --list).

4. Orientar — historia primero, estado después. El más reciente data/changes/_RESUME_*.md (días anteriores: _PENDING_*.md), luego data/changes/STATUS.md para tu área, luego git fetch --all --prune y git status -sb. Usa la skill kg para arte previo antes de diseñar nada — nunca un grep de data/changes/ como primer movimiento.

5. Solo máquinas publicadoras (IDENTITY.md dice PUBLISHER): comprueba el testigo y la cola de actualización.

   (cd "$S3" && ./publisher.sh status)
   bash data/knowledge-graph/kg_refresh.sh queue
   (cd "$S3" && ./delete.sh --check)            # archivos eliminados que volvieron (solo informe)
   

   Informa qué está pendiente; no inicies una actualización sin que te lo pidan — son ~100 decisiones de nombre y una hora completa, y un grafo medio nombrado no pasa ninguna puerta.

6. Haz un breve briefing al usuario en pocas líneas, luego detente. day start prepara la máquina; no elige el trabajo.

Paso 3 — day end

1. Escribe el día antes de publicarlo: el documento de ticket bajo data/changes/<ticket>/, una fila en STATUS.md, cualquier seguimiento en FOLLOWUPS.md. El trabajo sin registro escrito es indistinguible del trabajo que nunca ocurrió.

2. Previsualizar, y leer la lista de archivos. Este es el momento de saneamiento — sin claves, sin secretos, nada que no deba entrar en el registro compartido.

   (cd "$S3" && ./data-push.sh)
   

   ⚠️ Vigila los archivos de fixture (.docx/.pdf bajo directorios de fixture / issue / sample). Una ejecución del extractor vuelve a guardar los fixtures en su lugar, y un fixture reguardado puede mantener su tamaño de bytes exacto mientras su hash cambia. No subas por encima de la copia prístina del bucket — restaura la tuya desde el bucket en su lugar.

3. Publicar. Nunca --delete.

   (cd "$S3" && ./data-push.sh --go)
   

   Un push de contribuidor que informa que saltó knowledge-graph/ es correcto, no un error — solo refresh_queue/ sube desde una máquina contribuidora.

   ⛔ Si el push sale con código 4 — "RECHAZADO: archivo(s) compartido(s) del hub cambiaron en el bucket" — un compañero escribió uno de esos archivos después de que esta máquina sincronizara por última vez, y nuestra copia difiere. aws s3 sync no tiene fusión, así que subir reemplazaría la suya. Lee los archivos nombrados en voz alta al usuario, compara cada uno con la copia del bucket, y fusiónalos. NO pases --allow-clobber por iniciativa propia — es para "el usuario ha confirmado que la nuestra reemplaza a la suya", nada menos.

   (cd "$S3" && source ./config.env && \
     aws s3 cp "s3://$BUCKET/$PREFIX/changes/STATUS.md" - --profile "$PROFILE" | diff - ../STATUS.md)
   

   Medido el 2026-09-18: un push cuatro minutos después de que un colega cerrara su día destruyó toda su sección de STATUS.md Y su registro de actividad — y nada en esta máquina parecía mal después, así que pasó un día entero sin ser detectado. La protección no se activa cuando nuestra copia es idéntica byte a byte a la del bucket, así que un archivo que acabamos de traer nunca es una colisión.

4. Si los documentos de ticket cambiaron, marca el grafo para que el publicador sepa que se necesita una reconstrucción:

   bash data/knowledge-graph/kg_refresh.sh request "<qué cambió y por qué es importante>"
   (cd "$S3" && ./data-push.sh --go)
   

5. Confirmar que aterrizó: (cd "$S3" && ./activity.sh) — el push de esta máquina debería leerse como de hace minutos.

day status

(cd "$S3" && ./activity.sh)          # última traída/subida por máquina
(cd "$S3" && ./activity.sh --log)    # flujo completo de eventos
(cd "$S3" && ./publisher.sh status)  # quién puede reconstruir y publicar el KG

⚠️ Informa de lo que fue registrado. Una máquina que nunca ha ejecutado los scripts instrumentados no muestra nada; la ausencia de un registro no es evidencia de falta de actividad.

day baton — mover el rol de publicador

Una máquina publica el grafo de conocimiento, porque aws s3 sync es el último que escribe gana sin fusión: dos publicadores destruyen silenciosamente los nombres comunitarios escritos a mano del otro. El testigo es un bloqueo consultivo mantenido en el bucket, así que cualquiera de las máquinas puede comprobarlo.

(cd "$S3" && ./publisher.sh status)
(cd "$S3" && ./publisher.sh release)            # máquina saliente, PRIMERO
(cd "$S3" && ./publisher.sh claim "motivo")        # máquina entrante, SEGUNDO

La máquina receptora también debe establecer MACHINE_ROLE="publisher" en config.env y volver a ejecutar ./identity.sh --write, o su agente seguirá leyendo CONTRIBUTOR y rechazará el trabajo que ahora posee. claim --force anula un testigo retenido — confírmalo con el usuario cada vez.

Reglas que se mantienen en todas las ramas

• Nunca --delete. Solo publicador, deliberado, y solo justo después de una traída fresca.
• Eliminar del almacén compartido es ./delete.sh (publicador), nunca aws s3 rm o --delete — de lo contrario las otras máquinas lo subirán de nuevo en su próximo push.
• Nunca subir knowledge-graph/ desde un contribuidor. La herramienta lo exige; no lo evites.
• Vuelve a iniciar sesión antes de diagnosticar un error de acceso — el error describe tu token en caché.
• El humano es dueño de las acciones externas. Esta skill sincroniza el registro compartido; no sube ramas, abre PRs, despliega ni envía mensajes a nadie.