Diseño de Documento con Primera Línea de Suposiciones

design-doc

gemini-4-argon escribe y revisa toda la prosa, incluidos resúmenes, gemelos textuales, identificadores, notas de revisión y texto de publicación. La sesión le proporciona los hechos y las reglas (el contrato de escritura, las reglas anti-chatarra, los límites de longitud) a través de gemini -m gemini-4-argon --skip-trust -p, incorpora la respuesta textualmente, y recopila evidencia y publica el resultado por sí misma. Los ayudantes de prosa llaman al mismo modelo a través de gemini --skip-trust -p, sin modelo de respaldo.

Un diseño de arquitectura es una pila de decisiones sobre una pila de suposiciones. Esta habilidad ejecuta el diseño como una conversación — el usuario decide todo — y renderiza el resultado como un documento donde cada afirmación se remonta a una suposición, una decisión y la ronda de preguntas que la produjo.

Un comando impulsa las partes mecánicas:

TOOL="python3 ${CLAUDE_PLUGIN_ROOT}/skills/design-doc/scripts/design.py"
$TOOL scaffold --title <nombre>   # nuevo directorio ./<slug>/ para este documento de diseño
$TOOL scaffold --example        # ./tinyq/, un pequeño ejemplo completo
$TOOL check <dir>               # lint de los registros, los gemelos textuales, el código fuente del diagrama y la baraja de resúmenes; los errores salen con código no cero, --strict convierte las advertencias que bloquean la publicación también en errores
$TOOL summary-text <dir>        # la baraja como Markdown, una sección ## por panel; la entrada para los portones
$TOOL plainify <dir> [--only DQ3,A2] [--dry-run]
$TOOL glossary <dir>            # términos que usa la prosa y que faltan en el glosario, como entradas candidatas
$TOOL build <dir>               # compila components/*.tsx en components.js; solo para un doc con un directorio components/
$TOOL render-check <dir>        # renderiza cada bloque Mermaid en Chrome sin cabeza; falla en un error de análisis o una excepción de página
$TOOL pdf <dir>                 # imprime el documento a través de la hoja de estilos de impresión de la plantilla en <dir>/design-doc.pdf
$TOOL snapshot <dir> --note "…" --item "…" # sella una revisión contra la cual la vista de cambios-desde hace diff; note es el titular para el lector, cada --item es un cambio
$TOOL links <dir> [--fetch] [--missing] # cada decisión y elemento abierto con sus enlaces de pull-request y estado; --fetch pregunta a GitHub si cada enlace se fusionó e informa desviaciones, --missing lista las entradas aún sin enlazar

Lee reference/method.md antes de la Fase 1, reference/writing.md antes de la Fase 5, y reference/publish.md antes de la Fase 6 — el archivo de método es el protocolo de ronda/registro, el archivo de escritura es el contrato de voz, el archivo de publicación es el flujo de alojamiento. reference/schema.md es el contrato campo por campo para los archivos JSON; crea el ejemplo tinyq cuando quieras un registro completo junto al esquema.

Terminología

