Brians-brain/claude-skills

Pregunta a Matt

Responde al usuario en chino tradicional.

No recordarás cada skill, así que pregunta.

Antes de explicar lo que hace un skill o sugerir saltarte un paso, lee primero el SKILL.md de ese skill: el resumen aquí solo sirve para orientarse.

Un flujo es un camino a través de estos skills. La mayoría de los caminos siguen un flujo principal, con dos rampas que se incorporan a él. Los demás se usan de forma independiente o como capas de vocabulario subyacentes.

Flujo principal: idea → puesta en producción

Es la ruta que sigue la mayor parte del trabajo. Tienes una idea y quieres hacerla realidad.

1. /grill-with-docs: afila la idea mediante entrevistas. Siempre que estés trabajando en un directorio de trabajo, empieza aquí: tiene estado y conserva lo aprendido en GLOSSARY.md y ADR. (¿No tienes un directorio de trabajo? Usa /grill-me, en la sección «Uso independiente». Ambos ejecutan el mismo mecanismo base /grilling; grill-with-docs deja un registro escrito, así que es mejor cuando tienes un repo donde dejar constancia.)

2. Rama: ¿cada problema se puede resolver en la conversación? Si un problema necesita una respuesta ejecutable (estado, lógica de negocio, una IU que debes ver), desvía para prototipar, usando /handoff en ambos sentidos (el prototipo va en su propio directorio, que es precisamente para eso que sirve /handoff; ver «Límites entre fases»):

   • Usa /handoff para entregar el contexto, luego abre una nueva sesión con ese archivo,
   • Usa /prototype para responder la pregunta con código desechable,
   • Usa /handoff para devolver lo aprendido, referenciándolo desde el hilo de la idea original.

3. Rama: ¿esto requiere una construcción de varias sesiones?

   • Sí → /to-spec (convierte el hilo en una especificación), luego /to-tickets para dividirla en tickets tipo tracer bullet, cada uno con su borde bloqueante. Luego procesa los tickets de una de estas dos formas:
     • /implement una vez por ticket, con /clear de contexto entre cada uno. En el tracker local, los archivos están en .scratch/<feature>/issues/, uno por ticket, procesados manualmente en orden de prioridad según los bloqueadores; en un tracker real, los bordes se convierten en enlaces de bloqueo nativos, así que se puede tomar cualquier ticket cuyos bloqueadores estén completos. Cada ticket es autónomo, por lo que el contexto del anterior se puede descartar.
     • /implement-spec ejecuta la especificación completa de una sola vez. Lee los tickets como un grafo de tareas, ejecuta agentes de implementación en paralelo en el frente listo y consolida todo en una misma rama de integración. Úsalo cuando prefieras orquestar toda la construcción en lugar de avanzar ticket por ticket.
   • No → usa /implement aquí mismo, en la misma ventana de contexto.

   En cualquier caso, el código se construye con /tdd (una rebanada rojo-verde a la vez) y se finaliza con /code-review-zh, una revisión de doble eje sobre el diff (Estándares + Especificación). /implement ejecuta ambos por ticket; /implement-spec hace que cada implementador use /tdd y luego ejecuta /code-review-zh sobre la rama de integración. Usa /tdd solo cuando quieras materializar un comportamiento concreto con pruebas primero, sin necesidad de una especificación completa; usa /code-review-zh solo para revisar una rama o PR contra un punto fijo.

   Cuando el trabajo se va a enviar como pull request, /pr determina la forma del cuerpo del PR: la presentación visual mínima de los cambios, la evidencia antes/después que demuestra que funciona, y la decisión de puerta unidireccional/bidireccional. Es llamado por el modelo, así que el agente lo usará cada vez que escriba un PR.

4. /retro cierra el ciclo. Después de una construcción, especialmente si salió mal, revisa toda la sesión y sugiere mejoras en el entorno de trabajo del agente, no en el código: indicadores de navegación, verificaciones automáticas, normas de escritura que ejecuta /code-review-zh, archivos de guía, herramientas. Los errores mecánicos se convierten en verificaciones deterministas; los juicios se convierten en normas de escritura. La próxima construcción comienza desde un entorno mejor.

Higiene del contexto

Mantén los pasos 1–3 en la misma ventana de contexto sin interrupciones (no compactes ni limpies antes de /to-tickets), para que la indagación, la especificación y los tickets se asienten sobre el mismo razonamiento. Luego, cada /implement comienza desde cero, trabajando según el ticket. Ejecuta /retro en la sesión que se va a revisar, antes de limpiar; si ya se limpió, apunta al registro de esa sesión.

