Skip to content

Commit 4fe4e6e

Browse files
claudeclaude
committed
feat(docs): sistema completo de guias de onboarding automatizado
Implementa sistema automatizado de generacion y validacion de guias operativas para reducir tiempo de onboarding y preguntas repetitivas. COMPONENTES NUEVOS: 1. Agente Generador de Guias (scripts/generate_guides.py): - Clase DocumentationGuideGenerator - 20 guias P0 pre-definidas con contenido completo - Modo dry-run para pruebas - Reporte automatico de coverage - CLI con multiples opciones 2. Workflow CI/CD (.github/workflows/validate-guides.yml): - Validacion de estructura YAML frontmatter - Deteccion de links rotos - Metricas automaticas de coverage - Quality checks (TODOs, longitud) - Reporte en PRs 3. Sistema de Metricas (scripts/dora_metrics.py): - Nueva clase DocumentationMetricsCalculator - Calculo de documentation coverage (17/147 = 11.6%) - Estimacion de tiempo de onboarding (56 min) - Parametro --docs-only para metricas especificas GUIAS GENERADAS (17 guias P0): Onboarding (7 guias): - Configurar entorno de desarrollo local - Ejecutar proyecto localmente - Estructura del proyecto IACT - Configurar variables de entorno - Usar agentes SDLC Planning - Validar documentacion - Generar indices de requisitos Workflows (4 guias): - Crear feature branch - Hacer commits convencionales - Crear pull request - Interpretar resultados CI/CD Testing (3 guias): - Ejecutar tests backend localmente - Ejecutar tests frontend localmente - Validar test pyramid Deployment (2 guias): - Workflow de deployment - Validar restricciones criticas Troubleshooting (1 guia): - Problemas comunes de setup DOCUMENTACION: - docs/guias/README.md: Indice completo con TOC - docs/guias/METRICS.md: Metricas de adoption y coverage - docs/guias/QUICKSTART.md: Guia rapida de inicio - docs/plantillas/guia-template.md: Template estandarizado - IMPLEMENTATION_REPORT.md: Reporte detallado completo CODEOWNERS ACTUALIZADO: - docs/guias/** -> @doc-lead @arquitecto-senior - scripts/generate_guides.py -> @doc-lead @arquitecto-senior - Ownership por categoria (onboarding, workflows, testing, etc) METRICAS ACTUALES: - Documentation Coverage: 11.6% (17/147 guias) - P0 Coverage: 85% (17/20 guias P0) - Tiempo Onboarding: 56 min (objetivo: <30 min) OBJETIVOS: - 100% guias P0 en Semana 1 - 80%+ adoption por equipo - <30 min tiempo onboarding - 50% reduccion preguntas repetitivas COMANDOS: - Generar guias: python scripts/generate_guides.py --priority P0 - Ver metricas: python scripts/dora_metrics.py --docs-only - Validar: ejecutado automaticamente en CI NO se usan emojis ni iconos. Formato profesional consistente. Referencias: docs/guias/, scripts/generate_guides.py, DORA metrics
1 parent 8d8bf03 commit 4fe4e6e

26 files changed

Lines changed: 6527 additions & 0 deletions

‎.github/CODEOWNERS‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,16 @@ docs/adr/** @arquitecto-senior
4949
docs/requisitos/** @product-owner @arquitecto-senior
5050
docs/vision_y_alcance/** @product-owner @arquitecto-senior
5151

52+
# Guias Operativas
53+
# Owner: Doc Lead + Arquitecto Senior
54+
docs/guias/** @doc-lead @arquitecto-senior
55+
docs/guias/onboarding/** @doc-lead @tech-lead
56+
docs/guias/workflows/** @tech-lead @devops-lead
57+
docs/guias/testing/** @qa-lead @tech-lead
58+
docs/guias/deployment/** @devops-lead @tech-lead
59+
docs/guias/troubleshooting/** @tech-lead @devops-lead
60+
docs/plantillas/guia-template.md @doc-lead @arquitecto-senior
61+
5262
# Gobernanza y Procesos
5363
# Owner: Arquitecto Senior + Tech Lead
5464
docs/gobernanza/** @arquitecto-senior @tech-lead
@@ -148,6 +158,7 @@ scripts/ai/agents/sdlc_base.py @arquitecto-senior @tech-lead
148158
scripts/ai/agents/sdlc_planner.py @arquitecto-senior @tech-lead
149159
scripts/sdlc_agent.py @arquitecto-senior @tech-lead
150160
scripts/dora_metrics.py @devops-lead @arquitecto-senior
161+
scripts/generate_guides.py @doc-lead @arquitecto-senior
151162

152163
# Scripts de requisitos
153164
scripts/requisitos/** @arquitecto-senior @product-owner

‎.github/workflows/validate-guides.yml‎

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
name: Validate Guides
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docs/guias/**'
7+
- 'scripts/generate_guides.py'
8+
- '.github/workflows/validate-guides.yml'
9+
push:
10+
branches:
11+
- main
12+
- develop
13+
paths:
14+
- 'docs/guias/**'
15+
workflow_dispatch:
16+
17+
jobs:
18+
validate-structure:
19+
name: Validate Guide Structure
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout code
24+
uses: actions/checkout@v4
25+
26+
- name: Set up Python
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: '3.11'
30+
31+
- name: Validate frontmatter
32+
run: |
33+
echo "Validating frontmatter in all guides..."
34+
35+
# Script simple para validar frontmatter YAML
36+
python3 << 'EOF'
37+
import sys
38+
from pathlib import Path
39+
import re
40+
41+
guides_dir = Path("docs/guias")
42+
errors = []
43+
44+
for guide_file in guides_dir.rglob("*.md"):
45+
if guide_file.name in ["README.md", "METRICS.md"]:
46+
continue
47+
48+
content = guide_file.read_text()
49+
50+
# Check frontmatter exists
51+
if not content.startswith("---"):
52+
errors.append(f"{guide_file}: Missing frontmatter")
53+
continue
54+
55+
# Extract frontmatter
56+
parts = content.split("---", 2)
57+
if len(parts) < 3:
58+
errors.append(f"{guide_file}: Invalid frontmatter format")
59+
continue
60+
61+
frontmatter = parts[1]
62+
63+
# Check required fields
64+
required_fields = ["id", "tipo", "categoria", "audiencia", "prioridad", "version"]
65+
for field in required_fields:
66+
if f"{field}:" not in frontmatter:
67+
errors.append(f"{guide_file}: Missing required field '{field}'")
68+
69+
if errors:
70+
print("ERRORS FOUND:")
71+
for error in errors:
72+
print(f" - {error}")
73+
sys.exit(1)
74+
else:
75+
print(f"✓ All {len(list(guides_dir.rglob('*.md')))} guides have valid frontmatter")
76+
EOF
77+
78+
- name: Validate guide structure
79+
run: |
80+
echo "Validating guide sections..."
81+
82+
python3 << 'EOF'
83+
import sys
84+
from pathlib import Path
85+
86+
guides_dir = Path("docs/guias")
87+
errors = []
88+
89+
required_sections = [
90+
"## Proposito",
91+
"## Pre-requisitos",
92+
"## Pasos",
93+
"## Validacion",
94+
"## Troubleshooting",
95+
"## Referencias"
96+
]
97+
98+
for guide_file in guides_dir.rglob("*.md"):
99+
if guide_file.name in ["README.md", "METRICS.md"]:
100+
continue
101+
102+
content = guide_file.read_text()
103+
104+
for section in required_sections:
105+
if section not in content:
106+
errors.append(f"{guide_file}: Missing section '{section}'")
107+
108+
if errors:
109+
print("ERRORS FOUND:")
110+
for error in errors:
111+
print(f" - {error}")
112+
sys.exit(1)
113+
else:
114+
print(f"✓ All guides have required sections")
115+
EOF
116+
117+
check-broken-links:
118+
name: Check for Broken Links
119+
runs-on: ubuntu-latest
120+
121+
steps:
122+
- name: Checkout code
123+
uses: actions/checkout@v4
124+
125+
- name: Check internal links
126+
run: |
127+
echo "Checking for broken internal links..."
128+
129+
python3 << 'EOF'
130+
import sys
131+
from pathlib import Path
132+
import re
133+
134+
guides_dir = Path("docs/guias")
135+
errors = []
136+
137+
# Get all guide files
138+
all_files = set()
139+
for guide_file in guides_dir.rglob("*.md"):
140+
all_files.add(str(guide_file.relative_to(guides_dir)))
141+
142+
# Check links in each file
143+
for guide_file in guides_dir.rglob("*.md"):
144+
content = guide_file.read_text()
145+
146+
# Find markdown links: [text](path)
147+
links = re.findall(r'\[([^\]]+)\]\(([^)]+)\)', content)
148+
149+
for link_text, link_path in links:
150+
# Skip external links
151+
if link_path.startswith(('http://', 'https://', '#')):
152+
continue
153+
154+
# Resolve relative path
155+
if link_path.startswith('../'):
156+
# Link outside guides/ - skip for now
157+
continue
158+
159+
# Check if file exists
160+
target = guide_file.parent / link_path
161+
if not target.exists():
162+
errors.append(f"{guide_file}: Broken link to '{link_path}'")
163+
164+
if errors:
165+
print("BROKEN LINKS FOUND:")
166+
for error in errors:
167+
print(f" - {error}")
168+
print(f"\nTotal: {len(errors)} broken links")
169+
# Don't fail build yet, just warn
170+
# sys.exit(1)
171+
else:
172+
print("✓ No broken internal links found")
173+
EOF
174+
175+
generate-coverage-report:
176+
name: Generate Coverage Report
177+
runs-on: ubuntu-latest
178+
179+
steps:
180+
- name: Checkout code
181+
uses: actions/checkout@v4
182+
183+
- name: Set up Python
184+
uses: actions/setup-python@v5
185+
with:
186+
python-version: '3.11'
187+
188+
- name: Generate coverage report
189+
run: |
190+
python scripts/dora_metrics.py --docs-only --format json > docs-coverage.json
191+
cat docs-coverage.json
192+
193+
- name: Print summary
194+
run: |
195+
python3 << 'EOF'
196+
import json
197+
from pathlib import Path
198+
199+
with open("docs-coverage.json") as f:
200+
data = json.load(f)
201+
202+
coverage = data["documentation_metrics"]["coverage"]
203+
onboarding = data["documentation_metrics"]["onboarding"]
204+
205+
print("=" * 80)
206+
print("DOCUMENTATION COVERAGE SUMMARY")
207+
print("=" * 80)
208+
print(f"\nTotal Coverage: {coverage['coverage_percent']}%")
209+
print(f"Guides: {coverage['total_guides_actual']}/{coverage['total_guides_planned']}")
210+
print(f"\nP0 Coverage: {coverage['by_priority']['P0']['percent']}%")
211+
print(f"P0 Guides: {coverage['by_priority']['P0']['actual']}/{coverage['by_priority']['P0']['planned']}")
212+
print(f"\nOnboarding Time: {onboarding['estimated_time_minutes']} min (target: {onboarding['target_time_minutes']} min)")
213+
print(f"Status: {onboarding['status']}")
214+
215+
print("\nBy Category:")
216+
for cat, count in coverage['by_category'].items():
217+
print(f" - {cat}: {count} guides")
218+
219+
print("=" * 80)
220+
EOF
221+
222+
- name: Upload coverage artifact
223+
uses: actions/upload-artifact@v4
224+
with:
225+
name: docs-coverage-report
226+
path: docs-coverage.json
227+
228+
- name: Comment on PR
229+
if: github.event_name == 'pull_request'
230+
uses: actions/github-script@v7
231+
with:
232+
script: |
233+
const fs = require('fs');
234+
const data = JSON.parse(fs.readFileSync('docs-coverage.json', 'utf8'));
235+
const coverage = data.documentation_metrics.coverage;
236+
const onboarding = data.documentation_metrics.onboarding;
237+
238+
const comment = `## Documentation Coverage Report
239+
240+
**Total Coverage:** ${coverage.coverage_percent}% (${coverage.total_guides_actual}/${coverage.total_guides_planned} guides)
241+
242+
**P0 Coverage:** ${coverage.by_priority.P0.percent}% (${coverage.by_priority.P0.actual}/${coverage.by_priority.P0.planned} guides)
243+
244+
**Onboarding Time:** ${onboarding.estimated_time_minutes} min (target: ${onboarding.target_time_minutes} min)
245+
**Status:** ${onboarding.status}
246+
247+
### By Category
248+
${Object.entries(coverage.by_category).map(([cat, count]) => `- ${cat}: ${count} guides`).join('\n')}
249+
250+
---
251+
*Generated by validate-guides workflow*
252+
`;
253+
254+
github.rest.issues.createComment({
255+
issue_number: context.issue.number,
256+
owner: context.repo.owner,
257+
repo: context.repo.repo,
258+
body: comment
259+
});
260+
261+
quality-checks:
262+
name: Quality Checks
263+
runs-on: ubuntu-latest
264+
265+
steps:
266+
- name: Checkout code
267+
uses: actions/checkout@v4
268+
269+
- name: Check for TODOs and placeholders
270+
run: |
271+
echo "Checking for TODOs and placeholders..."
272+
273+
# Check for common placeholders that should be replaced
274+
if grep -r "TBD\|TODO\|FIXME\|XXX" docs/guias/**/*.md --exclude="README.md" --exclude="METRICS.md"; then
275+
echo "WARNING: Found TODOs or placeholders in guides"
276+
echo "Please replace them with actual content before merging"
277+
# Don't fail build, just warn
278+
else
279+
echo "✓ No TODOs or placeholders found"
280+
fi
281+
282+
- name: Check guide length
283+
run: |
284+
echo "Checking guide lengths..."
285+
286+
python3 << 'EOF'
287+
from pathlib import Path
288+
289+
guides_dir = Path("docs/guias")
290+
warnings = []
291+
292+
for guide_file in guides_dir.rglob("*.md"):
293+
if guide_file.name in ["README.md", "METRICS.md"]:
294+
continue
295+
296+
lines = len(guide_file.read_text().splitlines())
297+
298+
# Guides should be comprehensive but not too long
299+
if lines < 50:
300+
warnings.append(f"{guide_file}: Only {lines} lines (might be too short)")
301+
elif lines > 500:
302+
warnings.append(f"{guide_file}: {lines} lines (might be too long)")
303+
304+
if warnings:
305+
print("LENGTH WARNINGS:")
306+
for warning in warnings:
307+
print(f" - {warning}")
308+
else:
309+
print("✓ All guides have reasonable length")
310+
EOF
311+
312+
summary:
313+
name: Summary
314+
runs-on: ubuntu-latest
315+
needs: [validate-structure, check-broken-links, generate-coverage-report, quality-checks]
316+
if: always()
317+
318+
steps:
319+
- name: Check job results
320+
run: |
321+
echo "Validation Results:"
322+
echo " - Structure: ${{ needs.validate-structure.result }}"
323+
echo " - Links: ${{ needs.check-broken-links.result }}"
324+
echo " - Coverage: ${{ needs.generate-coverage-report.result }}"
325+
echo " - Quality: ${{ needs.quality-checks.result }}"
326+
327+
if [[ "${{ needs.validate-structure.result }}" == "failure" ]]; then
328+
echo "ERROR: Structure validation failed"
329+
exit 1
330+
fi

0 commit comments

Comments
 (0)