• Registro — una lista estructurada en registers.json cuyas entradas tienen IDs estables: A# suposiciones, DQ# decisiones, Q# preguntas abiertas, V# spikes, c-<slug> tarjetas de arquitectura.
• Ronda — un tablero presentado al usuario, registrado textualmente en qa-log.json. Una ronda pregunta todas las bifurcaciones abiertas a la vez, cada una como un bloque design-doc.fork, y no pregunta nada más. Las respuestas que abren nuevas bifurcaciones inician la siguiente ronda, de nuevo todas a la vez; qa-log.json registra las rondas en orden, para que un tablero posterior pueda depender de una respuesta anterior.
• Supersesión — una decisión modificada obtiene una nueva entrada y la anterior recibe s: "superseded" más un puntero by, que el documento renderiza como "Reemplazado por" y el título del sucesor. El historial se mantiene legible porque nada se edita en su lugar.
• Estrella (★) — marca la suposición crítica, aquella cuyo fallo invalida el documento.
• Spike — un experimento con nombre y tiempo limitado (V#) que convierte una estimación marcada con (E) en un número medido.
• Resumen ejecutivo — summary.html, un fragmento HTML escrito a mano junto a registers.json, para el lector que no lee nada más: una baraja de paneles a pantalla completa por defecto, un póster cuando el diseño es una idea y una figura. Nunca se analiza como datos; check verifica su forma, sus presupuestos de palabras y sus citas.
• Gemelo textual — el campo p junto a la redacción precisa de una entrada, una o dos frases cortas que dicen lo que significa la entrada para alguien que no la lee. El documento muestra los gemelos por defecto y la redacción exacta a un clic de distancia.
• Clave y tema — key: true marca las 3–8 decisiones y suposiciones sobre las que el documento se abre como tarjetas; theme archiva cada entrada bajo uno de los 3–5 temas del diseño, nombrados en la Fase 0 y definidos en el mapa themes.
• Diagrama — el código fuente Mermaid del diagrama del sistema, en la clave diagram del registro; el documento lo renderiza, el lector lo desplaza y pasa el ratón por encima, y las rutas de solicitud lo recorren paso a paso. diagram.overview es el subconjunto de diez nodos que dibuja la tarjeta de Visión General, con el gráfico completo a un clic de distancia. Un sysd.svg dibujado a mano sigue siendo válido como diagram.kind: "svg".
• Identificador — el campo h en cada decisión, suposición, elemento abierto, tarjeta de arquitectura y tabla de números: cómo lo llamaría un lector, de dos a cinco palabras. Las citas y las filas de tarjetas muestran el identificador; el ID vive en la tarjeta emergente.
• Componente — una figura interactiva declarada en el mapa components (dd.tabs, dd.before-after, dd.whatif, dd.steps, dd.timeline, dd.matrix, las dos figuras de panel de comparación dd.flow y dd.lanes, el mapa del sistema dibujado a mano dd.system, y dd.arch, que incrusta un documento de arquitectura publicado) y colocada por id en la baraja o en una entrada; un archivo TSX bajo components/ es la alternativa que build compila.
• Resumen de figura y crítica — las dos secciones de NOTES.md de las que se extrae la baraja y contra las que se lee. Un resumen son cinco líneas por figura, escritas antes de dibujar la figura: el punto que plantea, la decisión a la que sirve por ID, la vista más pequeña que muestra el punto, lo que omite y las etiquetas reales que utiliza. Sus dos primeras líneas se convierten en la <figcaption>. La crítica es una fila por panel, figura, tabla y estadística, escrita antes de los portones: la decisión a la que sirve, la afirmación que hace, la pregunta que le queda al lector y corregida o eliminada. check advierte cuando falta cualquiera de los dos encabezados.
• Enlace — una entrada de links[] en una decisión, un elemento abierto o una fila de hallazgo: el pull request, issue, commit o documento que lo materializa. closes: true en el enlace de un elemento abierto marca el que lo retira. El documento muestra cada enlace como una tarjeta con su estado en GitHub y encabeza cada grupo abierto con cuántos de sus elementos están cerrados.
• Estados: las decisiones son resolved | superseded | open, que el documento renderiza como Decidida, Reemplazada y Aún abierta; las suposiciones son working | validate, renderizadas Supuesta y Necesita que alguien confirme (alguien fuera del documento tiene que decir que sí). Los elementos abiertos son open | closed, renderizados Aún abierto y Cerrado; un enlace closes fusionado cierra un elemento antes de que s lo indique. La prosa usa las palabras renderizadas, JSON los valores.

Alcance

Esta habilidad se detiene en el diseño. Sus resultados son un registro de decisiones y un documento; el código de implementación es una tarea diferente que comienza después de que la propuesta sobrevive a la revisión. Cuatro portones mantienen honesto el registro:

• Las bifurcaciones de diseño son decisión del usuario. Cada bifurcación pasa por una ronda, incluso cuando una opción parece obviamente correcta: el registro del por qué vale más que el intercambio ahorrado.
• qa-log.json es textual y de solo adición. Limpia la ortografía en las respuestas, no cambies nada sustancial y omite los intercambios de solo explicación; es un registro de decisiones, no una transcripción.
• El artefacto de la revisión adversaria permanece fuera del documento renderizado. Solo se envían las decisiones que impulsó; una sección de hallazgos se lee como autofelicitación y no le dice nada al lector.
• El documento no lleva recuentos de vanidad ("27 entradas", "9 spikes pendientes"). Los números aparecen cuando describen el sistema, no el esfuerzo.

Fase 0 — Andamio y diagnóstico

Ejecuta $TOOL scaffold --title <nombre>. Cada documento de diseño vive en su propio directorio nuevo — scaffold crea ./<slug>/ (pasa una ruta explícita como argumento posicional para colocarlo en otro lugar) y rechaza un destino no vacío, por lo que un diseño nunca se mezcla con los archivos de otro o con un proyecto existente. Entrevista al usuario sobre el sistema actual antes de proponer nada: qué existe, qué duele y por qué. Escribe el diagnóstico en NOTES.md como causas raíz, no síntomas ("la latencia de durabilidad es la latencia de S3", no "las escrituras son lentas"). El diagnóstico nunca va en un tablero: escríbelo directamente en NOTES.md, el usuario lo revisa en el documento renderizado, y cada corrección que hacen se incorpora de nuevo con sus propias palabras. Cierra el diagnóstico con la única clasificación de la que cuelga el resumen ejecutivo: un cambio a un sistema que existe hoy, o nuevo, sin nada detrás excepto requisitos. Nombra los tres a cinco temas del diseño al mismo tiempo ("almacenamiento", "despacho", "tenencia"): se convierten en el mapa themes bajo el que se archivan las decisiones y suposiciones, y un tema que el diagnóstico no puede nombrar es un tema que el diseño no tiene. Diseñar contra un diagnóstico incorrecto desperdicia todas las fases posteriores.

Criterio de salida: el directorio del proyecto existe; el usuario ha leído el diagnóstico en el documento renderizado, incluidos cambio o nuevo y los temas, y está de acuerdo con él.

Fase 1 — Suposiciones

Antes de la primera ronda, verifica la lista de habilidades disponibles en busca de cc-present:present (la habilidad de tablero /cc-present) e invócala con la herramienta Skill cuando esté listada; la entrevista se ejecuta como un tablero en vivo desde la primera pregunta, con AskUserQuestion solo como respaldo sin cc-present. Este plugin incluye su propio paquete de bloques — ejecuta cc-present pack list y lee el fragmento de referencia de design-doc; su bloque design-doc.fork es la superficie de la entrevista, y el único bloque que lleva un tablero de entrevista.

Escribe las suposiciones directamente en registers.json; ningún tablero las confirma o las desafía. Nunca pongas un bloque design-doc.claims, un barrido de confirmar/desafiar, o un volcado de registro frente al usuario: revisan las suposiciones en el documento renderizado, y una corrección que hacen se incorpora de nuevo con sus propias palabras. Una suposición sin la cual el diseño no puede proceder y que requiere elegir entre opciones es una bifurcación, y va al tablero de la Fase 2 como un bloque design-doc.fork. Recopila verdades fundamentales de la entrevista de diagnóstico, el código y lo que el usuario ya ha dicho: restricciones que el diseño debe satisfacer, hechos sobre escala y carga de trabajo, cosas que el usuario cree pero no ha verificado. Cada una se convierte en una entrada A# con estado working o validate; marca la crítica, y registra quién tiene que confirmar cada entrada validate como un elemento abierto. Cuando el usuario señala una suposición como inestable, esa bandera va en la entrada; resolverla en su nombre derrotaría el propósito del registro.

Criterio de salida: el usuario ha revisado las suposiciones en el documento renderizado y cubren lo que el usuario sabe; $TOOL check está limpio.

Fase 2 — Rondas de diseño

Diseña mediante rondas de preguntas. La entrevista es un tablero cc-present que pregunta todas las bifurcaciones abiertas a la vez, cada una como un bloque design-doc.fork con opciones enriquecidas: una consecuencia en cada opción, pros y contras, exactamente una recomendada y la alternativa de lista abierta. El tablero lleva bloques de bifurcación y nada más. Cualquier cosa fuera de las bifurcaciones es un defecto: un bloque design-doc.claims, un barrido de confirmar/desafiar, un volcado design-doc.registers o un bloque de contexto. La propia pregunta de una bifurcación, sus consecuencias y sus pros y contras llevan el contexto que necesitan. Las respuestas que abren nuevas bifurcaciones van al siguiente tablero, construido de la misma manera.

Las rondas se ejecutan en un tablero cc-present en vivo: antes de la primera ronda (en la Fase 1 y aquí de nuevo), verifica la lista de habilidades disponibles en busca de cc-present:present (la habilidad de tablero /cc-present) e invócala con la herramienta Skill — sus instrucciones gobiernan la composición y el envío del tablero, y cada ronda a partir de entonces pasa por un tablero. Una bifurcación es un bloque design-doc.fork, cuyas opciones llevan su consecuencia en línea y cuya alternativa devuelve {defer: {title, why}}: el humano nombra la pregunta abierta, por lo que la Q# aterriza sin gastar otra ronda preguntando cómo llamarla. Cuando falta el paquete, un bloque choice simple lleva la misma forma manualmente — descripciones de consecuencia en cada opción, exactamente una marcada "(Recomendada)", y una última opción "Agregar a la lista abierta" que realmente encola una Q# — y AskUserQuestion es la superficie de último recurso, utilizada solo cuando cc-present:present está ausente de la lista de habilidades. Mientras exista la habilidad de tablero, las bifurcaciones de diseño nunca pasan por AskUserQuestion. Pregunta cada bifurcación como una pregunta simple que una persona pueda responder en frío ("¿Cómo deberían los workers recibir trabajos?"). El ID del registro que resuelve va en el campo decides del bloque, o sigue al header de AskUserQuestion, nunca en el texto de la pregunta; la consecuencia de una opción dice qué sucede, no qué entrada reemplaza. Las rondas son una entrevista, no una encuesta: señala fallos en el borrador actual, sugiere alternativas que el usuario no nombró, presiona cuando la evidencia no está de acuerdo y no decidas nada tú mismo. Cada respuesta se convierte en un DQ# con la resolución, las alternativas rechazadas y el número de ronda. Cuando una ronda posterior cambia una decisión anterior, supersede: un nuevo DQ#, un puntero by en la anterior.

Criterio de salida: no queda ninguna bifurcación no decidida fuera de la lista abierta; cada DQ# se remonta a una ronda en qa-log.json.

Fase 3 — Revisión adversaria

Ataca el borrador intermedio, antes de que el pulido haga más difíciles de ver los fallos. Usa la habilidad del plugin codex cuando esté disponible; de lo contrario, genera un subagente de nuevo contexto sin participación en el diseño y con un resumen para atacarlo como un ingeniero senior escéptico: errores de corrección, modos de fallo faltantes, números injustificados. Guarda la salida textualmente como <revisor>-review-<fecha>.md, indexa cada hallazgo en el registro findings (solo datos — nunca renderizados), y dispone de cada uno: una nueva decisión, un elemento abierto o un rechazo registrado con una razón. Un hallazgo corregido por código lleva el pull request que lo corrigió como el quinto elemento de la fila, en la misma forma que una entrada links[]. Un hallazgo que necesita la decisión del usuario se convierte en una ronda como cualquier otra, cuya pregunta dice lo que el revisor encontró, en palabras; el número de hallazgo

...

[truncado para traducción]