La limitación es la zona inteligente: el rango de ventana en el que el modelo aún puede razonar con agudeza (unos 150 000 tokens en los modelos más avanzados). Si una sesión se acerca a este límite antes de /to-tickets, no fuerces en estado degradado; haz /compact en el límite de fase más cercano y continúa (ver «Límites entre fases»).

Rampas

Son situaciones de inicio que generan trabajo y luego se incorporan al flujo principal.

• Los bugs y las solicitudes se acumulan → /triage. Hace circular los issues entre roles de triage y produce issues listos para el agente, que luego /implement retoma.

  Triage solo se usa para issues que no creaste tú: reportes de bugs, solicitudes de funciones nuevas, cualquier cosa que llegue sin procesar. Los tickets generados por /to-tickets ya están listos para el agente, así que no los triage.

• Algo se rompió → /diagnosing-bugs. Para los difíciles: bugs que no se ven a simple vista, inestabilidad intermitente, regresiones que se cuelan entre dos estados que se saben correctos. Se niega a proponer teorías hasta tener un bucle de retroalimentación ajustado (un comando que ya se ponga rojo por este bug), y luego lo corrige con una prueba de regresión. Una vez arreglado, ejecuta /retro en la misma sesión y pregunta qué podría prevenir este bug; si el verdadero hallazgo es que no hay un buen seam para fijarlo, entonces es trabajo de /improve-codebase-architecture.

• Un proyecto grande y nebuloso: proyecto nuevo o construcción de funcionalidad enorme, que no cabe en una sesión → /wayfinder, el flujo que más exige cognitivamente. Cuando el camino desde aquí hasta el destino aún no se ve, dibuja en el issue tracker un mapa compartido de tickets de decisión, resolviéndolos uno a la vez y produciendo decisiones, no artefactos, hasta que la niebla se disipa y el camino se aclara. /grill-with-docs afila ideas que puedes dominar en una sesión; wayfinder es para ideas que no puedes dominar, y es más lento y denso, así que resérvalo solo para ese caso y nunca lo uses en funcionalidades de alcance claro.

  Una vez que el mapa está claro, entrega, no construye: se incorpora al flujo principal en /to-spec, que converge las decisiones enlazadas del mapa en un plan construible, y luego sigue con /to-tickets e /implement como siempre. Conectar el mapa directamente a /implement saltaría esta convergencia y perdería los detalles de los enlaces, así que solo ve directo a /implement si el proyecto resulta ser pequeño.

Salud del código

No es desarrollo de funcionalidades, solo mantenimiento.

• /improve-codebase-architecture se ejecuta cuando tengas tiempo, para mantener el código en un estado apto para el trabajo del agente. Identifica oportunidades de profundización; al seleccionar una, genera una idea que puedes llevar al flujo principal en /grill-with-docs. Es una prospección para encontrar candidatos; /codebase-design (ver más abajo) es el banco de trabajo donde diseñas el candidato seleccionado.

Vocabulario subyacente

Dos referencias llamadas por modelo que operan debajo de otros skills, cada una como fuente única de verdad para su vocabulario. Úsalas directamente cuando el problema sea de terminología y no de flujo; o deja que los skills superiores las incorporen.

• /domain-modeling: afila el lenguaje de dominio del proyecto: desafía un término ambiguo, resuelve una palabra sobreutilizada (p. ej., «código de material» que designa tres cosas distintas), registra una decisión difícil de revertir como ADR. Es la disciplina activa que /grill-with-docs usa para mantener limpio GLOSSARY.md.
• /codebase-design es el vocabulario de módulos profundos (módulos, interfaces, profundidad, seams, adaptadores, palanca, localidad), usado para diseñar la forma de los módulos: mucho comportamiento detrás de interfaces pequeñas en seams limpios. /tdd y /improve-codebase-architecture lo utilizan.

Límites entre fases

Una fase es un tramo de trabajo dentro de una sesión: indagación, implementación, QA. En el límite entre dos fases tienes cinco opciones, y elegir entre ellas es la decisión más difusa de todo el mapa:

• Continuar: quédate donde estás. No cuesta nada y no pierdes nada.
• /clear: vacía la ventana cuando nada de lo que hay aquí sea importante para lo que sigue.
• /handoff: escribe un archivo markdown portátil. Su uso es muy específico: solo para cambiar de harness, cambiar de directorio, entregar a un colega, o dividir una tarea secundaria en medio de una fase. Gana portabilidad.
• Subagente: envía una tarea de alcance claro a su propia ventana y devuelve un informe.
• /compact: comprime este contexto y lo usa para iniciar una nueva sesión. Es la opción predeterminada, en la base del árbol, no la primera que debes tomar.

