md-review

Descripción general de la skill md-review

Qué hace md-review

md-review es una skill de presentación para Code Review que convierte una reseña de PR escrita en markdown en una revisión HTML de un solo archivo y dos columnas. Espera markdown de revisión con bloques cercados de diff unificado y comentarios etiquetados por severidad, como > [!BLOCKER], > [!MAJOR], > [!MINOR] o > [!NIT]. La salida coloca el diff renderizado a la izquierda, las tarjetas de anotación a la derecha, una navegación superior para saltar entre hallazgos y un pie obligatorio con el nombre del revisor.

Usuarios y flujos de trabajo ideales

La skill md-review encaja mejor en equipos que ya escriben notas de revisión de código estructuradas en markdown y quieren un artefacto HTML portable para compartir, archivar o entregar fuera de una plataforma de PR. Es útil para leads de ingeniería, revisores, responsables de documentación y flujos con agentes que convierten el análisis de un PR en una página de revisión pulida. Resulta especialmente valiosa cuando la severidad de los hallazgos, el anclaje a líneas y la accesibilidad importan más que un resumen simple en markdown.

Qué diferencia a md-review

A diferencia de un prompt genérico del tipo “haz que esta revisión se vea mejor”, md-review tiene un pipeline definido: diff_parser.py extrae hunks de diff unificado, annotation_extractor.py asocia los callouts de severidad con el bloque de diff inmediatamente anterior más cercano, y review_html_renderer.py genera el HTML final. El repositorio también documenta decisiones de renderizado en references/diff_rendering_canon.md, references/pr_annotation_ux.md y references/severity_coding.md, lo que hace que la salida sea más predecible que un formateo improvisado por un LLM.

Restricciones clave para adoptarlo

El principal bloqueo es la forma de la entrada. md-review no sirve para páginas markdown comunes, notas de versión ni informes narrativos sin hunks de diff. Se niega a renderizar si no hay un nombre de revisor explícito, y está diseñado para no codificar la severidad solo con color: las insignias incluyen iconos y texto aria-label para cumplir con WCAG 1.4.1. Si tu fuente no contiene diffs unificados reales, conviene derivar la tarea a una skill de renderizado de documentos.

Cómo usar la skill md-review

Instalación de md-review y archivos del repositorio que conviene revisar

Para gestores de skills compatibles con Claude, instala desde la ruta del repositorio de GitHub, por ejemplo:

npx skills add alirezarezvani/claude-skills --skill md-review

Después de instalar, lee primero SKILL.md para entender las reglas de invocación. Luego revisa estos archivos antes de usarla en producción:

• scripts/diff_parser.py para ver los formatos aceptados de bloques cercados de diff y --infer-diff
• scripts/annotation_extractor.py para entender el parseo de callouts y el comportamiento de asociación
• scripts/review_html_renderer.py para conocer flags obligatorios del renderizador, como --reviewer
• assets/md_review_template.html para revisar la estructura final de la página
• references/severity_coding.md para los niveles de severidad predeterminados y personalizados

Preparar una entrada que md-review pueda parsear

Un buen patrón de uso de md-review empieza con markdown que mantiene cada hallazgo cerca del diff que describe:

# Review: payment retry change

```diff
--- a/src/retry.py
+++ b/src/retry.py
@@ -14,6 +14,8 @@ def retry_payment():
-    attempts = 1
+    attempts = 5
+    timeout = None

[!BLOCKER]
This can retry indefinitely if the provider never returns. Add a bounded timeout.

Usa bloques cercados `diff` siempre que sea posible. El parser puede inferir algunos bloques sin etiqueta solo cuando se usa `--infer-diff`, pero los cercados explícitos reducen la ambigüedad. Coloca comentarios generales antes de cualquier diff solo si quieres que se rendericen como comentarios sin anclaje.

### Invocar md-review en un flujo de trabajo con agentes

La skill puede activarse cuando un orquestador markdown-html clasifica la entrada como `REVIEW`, o directamente con `/cs:md-review`. Un prompt completo debe incluir el markdown fuente, el nombre del revisor y cualquier cambio en la convención de severidad:

```text
/cs:md-review
Convert this markdown code review into a single-file HTML review.
Reviewer: Jane Doe
Use the default BLOCKER/MAJOR/MINOR/NIT severity convention.
Keep all diff hunks and attach annotations to the nearest preceding hunk.
[Paste review markdown here]

