slipdock/work

Trabajando desde el slipdock

El tablero es el plan de registro: qué hacer a continuación, y dónde va el registro de lo que sucedió. El servidor documenta sus propias convenciones: léelas primero, una vez por sesión, antes de elegir o actualizar algo:

slipdock guide                    # markdown, desde GET /api/guide

Sin la CLI en esta máquina — que es el caso habitual, ya que la CLI necesita Elixir:

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"   # pregunta al usuario si ninguno está configurado
curl -s -H "Authorization: Bearer $SLIPDOCK_TOKEN" "$B/api/guide"

La dirección del servidor proviene de $SLIPDOCK_URL, si no de ~/.config/slipdock/url (escrito por slipdock url o por /install.sh del servidor). Si no tienes ninguno, pregunta al usuario la dirección de su Slipdock en lugar de adivinarla; un tablero alojado es algo como https://app.slipdock.us, uno auto-alojado cualquier nombre con el que lo alcancen.

Pasa el token si lo hay ($SLIPDOCK_TOKEN, si no ~/.config/slipdock/token). La guía no necesita token, pero con uno termina con los tableros reales del usuario, cada lista en ellos, y qué lista es la lista de listo, el backlog, la de trabajo en progreso y la de trabajo terminado — que es exactamente lo que necesitas para recoger algo.

La guía prevalece sobre este archivo. Proviene del servidor en ejecución, por lo que está actualizada: los endpoints, los vocabularios y la disposición del tablero se generan en el momento de la solicitud. Este archivo solo te dice que la vayas a buscar y qué hacer mientras no la tienes.

Encontrar algo que nadie puede nombrar

slipdock cards <board> --search Q filtra un tablero por subcadena. Sus otros filtros preguntan sobre el estado en lugar de palabras, y son los que responden "¿qué debería recoger?": --deps ready deja fuera cualquier cosa que espera una tarjeta sin terminar, --no-assignee deja fuera el trabajo de otros, --due overdue es lo que se ha retrasado. Así que la lista elegible es una llamada:

slipdock cards <board> --column "To Do" --open --deps ready --no-assignee

slipdock search <words...> es diferente: coincide por significado, a través de todos los tableros que el usuario puede ver, y cubre comentarios y actualizaciones de estado además de tarjetas. Úsalo cuando el usuario describe algo en lugar de nombrarlo ("la tarjeta sobre el problema de redondeo de reembolso"), cuando lo que buscas probablemente se dijo en un comentario en lugar de un título, o cuando no sabes en qué tablero mirar. Lee el fragmento coincidente que imprime, luego slipdock card <id> para la tarjeta completa antes de tocarla.

La versión corta que se ampliará

