| name | technical-writing |
| version | 1.0.0 |
| author | Javier Montaño · Comunidad MetodologIA |
| argument-hint | doc-type: analysis|spec|handover|architecture|assessment depth: ejecutivo|tecnico|exhaustivo |
| description | Technical documentation precision — progressive disclosure, terminology consistency, evidence attribution, and reproducible analysis. Use when writing AS-IS analyses, functional specs, architecture documents, handover guides, or any deliverable requiring technical rigor and documentation standards. [EXPLICIT] |
| model | opus |
| context | fork |
| allowed-tools | ["Read","Write","Edit","Glob","Grep"] |
Technical Writing — Documentation Precision & Progressive Disclosure
Ensures technical deliverables are precise, reproducible, and progressively disclosed. Owns terminology consistency, evidence attribution, structural patterns, and anti-pattern enforcement across all discovery documentation. [EXPLICIT]
Grounding Guideline
Technical documentation is a knowledge contract. Every assertion is verifiable. Every term is consistent. Every section builds on the previous one. The reader must be able to reproduce the analysis, validate the conclusions, and act on the recommendations without needing the author.
Documentation Philosophy
- Progressive disclosure. TL;DR → sections → details → appendix. The executive reads 2 pages, the architect reads 20, the implementer reads 50. [EXPLICIT]
- Terminology as contract. One term = one meaning across the entire discovery. Zero ambiguous synonyms. [EXPLICIT]
- Traceable evidence. Every data point carries a source tag. The reader can verify without asking. [EXPLICIT]
- Information density. Every sentence contributes new information. Zero filler, zero repetition. [EXPLICIT]
Inputs
$1 — Document type: analysis, spec, handover, architecture, assessment (default: analysis)$2 — Depth: ejecutivo, técnico, exhaustivo (default: técnico)
Parse from $ARGUMENTS. [EXPLICIT]
Document Structure Patterns
Progressive Disclosure Architecture
Level 0: TL;DR (3-5 bullets)
├── Level 1: Section summaries (1 paragraph each)
│ ├── Level 2: Full sections with evidence
│ │ ├── Level 3: Technical detail, code refs, configs
│ │ └── Level 3: Diagrams, matrices, data tables
│ └── Level 2: Cross-references to related deliverables
└── Appendix: Raw data, methodology notes, glossary
Section Template
## [N]. Section Title
> **TL;DR**: [1-2 sentence summary with key metric]
[Analysis body — dense, evidence-tagged paragraphs]
| Finding | Evidence | Impact | Source |
|---------|----------|--------|--------|
| ... | ... | 🟢/🟡/🔴 | [TAG] |
💡 **Insight**: [Actionable interpretation of the data]
→ See [XX_Deliverable § Section] for related analysis
Evidence Attribution System
| Tag | Meaning | Confidence |
|---|
| [CÓDIGO] | Verified in source code | High — directly observable |
| [CONFIG] | Found in configuration files | High — directly observable |
| [DOC] | Referenced in documentation | Medium — may be outdated |
| [INFERENCIA] | Deduced from patterns | Medium — requires validation |
| [SUPUESTO] | Assumption, explicitly declared | Low — must be validated |
| [STAKEHOLDER] | Reported by stakeholder | Medium — subjective, cross-validate |
| [BENCHMARK] | Industry standard reference | Medium — context-dependent |
Attribution Rules
- Every quantitative claim must have at least one evidence tag
- Mixed evidence uses highest-confidence tag first:
[CÓDIGO][CONFIG]
- Inferences always state the reasoning: "X is inferred based on Y [INFERENCIA]"
- Assumptions always state the validation path: "Assumption: X. Validate with: Y [SUPUESTO]"
Terminology Consistency Protocol
1. First use: define the term in context
"El monolito (aplicación principal desplegada como una unidad) presenta..."
2. Subsequent uses: use the defined term consistently
✅ "El monolito requiere..."
❌ "La aplicación legacy..." (undefined synonym)
❌ "El sistema principal..." (another synonym)
3. Glossary: maintain implicit glossary across deliverables
- Same term = same meaning in 00 through 09
- If a term evolves (AS-IS → TO-BE), explicitly note the transition
Structural Patterns by Document Type
| Type | Structure | Key Sections | Mermaid Budget |
|---|
| Analysis (02-03) | Finding → Evidence → Impact | TL;DR, 10 sections, cross-refs | 2-4 diagrams |
| Spec (07) | Use Case → Rules → Acceptance | Actors, flows, business rules | 2-3 diagrams |
| Handover (09) | Phase → Tasks → Criteria | 90-day plan, RACI, risks | 1-2 diagrams |
| Architecture | Component → Interaction → Quality | C4, ADRs, quality attributes | 3-4 diagrams |
| Assessment | Dimension → Score → Evidence | Matrix, findings, recommendations | 1-2 diagrams |
Anti-Pattern Enforcement
| Anti-Pattern | Rule | Fix |
|---|
| Filler phrases | BLOCK | Delete entirely |
| Passive voice without agent | WARN | "Se implementó" → "El equipo implementó" or "El módulo X implementa" |
| Scores without justification | BLOCK | Every 🟢/🟡/🔴 needs evidence in same row |
| Tables without headers | BLOCK | Every table has labeled columns |
| Headings that skip levels | BLOCK | h1→h2→h3 only, no h1→h3 |
| Orphan sections (<2 sentences) | WARN | Expand or merge with parent |
| Acronyms without definition | BLOCK | Define on first use |
Callout System
| Icon | Usage | When |
|---|
| 💡 Insight | Actionable interpretation | After data/finding presentation |
| ⚖️ Trade-off | Decision with competing factors | Architecture/scenario choices |
| ⚠️ Risk | Identified risk with impact | Risk-bearing findings |
| 🔍 Evidence | Supporting data point | Deep technical evidence |
Output Configuration
- Language: Spanish (Latin American, business register — simple, clear, concise, direct)
- Attribution: Expert committee of the MetodologIA Discovery Framework
- Tagline: "Construido por profesionales, potenciado por la red agéntica de MetodologIA."
Validation Gate
| Criterion | Check |
|---|
| TL;DR present | 3-5 bullets at document top |
| Evidence tags on all claims | [CÓDIGO], [CONFIG], [DOC], [INFERENCIA], [SUPUESTO] |
| Heading hierarchy valid | h1→h2→h3, no skips |
| Tables have headers | Every table labeled |
| Cross-references valid | → See format, target deliverable exists |
| Zero filler | No "cabe señalar", "es importante destacar" |
| Terminology consistent | Same terms across the document |
| Mermaid diagrams present | Minimum 1 per deliverable |
Assumptions & Limits
- El input contiene datos tecnicos verificados o claramente etiquetados con nivel de confianza.
- Toda documentacion sigue el estandar markdown-excellence como baseline.
- Esta skill posee precision documental y estructura. NO posee persuasion narrativa (eso es copywriting) ni produccion de formato visual (eso es output-engineering).
- NUNCA producir precios. Solo FTE-meses, magnitudes, cost drivers.
Edge Cases
| Caso Borde | Estrategia de Manejo |
|---|
| Codebase con cobertura parcial (<30% documentado) | Usar [INFERENCIA] y [SUPUESTO] extensivamente. Declarar limitacion de cobertura en TL;DR. Priorizar documentacion de modulos criticos sobre cobertura uniforme. Incluir "Coverage Disclaimer" al inicio. |
| Codebase multilenguaje (>3 lenguajes) | Documentar distribucion de lenguajes como hallazgo. Usar identificadores en idioma original del codigo. Crear seccion de "Language Map" con porcentajes y modulos por lenguaje. |
| Cero documentacion previa existente | Flaggear como hallazgo critico en TL;DR. Usar [CODIGO] y [CONFIG] como fuentes primarias. Recomendar Sprint 0 de documentacion. Producir glossario como primer entregable. |
| Terminologia inconsistente en el sistema existente | Crear tabla de reconciliacion de terminos. Documentar sinonimos encontrados y el termino canonico elegido. Aplicar termino canonico consistentemente con nota de mapeo. |
Decisions & Trade-offs
| Decision | Justificacion | Alternativa Descartada |
|---|
| Progressive disclosure (TL;DR -> detalle -> apendice) | Multiples audiencias consumen el mismo documento a diferente profundidad. Reduce necesidad de documentos separados. | Documento monolitico: el ejecutivo nunca lo lee; el implementador pierde tiempo buscando detalle. |
| Terminologia como contrato (1 termino = 1 significado) | Elimina ambiguedad en documentacion tecnica. Evita errores de interpretacion en implementacion. | Sinonimos permitidos: genera confusion especialmente en equipos distribuidos. |
| Evidence tags obligatorios en toda afirmacion | Permite al lector verificar sin preguntar. Distingue hechos de inferencias. Reduce riesgo de decisiones basadas en supuestos no declarados. | Sin tags: imposible distinguir dato verificado de opinion. |
| Mermaid como formato de diagramas | Versionable en git, renderizable en markdown, editable sin herramientas especiales. | Imagenes estaticas: no versionables, dificiles de actualizar, rompen flujo de documentacion-as-code. |
Knowledge Graph
graph TD
subgraph Core["Core: Technical Writing"]
PD[Progressive Disclosure]
TERM[Terminology Contract]
EVID[Evidence Attribution]
STRUCT[Structural Patterns]
end
subgraph Inputs["Inputs"]
DOCTYPE[Document Type]
DEPTH[Profundidad]
CODE[Codebase Analysis]
FINDINGS[Hallazgos]
end
subgraph Outputs["Outputs"]
ANALYSIS[AS-IS Analysis]
SPEC[Functional Spec]
HANDOVER[Handover Guide]
ARCHIDOC[Architecture Doc]
end
subgraph Related["Related Skills"]
COPY[copywriting]
STORY[storytelling]
OUTPUT[output-engineering]
EDITORIAL[editorial-director]
end
DOCTYPE --> STRUCT
DEPTH --> PD
CODE --> EVID
FINDINGS --> TERM
PD --> ANALYSIS
STRUCT --> SPEC
EVID --> HANDOVER
TERM --> ARCHIDOC
COPY --> Core
STORY --> Core
Core --> OUTPUT
EDITORIAL --> Core
Output Templates
Template 1: Technical Analysis Document (Markdown)
Filename: {NN}_{Entregable}_{contexto}_{WIP|Aprobado}.md
# {NN}. {Titulo del Entregable}
## TL;DR
- {Hallazgo 1 con metrica clave}
- {Hallazgo 2 con metrica clave}
- {Hallazgo 3 con metrica clave}
## 1. {Seccion}
> **TL;DR**: {Resumen en 1-2 oraciones con metrica principal}
{Cuerpo de analisis con parrafos densos y evidence-tagged}
| Hallazgo | Evidencia | Impacto | Fuente |
|---|---|---|---|
| ... | ... | Alto/Medio/Bajo | [TAG] |
**Insight**: {Interpretacion accionable del dato}
> Ver [{XX}_Entregable Seccion] para analisis relacionado
## Glosario
| Termino | Definicion | Primera aparicion |
|---|---|---|
Template 2: Handover Guide (Markdown)
Filename: 09_Handover_{contexto}_{WIP|Aprobado}.md
# Handover Guide: {project}
## TL;DR
{5 bullets: que se entrega, a quien, y como empezar}
## Plan de 90 Dias
### Fase 1: Quick Wins (Dias 1-30)
| Actividad | Responsable | Criterio de Exito | Dependencia |
|---|---|---|---|
### Fase 2: Estabilizacion (Dias 31-60)
...
### Fase 3: Aceleracion (Dias 61-90)
...
## RACI
| Actividad | Responsable | Aprobador | Consultado | Informado |
|---|---|---|---|---|
## Riesgos de Transicion
| Riesgo | Probabilidad | Impacto | Mitigacion |
|---|---|---|---|
## Transition Success Criteria
- [ ] {Measurable criterion 1}
- [ ] {Measurable criterion 2}
Template 3: HTML (bajo demanda)
- Filename:
{NN}_{Entregable}_{contexto}_{WIP|Aprobado}.html
- Estructura: HTML self-contained branded (Design System MetodologIA v5). Light-First Technical. Incluye tabla de evidencias con filtros por tag ([CÓDIGO], [CONFIG], [DOC], [INFERENCIA], [SUPUESTO]), índice de secciones con progressive disclosure, y callouts con iconografía semántica. WCAG AA, responsive, print-ready.
Template 4: XLSX (bajo demanda)
- Filename:
{fase}_{entregable}_{contexto}_{WIP}.xlsx
- Generado con openpyxl y MetodologIA Design System v5. Encabezados con fondo navy y texto Poppins blanco, formato condicional por tag de evidencia y nivel de impacto, auto-filtros en todas las columnas, valores calculados sin fórmulas. Hojas: Hallazgos con evidencia, Glosario de términos, Matriz de cross-references, Anti-patterns detectados.
Template 5: PPTX (bajo demanda)
- Filename:
{fase}_{entregable}_{cliente}_{WIP}.pptx
- Generado con python-pptx y MetodologIA Design System v5. Slide master con gradiente navy, títulos en Poppins, cuerpo en Trebuchet MS, acentos gold. Máx 20 slides versión ejecutiva / 30 versión técnica. Notas del orador con referencias de evidencia por slide. Slides sugeridos: portada, TL;DR de hallazgos clave, estructura de progressive disclosure (niveles 0-3), tabla de evidencias con tags, glosario de términos canónicos, cross-references activos, anti-patterns detectados, recomendaciones priorizadas.
Evaluacion
| Dimension | Peso | Criterio |
|---|
| Trigger Accuracy | 10% | Se activa ante solicitudes de documentacion tecnica, AS-IS, spec, handover, o assessment |
| Completeness | 25% | TL;DR presente, evidence tags en toda afirmacion, jerarquia de headings valida, cross-refs activos |
| Clarity | 20% | Terminologia consistente; progressive disclosure funcional; cero frases de relleno |
| Robustness | 20% | Produce documentacion util con codebase parcial, sin documentacion previa, o con terminologia inconsistente |
| Efficiency | 10% | Genera estructura completa con parametros minimos (tipo + profundidad) |
| Value Density | 15% | Cada seccion aporta informacion nueva; cero repeticion entre niveles de disclosure |
Umbral minimo: 7/10
Cross-References
metodologia-copywriting — Transforma precision tecnica en prosa ejecutiva persuasivametodologia-storytelling — Aporta arco narrativo a la estructura documentalmetodologia-output-engineering — Produce formatos finales (HTML, DOCX) desde el markdown tecnicometodologia-editorial-director — Coordina consistencia cross-entregable
Edge Cases
- Sparse codebase: Rely more on [INFERENCIA] and [SUPUESTO] tags. Explicitly declare coverage limitations.
- Multilingual codebase: Document language distribution; use original-language identifiers.
- No documentation: Flag as finding. Use [CÓDIGO] and [CONFIG] as primary evidence sources.
Limits
- This skill owns documentation precision and structure. It does NOT own narrative persuasion (that's metodologia-copywriting) or visual format production (that's metodologia-output-engineering).
- Follows markdown-excellence standard as baseline.
Usage
Example invocations:
- "/technical-writing" — Run the full technical writing workflow
- "technical writing on this project" — Apply to current context