Si usas los scripts directamente, el flujo práctico es: parsear los bloques de diff a JSON, extraer las anotaciones contra esos hunks y luego renderizar el HTML con --reviewer. Los scripts usan solo la biblioteca estándar de Python, lo que facilita ejecutarlos en CI restringidos o en automatizaciones locales.

Consejos prácticos para mejorar la calidad de la salida

Para un mejor anclaje, coloca cada callout inmediatamente después del bloque de diff correspondiente. Para una mejor priorización, reserva BLOCKER para problemas que deben corregirse sí o sí y evita etiquetar cualquier inquietud como MAJOR. Para facilitar el escaneo, escribe la primera oración de cada anotación como el punto de decisión, porque la navegación de hallazgos usa vistas previas breves. Si tu equipo usa otras etiquetas, pasa una convención personalizada de cuatro niveles en orden de mayor a menor severidad, por ejemplo critical,important,suggestion,nit.

Preguntas frecuentes sobre la skill md-review

¿md-review es solo para Code Review?

Sí. md-review para Code Review es deliberadamente específica: convierte revisiones de PR en markdown con hunks de diff y anotaciones de severidad en una página HTML de revisión. No es un generador general de sitios markdown, no genera diffs de PR y no sustituye la escritura de la revisión en sí.

¿Qué pasa si mi markdown no tiene bloques de diff?

Es un mal encaje. El diseño central de la skill depende de hunks de diff unificado, números de línea, adiciones, eliminaciones y asociación de anotaciones. Sin bloques de diff, el resultado sería engañoso, por lo que el comportamiento previsto es rechazar la tarea o derivarla a una skill orientada a convertir markdown en HTML para documentos.

¿En qué es mejor md-review que un prompt normal?

Un prompt normal puede producir HTML atractivo, pero a menudo inventará reglas de diseño, omitirá convenciones de numeración de líneas o dependerá de señales de severidad basadas solo en color. md-review usa scripts concretos de parseo y renderizado, una UX de revisión de dos columnas documentada y restricciones explícitas de accesibilidad. Eso la hace más adecuada cuando importan la consistencia y la semántica de la revisión.

¿md-review es apta para principiantes?

Es apta para principiantes si ya entiendes los bloques cercados de código en markdown y los diffs unificados. Quienes solo tengan comentarios en prosa quizá necesiten generar o pegar primero un diff real del PR. El punto de partida más sencillo es ejecutar los modos de ejemplo de los scripts y luego adaptar la estructura del markdown de muestra a tu propia revisión.

Cómo mejorar la skill md-review

Mejorar las entradas de md-review antes de renderizar

La forma más rápida de mejorar la salida de md-review es mejorar la revisión fuente. Incluye rutas de archivo en encabezados estándar de diff unificado, conserva los encabezados de hunk @@ y mantén suficientes líneas de contexto para que los revisores entiendan el cambio. Cuando sea posible, usa un hallazgo por callout; combinar problemas no relacionados en una sola tarjeta MAJOR hace que la navegación superior sea menos útil.

Evitar modos de fallo comunes

Los fallos comunes incluyen omitir --reviewer, usar bloques cercados de diff mal formados, emplear etiquetas de severidad fuera de la convención configurada y colocar anotaciones demasiado lejos del diff al que hacen referencia. Otro problema más sutil es usar la severidad como tono en lugar de prioridad. Una preferencia de estilo redactada con dureza debería seguir siendo NIT; un problema de corrección redactado con calma puede ser BLOCKER.

Iterar después de la primera salida HTML

Después del primer renderizado, revisa tres cosas: si todos los hallazgos aparecen en la navegación superior, si las anotaciones se asocian con los hunks previstos y si los comentarios sin anclaje son realmente comentarios generales. Si una anotación termina en el lugar incorrecto, muévela más cerca del bloque de diff relevante en lugar de intentar arreglar el HTML manualmente.

Personalizar sin romper el modelo de revisión

Usa la personalización para reflejar convenciones del equipo, no para debilitar la estructura. Una lista personalizada de severidades es razonable si tu organización usa etiquetas como critical, important, suggestion y nit. Convertir la salida en un informe en prosa, ocultar los iconos de severidad o eliminar el pie con el revisor socava lo que md-review está diseñada para garantizar: una salida de revisión responsable, accesible y centrada en el diff.