gonzalezpazmonica/human-code-map
.claude/skills/human-code-map/SKILL.md
Genera y mantiene mapas narrativos de componentes (.hcm) para luchar activamente contra la deuda cognitiva. Usar PROACTIVELY cuando: se incorpora un dev nuevo, se toca un módulo sin mapa, debt-score > 6, o se detecta que alguien re-lee el mismo código repetidamente.
$ install --global
skillsauthnpx skillsauth add gonzalezpazmonica/pm-workspace human-code-mapInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 17, 2026, 2:49 AM6.4s2 files scanned
SKILL.md
- name:
- human-code-map
- description:
- Genera y mantiene mapas narrativos de componentes (.hcm) para luchar activamente contra la deuda cognitiva. Usar PROACTIVELY cuando: se incorpora un dev nuevo, se toca un módulo sin mapa, debt-score > 6, o se detecta que alguien re-lee el mismo código repetidamente.
- summary:
- |
- Pipeline de 4 fases:
- cargar .acm del componente → analizar código real →
- Output:
- fichero .hcm con story, modelo mental, gotchas, decisiones y debt-score.
- maturity:
- experimental
- context:
- fork
- category:
- quality
- tags:
- ["comprehension", "cognitive-debt", "documentation", "onboarding", "mental-model"]
- priority:
- high
- allowed-tools:
- [Read, Write, Edit, Glob, Grep, Bash]
- model:
- sonnet
- context_cost:
- medium
Human Code Map — Skill
Por qué existe este skill
La deuda cognitiva es el coste invisible de los sistemas de software. Los .acm resuelven la comprensión para los agentes de IA. Los .hcm resuelven la comprensión para los desarrolladores humanos. Sin .hcm, el conocimiento de un módulo muere con la persona que lo escribió.
Referencia: https://addyosmani.com/blog/comprehension-debt/
Regla del skill
Ver docs/rules/domain/hcm-maps.md — formato, lifecycle, debt score, relación con .acm.
Fase 1 — Cargar contexto del componente
Input: path de componente o nombre de servicio
- Leer
.agent-maps/INDEX.acmpara localizar la capa/sección relevante - Leer el
.acmde la capa correspondiente (entities/services/infrastructure/api) - Leer los ficheros principales del componente (máx 5, los más relevantes)
- Si existe un
.hcmprevio, leerlo para preservar gotchas y decisiones históricas
Output: contexto suficiente para generar narración precisa sin inventar.
Fase 2 — Análisis de deuda
Calcular debt-score antes de generar (fórmula en hcm-maps.md):
- Staleness penalty: días sin paseo / 30 × 2 (máx 4)
- Complexity: líneas >200 → 3, >80 → 2, ≤80 → 1
- Coverage gap: (1 - cobertura) × 3
Si DEBT_SCORE > 7 → avisar al PM antes de generar.
Fase 3 — Generar borrador narrativo
Generar cada sección del .hcm con instrucciones específicas:
La historia (1 párrafo)
No describir ficheros — describir el problema que resuelve y cómo lo piensa el sistema. Usar el tiempo presente. Evitar jerga técnica innecesaria.
Correcto: "El pipeline SDD transforma un PBI vago en código deployable pasando por 5 agentes en secuencia, donde cada agente valida el trabajo del anterior antes de continuar."
Incorrecto: "El skill spec-driven-development contiene los ficheros SKILL.md y DOMAIN.md que definen el proceso..."
El modelo mental
Identificar la abstracción central del componente. Una analogía si ayuda. ¿Qué concepto del mundo real modela? ¿Qué invariante mantiene siempre?
Puntos de entrada
Para cada operación común, dar la ruta exacta de inicio: fichero, función, línea.
Basado en los Public API del .acm correspondiente.
Gotchas
Buscar en el código:
- Comentarios
// HACK,// TODO,// NOTE,// WARNING - Condiciones con nombres no obvios
- Efectos secundarios en funciones con nombres inocentes
- Orden de operaciones que no es obvio
Si existe un .hcm previo, preservar los gotchas validados por humanos.
Por qué está construido así
Buscar en:
adrs/si existedecision-log.mdsi existe- Mensajes de commit relevantes:
git log --oneline -- {fichero} | head -20 - Comentarios de diseño en el código
Indicadores de deuda
- Complexity metrics (lines, deps, nesting)
- Coverage gaps (si existe test-coverage report)
- Áreas marcadas con TODO/FIXME
- Código que el análisis detecta pero ningún test cubre
Fase 4 — Ciclo de validación
El borrador generado NO es el .hcm final. Requiere validación humana.
Output al usuario:
📝 Borrador .hcm generado: .human-maps/{path}.hcm
debt-score estimado: {N}/10
⚠️ ACCIÓN REQUERIDA antes de marcar como válido:
[ ] Leer la sección "La historia" — ¿describe el problema correcto?
[ ] Leer "Gotchas" — ¿hay algo que falta o que está incorrecto?
[ ] Leer "Por qué está construido así" — ¿captura las decisiones reales?
[ ] Actualizar last-walk: con la fecha de hoy tras validar
El .hcm no protege contra deuda cognitiva hasta que un humano lo haya leído.
El campo last-walk: solo se actualiza cuando el humano confirma la validación.
Un .hcm con last-walk: = fecha de generación automática sin validación = no es fiable.
Integración con .acm
| Evento | .acm | .hcm |
|--------|------|------|
| Código cambia | Hash inválido → regenerar | Stale automático si .acm stale |
| Nuevo componente | Añadir sección | Crear borrador .hcm |
| Componente eliminado | Eliminar sección | Archivar en .human-maps/_archived/ |
| Dev nuevo llega | — | Cargar .hcm del módulo que va a tocar |
Cuándo NO generar .hcm
- Componentes con < 50 líneas de código (overhead mayor que beneficio)
- Ficheros de configuración pura (el .hcm sería solo repetición del .acm)
- Código generado automáticamente (migrations, scaffolding)
- Scripts de un solo uso (no hay deuda cognitiva a gestionar)
Output esperado
.human-maps/{capa}/{componente}.hcm — obligatorias: header, La historia, El modelo mental, Puntos de entrada, Gotchas. Opcionales: Por qué está construido así, Indicadores de deuda. Límite: 150 líneas.
Related Skills
gonzalezpazmonica/skill-creator
testing
VerifiedTrustedCommunity
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
40SKILL.mdUpdated May 24, 2026
gonzalezpazmonica/mcp-builder
tools
VerifiedTrustedCommunity
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
40SKILL.mdUpdated May 24, 2026
gonzalezpazmonica/wellbeing-guardian
tools
VerifiedTrustedCommunity
Sistema proactivo de bienestar individual
33SKILL.mdUpdated Apr 17, 2026
gonzalezpazmonica/web-research
development
VerifiedTrustedCommunity
Search the web to resolve context gaps — documentation, versions, CVEs, best practices. Auto-starts SearxNG Docker if available, falls back to WebSearch.
33SKILL.mdUpdated Apr 17, 2026