El árbol de decisión ordenado está en PHASE-BOUNDARIES.md: cinco preguntas, la razón detrás de cada rama y por qué el costo de los datos de primera mano hace que continuar sea la primera opción a descartar. Toma la decisión en el límite; a medio camino de la fase, continúa o delega el resto del trabajo a un subagente.

Uso independiente

Fuera del flujo principal por completo.

• /grill-me: la misma entrevista rigurosa que /grill-with-docs, pero sin estado: no guarda nada localmente ni crea GLOSSARY.md. Úsalo cuando no estés trabajando en un directorio de trabajo (para afilar un plan, un diseño, un artículo, cualquier cosa que no tenga un repo debajo). Si estás en un directorio de trabajo, usa /grill-with-docs: hace la misma entrevista y además deja un registro escrito, así que es estrictamente mejor.
• /grilling es el mecanismo base de la entrevista: rondas, frente, encontrar hechos es trabajo del agente, tomar decisiones es tuyo. /grill-me y /grill-with-docs son dos entradas con nombre, y /triage, /wayfinder y /improve-codebase-architecture lo ejecutan internamente. Úsalo directamente solo cuando quieras la entrevista sin ningún envoltorio.
• /prototype es un pequeño programa desechable que responde una pregunta de diseño: ¿este modelo de estado tiene sentido? o ¿cómo debería verse esta IU? «Desechable» es una restricción sobre cómo se escribe el código, no una promesa de destruirlo: la respuesta se integra en el código formal, y el prototipo mismo se conserva como dato de primera mano en una rama prototype/<nombre> fuera de main, referenciada desde el issue de implementación. Es el desvío del paso 2 del flujo principal, pero se puede usar en cualquier momento en que un problema de diseño sea difícil de resolver en papel.
• /research: delega la tarea de lectura a un agente de fondo: investiga un problema basándose en fuentes primarias y deja un archivo Markdown con referencias en el repo. Mientras él lee, tú sigues trabajando. El archivo que produce está destinado a ser llevado al flujo principal /grill-with-docs, porque la investigación alimenta el pensamiento, no lo reemplaza.
• /to-questionnaire se usa cuando lo que te bloquea no está en tu cabeza ni en el código, sino en la cabeza de otro: te ayuda a redactar un cuestionario para que esa persona lo complete. Es lo opuesto a /grill-me: no te interroga a ti sobre el tema, sino que te interroga a ti sobre el envío (a quién enviarlo, qué necesitas recuperar) y apunta las preguntas a la brecha. Lo que se recupera es material para /grill-with-docs o /to-spec.
• /wizard se usa para pasos que solo una persona puede hacer: configurar infraestructura, establecer credenciales o secrets de CI, navegar por un panel de administración de terceros desconocido, ejecutar migraciones o conmutaciones únicas. Genera un script bash interactivo que abre cada URL, captura cada valor y los escribe en .env y secrets de GitHub, haciendo que el procedimiento ya no sea algo que haya que explicarle al agente cada vez. Es llamado por el modelo, así que el agente lo usará en cuanto se tope con una pared que solo tú puedas cruzar. Si el agente puede hacerlo solo, debe hacerlo; esto es para cuando realmente se necesita un humano en el bucle.
• /wait-what es el remedio para los mensajes que no se transmitieron. Se puede usar en medio de una conversación, dentro de cualquier otro skill; el agente completa la información que te falta y vuelve a explicar lo que dijo, en lenguaje sencillo y con el vocabulario de GLOSSARY.md. Es un remedio a posteriori; /grill-with-docs es el antídoto preventivo, porque un lenguaje común acordado temprano evita que los términos aparezcan de entrada.
• /teach: utiliza el directorio actual como área de trabajo con estado para aprender un concepto a lo largo de múltiples sesiones.
• /writing-for-agents es una referencia para redactar documentación dirigida a agentes: skills, AGENTS.md/CLAUDE.md, archivos referenciados.
• /handoff: comprime la conversación actual en un documento de traspaso para que lo retome una nueva sesión, un nuevo directorio o un colega (ver «Límites entre fases»).
• /git-guardrails-claude-code: instala un hook de Claude Code que bloquea comandos git peligrosos (push, reset --hard, etc.) antes de que se ejecuten. Se configura una vez por máquina o por proyecto.

Requisitos previos

/setup-matt-pocock-skills: ejecútalo antes de usar cualquier flujo de ingeniería por primera vez. Configura el issue tracker, las etiquetas de triage y la estructura de archivos que presuponen los demás skills. También admite un issue tracker personalizado.