• Épicas y subtarjetas. Una tarjeta de nivel superior es una épica: un resultado, que contiene la prioridad, las fechas y la discusión. El trabajo está en sus subtarjetas, una por tarea. Los elementos de la lista de verificación son los pasos dentro de una tarea. El nuevo trabajo que descubres va debajo de la épica a la que sirve, como una subtarjeta, no como una nueva tarjeta de nivel superior.
• Selección. Termina lo que ya está en progreso; luego la lista de listo (To Do), y el backlog solo cuando no haya nada elegible allí. Primero la prioridad más alta, la posición en la lista desempata. Salta cualquier cosa completada, archivada, bloqueada, en espera, pospuesta o asignada a otra persona — --open --deps ready --no-assignee hace la mayor parte de ese salto por ti (las tarjetas pospuestas ya quedan fuera de slipdock cards) — y cualquier suplente (↪stand-in-for:#N): solo marca dónde fue una tarjeta a un sprint. Si el tablero responde PAUSED (paused en el JSON), una persona ha retenido el trabajo del ejecutor en él: no tomes nada y detente. Cuando la tarjeta en la que aterrizas tiene subtarjetas, desciende a ella y trabaja esas hasta completarlas antes de volver para la siguiente tarjeta de nivel superior.
• Actualización a medida que avanzas. Mueve la tarjeta a en progreso y asígnatela a ti mismo cuando empieces; comenta en cada decisión, sorpresa o callejón sin salida; márcala (blocked, review) con un comentario diciendo qué estás esperando; cuando solo una persona puede dar lo que necesitas, abre una espera y detente (slipdock wait <id> "lo que necesitas" [--on EMAIL] [--choice X]..., o update_card wait; varias preguntas van como --question Q --question Q / questions, una cada una, nunca un bloque): marca la tarjeta waiting, y responderla (slipdock answer) hace que el trabajo se reanude — o, cuando lo que espera tiene una fecha, pósponla en su lugar (slipdock snooze <id> <date> --note "…"): sale de las listas y vuelve el día señalado, al principio de su lista; al terminar, establece completed: true y muévela a la lista de hecho. Completa una épica solo cuando su resumen muestre cada subtarjeta hecha.
• Trabajo verificado, donde el tablero lo tiene (su línea en la guía dice verified work: …). Escribe la barra de la tarjeta antes de empezarla (slipdock edit <id> --bar "…"), y nunca intentes cambiarla una vez que el trabajo ha comenzado. Complétala con lo que verificaste (slipdock done <id> --evidence-commit <sha> --tests a,b --suite passed:38:0 --evidence "…"). En un tablero donde un segundo agente verifica, done envía la tarjeta y la deja pendiente: no la muevas a Hecho tú mismo. Una tarjeta rechazada vuelve con su razón en el comentario, el prompt del trabajo y rejection de get_card (la transferencia dice Rework: …): lee esa razón primero, ya que es la siguiente instrucción. Verificar la tarjeta de otra persona (nunca la tuya propia) significa revisar el commit de la evidencia en un árbol limpio, ejecutar la suite (en un tablero de pull request, verificar que su CI pasó en ese commit en su lugar), juzgarlo contra la barra, luego slipdock accept <id> o slipdock reject <id> --reason "…". En un tablero que despliega por pull request (la línea del tablero lo dice, al igual que el prompt del trabajo reclamado y slipdock card), nunca hagas push a la rama predeterminada: haz commit en card-<id>, haz push, abre el pull request una vez (gh pr create --head card-<id> --title "<título> (#<id>)" --fill; el siguiente intento de una tarjeta rechazada hace push a la misma rama), observa sus verificaciones (la ejecución completa de pruebas: antes de hacer push, ejecuta solo las pruebas que agregaste o cambiaste), y completa con slipdock done <id> --pr <url>. Aceptar la tarjeta la fusiona; no la fusiones tú mismo. Una fusión fallida envía la tarjeta de vuelta rechazada con la razón: rebasa la rama y envía de nuevo.
• Carriles, donde están activados (la línea del tablero en la guía dice lanes: on). Antes de comenzar una tarjeta, escribe las rutas que su trabajo tocará: slipdock edit <id> --paths "lib/foo/**,docs/manual.md", tan estrecho como lo permita la instrucción. Un movimiento rechazado por superponerse a una tarjeta en progreso nombra esa tarjeta: estrecha las rutas, o deja la tarjeta bloqueada por ella; solo una persona anula un carril. En un tablero push, una tarjeta que espera verificación libera su carril y sus dependientes; en un tablero de pull request, lo retiene hasta la fusión. Tengan o no carriles el tablero, en una tarjeta con rutas, organiza solo archivos bajo ellas, por nombre, y con otra sesión activa en el mismo repositorio, trabaja en un worktree de git propio (git worktree add ../<repo>-lanes/card-<id> -b card-<id>), a menos que un ejecutor ya te haya puesto en uno ($SLIPDOCK_WORKTREE).
• Lee la transferencia primero, deja una cuando te detengas antes de terminar. La transferencia de una tarjeta (Left off: en la parte superior de slipdock card <id>; handoff en su JSON) es donde quien la tuvo por última vez la dejó: el siguiente paso único y una nota breve. Léela antes de los comentarios cuando recojas una tarjeta. Cada vez que te detengas con una tarjeta sin terminar — fin de una sesión, devuelta, bloqueada, sin tiempo — deja una: slipdock handoff <id> --next "<el siguiente paso único>" --body "Estado: … Problemas: … Abierto: … Pistas: …" (sobre MCP, leave_handoff). Reemplaza la última; el historial se mantiene. Los comentarios siguen siendo el registro continuo; la transferencia es el ahora. En una tarjeta terminada, la transferencia es para la persona: lo que debe hacer, verificar o saber (un despliegue, una reinstalación, una pregunta, una advertencia) como --next, con dónde están las cosas en algunas viñetas. Si no queda nada para ellos: déjala en blanco, y slipdock handoff <id> --clear una dejada anteriormente.
• Vuelve a leer la tarjeta antes de hacer push, y sus comentarios después. Una vez que el trabajo está verificado, slipdock card <id> de nuevo: una descripción cambiada o un comentario más nuevo que tu reclamo sigue siendo esta tarjeta — hazlo antes de hacer commit. Una vez que la compilación ha comenzado, lee los comentarios una vez más para cualquier cosa añadida mientras tanto.
• Incidentes y despliegues. Cuando el tablero registra despliegues (slipdock dora <board> responde en lugar de decir que las métricas de entrega están desactivadas), una interrupción o un lanzamiento roto es una tarjeta ordinaria etiquetada incident; si conoces el despliegue que lo causó, slipdock incident-of <card> <deploy-id>. Nombra la tarjeta en el commit de la solución (#57), como con cualquier tarjeta: así es como su despliegue se cuenta como una solución y la tarjeta obtiene su línea Shipped. Nunca registres o finalices despliegues manualmente — eso es trabajo de CI, con su propio token.
• Las sugerencias de ordenación son decisión de la persona. slipdock garden <board> (sobre MCP, garden) enumera lo que el jardinero del tablero encontró: épicas hechas pero abiertas, tarjetas atascadas en progreso, duplicados, páginas huérfanas. Muéstralas cuando se te pida ordenar, y aplica (slipdock garden apply <id>, garden_decide) solo lo que la persona aprueba; trabajando sin supervisión, nunca apliques o descartes una — un descarte se recuerda.
• El trabajo de larga duración recibe actualizaciones intermedias. Si la tarea llevará más de una sesión corta, comenta en cada hito mientras aún está en ejecución — qué se ha hecho, qué queda, cualquier cosa que haya cambiado el plan — y mueve percent_complete con ello. Un solo informe al final es demasiado tarde para ser útil: una tarjeta en progreso sin nada más nuevo que el movimiento en ella se lee como abandonada. Una épica que abarca varias sesiones recibe el mismo tratamiento, una línea a medida que cada subtarjeta se cierra.
• Los comentarios son Markdown y se hojean. Abre con una línea en negrita que diga qué es (**Recogido.**, **Construido.**, **Decisión:** …), luego viñetas cortas, un dato cada una, con rutas, comandos e ids de commit entre comillas invertidas; nunca un párrafo denso de cláusulas. Envía cualquier cosa de más de una línea con slipdock comment <id> --body - <<'EOF' … EOF (entre comillas, para que las comillas invertidas sobrevivan); las palabras en la línea de comandos pierden sus saltos de línea.
• Haz commit y enlázalo. Cuando el proyecto es un repositorio git, haz commit del trabajo de la tarjeta una vez que esté completo — antes de cerrar la tarjeta — con el id de la tarjeta (#42) en el mensaje de commit. El comentario de cierre enlaza al commit, o al PR si se abrió uno (Commit: https://github.com/…/commit/abc1234). Sin remoto al que enlazar, da el hash corto y la rama en su lugar.
• Costo de tokens en el informe. El comentario de cierre en una tarjeta termina con una línea que da los tokens que el trabajo usó, p.ej. Token cost: ~135k tokens (context budget 15.00M → 14.86M, claim to close). Toma una lectura del contador de tokens restantes (total_tokens left en mensajes del sistema) cuando reclames la tarjeta y de nuevo cuando la cierres, y da la diferencia. Si se trabajaron varias tarjetas en una sola sesión, mide cada una desde su propio reclamo. Si no hay contador visible, di "Token cost: not measured" en lugar de estimar. Añade la misma cifra al comentario de progreso de la épica.
• Lee sus favoritos primero. slipdock favourites enumera los tableros, listas, tarjetas y vistas guardadas que esta persona ha marcado — dónde trabajan realmente, lo que una lista de tableros no te dice. Cuando "¿qué debería trabajar a continuación?" se pregunta sin nombrar un tablero, un favorito es la pista más fuerte que tienes. Son personales: nunca añadas o elimines uno a menos que se te pida.
• Los tableros archivados son trabajo que se ha dejado de lado. slipdock boards los omite a propósito; --all los muestra con un estado archived. Todo en uno todavía se lee y escribe, pero nunca tomes trabajo de un tablero archivado sin preguntar, y nunca pongas trabajo nuevo allí.
• Escribe lo que la tarjeta no puede contener. Un tablero dice lo que se está haciendo; es un mal lugar para cómo funciona algo, lo que se decidió y por qué, o la forma de una cosa. Esas cosas van en la wiki del tablero — slipdock page ls <board>, slipdock page read <page>, slipdock page new <board> <title...>. La prueba es si se leerá de nuevo después de que esta tarjeta se cierre: una decisión, un runbook, una especificación o los hallazgos de una investigación lo serán, y pertenecen a una página (enlazada desde el comentario de cierre de la tarjeta por su código, W-31); el progreso, los bloqueadores y lo que sucedió ahora pertenecen a un comentario en la tarjeta. Nunca ambos — una página que repite los comentarios es una página en la que nadie confía. Busca antes de escribir una (slipdock page ls <board> --q <la cosa>): extender la página que existe vence a una cuarta página sobre el despliegue. Pasa --message en cada edición, y --base-hash en cualquier edición a una página que no acabas de escribir tú mismo, para que un guardado nunca pueda aterrizar silenciosamente encima del de otra persona.
• Mantén los títulos cortos. Un título de tarjeta tiene como máximo unos 60 caracteres, una serie como <Serie> <n>: <qué> (Supervisión de agente 5: Trabajos estacionados), el detalle en la descripción. El título de una tarjeta se convierte en una carpeta y se muestra en listas ajustadas, y una secuencia de tarjetas que comparten sus primeros 40 caracteres no se pueden distinguir allí.
• No elimines tarjetas (archívalas en su lugar), reescribas un título para que coincida con lo que realmente hiciste, ordenes las tarjetas de otras personas, o dejes una tarjeta en progreso sin un comentario más nuevo que el movimiento. Archivar o reordenar un tablero completo está aún más lejos de tu competencia: solo por una solicitud explícita, nombrando ese tablero.

Cuándo se aplica esto

• "¿Qué debería trabajar a continuación?", "continuar con el plan", "trabajar a través del backlog", "siguiente tarea" → obtén la guía, luego elige según sus reglas y di qué tarjeta tomaste y por qué.
• "Pon este plan en el tablero", "divide esto en tareas" → épicas con subtarjetas, según la forma de la guía.
• Ya estás en medio de una tarea que vino del tablero → la tarjeta es donde se escriben el progreso, las decisiones y los bloqueadores, a medida que ocurren en lugar de en un solo volcado al final.
• Terminaste algo que vino del tablero → ciérralo en el tablero antes de informarlo como hecho.