grill-with-docs

Descripción general de la skill grill-with-docs

grill-with-docs es una skill de planificación y documentación para equipos que quieren poner a prueba un diseño frente al lenguaje y las decisiones que ya existen en su repo. Es ideal para Technical Writing, ingeniería con mentalidad de producto y trabajo de arquitectura asistido por IA, donde los términos deben mantenerse alineados con CONTEXT.md y los ADR, en lugar de derivar hacia un lenguaje vago “solo de prompt”.

Su tarea principal es sencilla: entrevistar al usuario una pregunta a la vez, recomendar respuestas y usar el código o la documentación cuando una pregunta pueda resolverse desde la fuente. Eso hace que la skill grill-with-docs sea más útil que un prompt genérico de lluvia de ideas cuando el riesgo real es un desfase de terminología, supuestos no documentados o registros de decisión desactualizados.

Qué hace diferente a grill-with-docs

Está diseñada alrededor del conocimiento del dominio, no solo de la conversación. La skill te empuja a revisar archivos de contexto existentes, explorar ADR y actualizar la documentación a medida que las decisiones se aclaran, por eso funciona tan bien para grill-with-docs for Technical Writing y otros flujos de trabajo con mucha documentación.

Casos de uso que mejor encajan

Usa grill-with-docs cuando necesites:

• validar un plan frente a un modelo de dominio existente,
• elegir terminología precisa para el proyecto,
• registrar decisiones a medida que se toman,
• o mantener un borrador alineado con la documentación ya establecida antes de empezar la implementación.

Cuándo no encaja

Si solo quieres un resumen rápido, una especificación pulida o ideación libre sin anclaje en el repo, esta skill se sentirá más lenta que un prompt plano. Su valor está en el cuestionamiento disciplinado y la verificación consciente de la documentación.

Cómo usar la skill grill-with-docs

Instala grill-with-docs

Instala la skill grill-with-docs en tu directorio de skills con el gestor estándar del repo y luego abre los archivos de la skill en el contexto del proyecto objetivo. El patrón base de instalación es:

npx skills add mattpocock/skills --skill grill-with-docs

Tómalo como el punto de partida para grill-with-docs install y después confirma que la skill esté disponible en el entorno de agente que realmente usas.

Empieza con la entrada correcta

La skill funciona mejor cuando tu primer mensaje contiene:

• el objetivo que estás planificando,
• el nombre del sistema o la funcionalidad,
• cualquier término conocido que importe,
• y el límite de decisión que quieres resolver.

Un prompt débil dice: “Ayúdame a diseñar esta funcionalidad.”
Un prompt más sólido dice: “Usa grill-with-docs para poner a prueba este plan de funcionalidad frente al dominio actual de billing. Necesito el término correcto para ‘subscription period’, la forma de los datos y cualquier decisión que merezca un ADR antes de escribir la documentación.”

Lee primero estos archivos

Para grill-with-docs usage, empieza con:

• SKILL.md para el comportamiento de la entrevista y el flujo de trabajo,
• CONTEXT.md o CONTEXT-MAP.md para el modelo de dominio activo,
• docs/adr/ para decisiones previas,
• ADR-FORMAT.md y CONTEXT-FORMAT.md si necesitas crear o actualizar archivos.

Estos archivos te dicen qué puede inferirse del repositorio y qué debe quedar escrito de forma explícita.

Flujo de trabajo que mejora el resultado

Usa la skill en un ciclo:

1. da un plan concreto o un borrador inicial,
2. deja que la skill haga una pregunta a la vez,
3. responde con el detalle más específico posible y con base en el repo,
4. permite la exploración del código cuando la pregunta pueda resolverse desde los archivos,
5. registra la terminología y las decisiones firmes en notas de contexto o ADR.

El consejo práctico clave: separa “necesitamos un nombre” de “necesitamos una decisión”. Eso mantiene el grill enfocado y evita ADR innecesarios.

Preguntas frecuentes sobre la skill grill-with-docs

¿grill-with-docs es solo para equipos de documentación?

No. Resulta útil siempre que un plan deba coincidir con un vocabulario de dominio existente, especialmente en ingeniería de producto, trabajo de plataforma o flujos de grill-with-docs for Technical Writing donde el texto y la estructura afectan la claridad posterior.

¿En qué se diferencia de un prompt normal?

Un prompt normal puede generar ideas, pero grill-with-docs está pensado para interrogar supuestos, revisar el repositorio y ajustar los términos según el contexto existente. Eso reduce la probabilidad de colisiones de nombres y de documentación que entra en conflicto con el código.

¿Necesito una base de documentación madura para usarlo?

No, pero funciona mejor cuando ya existen CONTEXT.md y ADR. Si no existen, la skill igual puede ayudarte a definirlos de forma progresiva a medida que aparecen las decisiones.

¿Cuándo debería evitar usarlo?

Evítalo cuando la tarea sea puramente exploratoria, el repositorio no tenga contexto de dominio relevante o necesites una respuesta rápida de una sola vez en lugar de una entrevista estructurada.

Cómo mejorar la skill grill-with-docs

Entrégale mejor material de decisión

La mejora de calidad más grande viene de darle a la skill un prompt estrecho y con forma de decisión. Incluye el nombre de la funcionalidad, la parte del sistema que toca y la ambigüedad exacta que quieres resolver. Ejemplo: “¿Deberíamos llamar a esto invoice, billing record o charge en el contexto contable, y dónde debería vivir esa decisión?”

Dale evidencia del repo desde el principio

Si ya conoces archivos relevantes, menciónalos desde el inicio. Apuntar la skill a CONTEXT.md, a un ADR específico o a una carpeta como src/billing/ le ayuda a hacer menos preguntas genéricas y más preguntas útiles. Esto importa especialmente para grill-with-docs usage porque la skill rinde más cuando puede comparar tu plan con términos y estructura existentes.

Vigila los fallos más comunes

El fallo principal es especificar poco el dominio y dejar que la entrevista se vuelva abstracta. Otro es pedir implementación antes de que el modelo de lenguaje tenga los términos adecuados. Si la primera salida resulta demasiado amplia, reformula la decisión en términos más estrechos y pide a la skill que continúe desde la última rama resuelta.

Itera desde la primera pasada

Después de la primera ronda, convierte las respuestas en uno de tres resultados: una entrada de glosario depurada, un ADR breve o un brief de implementación revisado. Luego vuelve a ejecutar grill-with-docs sobre las preguntas que sigan abiertas. Esa segunda pasada es donde la skill suele aportar más, porque la terminología y los límites ya están más claros.