MastersThesis/.claude/commands/documentation-review.md

Review and validate the documentation for this Master's Thesis project.

Instructions

1. Read metrics source files first to get the correct values:

   • docs/metrics/metrics_paddle.md - PaddleOCR results
   • docs/metrics/metrics_doctr.md - DocTR results
   • docs/metrics/metrics_easyocr.md - EasyOCR results
   • docs/metrics/metrics.md - Comparative summary
   • src/results/*.csv - Raw data from 64 trials per service (5-page tuning subset)
   • src/*/requirements.txt - Dependency versions used for the experiments

2. Review UNIR guidelines for formatting and structure rules:

   • instructions/plantilla_individual.htm - PRIMARY REFERENCE for all styling (CSS classes, Word styles)
   • instructions/plantilla_individual_files/ - Support files with additional style definitions
   • instructions/instrucciones.pdf - TFE writing instructions
   • instructions/plantilla_individual.pdf - Official template preview

   IMPORTANT: When styling elements (tables, figures, notes, quotes), ALWAYS check plantilla_individual.htm for existing Word/CSS classes (e.g., MsoQuote, MsoCaption, Piedefoto-tabla). Use these classes instead of custom inline styles.

UNIR Color Palette (from plantilla_individual.htm)

Color	Hex	Usage
Primary Blue	#0098CD	Headings, titles, diagram borders
Light Blue BG	#E6F4F9	Backgrounds, callout boxes, nodes
Dark Gray	#404040	Primary text
Accent Blue	#5B9BD5	Table headers, accent elements
Light Accent	#9CC2E5	Table borders
Very Light Blue	#DEEAF6	Secondary backgrounds, subgraphs
White	#FFFFFF	Header text, contrast

Table Styles (from template)

• MsoTableGrid - Basic grid table
• MsoTable15Grid4Accent1 - Styled table with UNIR colors (header: #5B9BD5, borders: #9CC2E5)
• Piedefoto-tabla - Table caption/source style

3. Validate each documentation file checking:

Data Accuracy

• All CER/WER values must match those in docs/metrics/*.md
• Verify: baseline, optimized, best trial, percentage improvement
• Verify: GPU vs CPU acceleration factor
• Verify: dataset size (pages)

UNIR Formatting

• Tables: **Tabla N.** *Descriptive title in italics.* followed by table, then a line that starts with Fuente: immediately after the table (no blank lines), e.g., Fuente: ...
  • Table titles must describe the content (e.g., "Comparación de modelos OCR")
• Figures: **Figura N.** *Descriptive title in italics.*
  • Figure titles must describe the content (e.g., "Pipeline de un sistema OCR moderno")
• Sequential numbering (no duplicates, no gaps)
• APA citation format for references

Word Generation Alignment

• Table sources are only captured when the line immediately after the table starts with Fuente: (per apply_content.py).
• Mermaid figures use the YAML title: for captions in Word output; **Figura N.** lines are ignored by the generator but should remain for UNIR compliance.

Mermaid Diagrams

• All diagrams must be in Mermaid format (no external images for flowcharts/charts)
• All Mermaid diagrams must use the UNIR color theme
• Required YAML frontmatter config (Mermaid v11+):

  ---
  title: "Diagram Title"
  config:
    theme: base
    themeVariables:
      primaryColor: "#E6F4F9"
      primaryTextColor: "#404040"
      primaryBorderColor: "#0098CD"
      lineColor: "#0098CD"
  ---
  flowchart LR
      A[Node] --> B[Node]
  

• Colors: #0098CD (UNIR blue for borders/lines), #E6F4F9 (light blue background)
• All diagrams must have a descriptive title: in YAML frontmatter
• Titles MUST be quoted: title: "Descriptive Title" (not title: Descriptive Title)
• Titles should describe the diagram content, not generic "Diagrama N"
• Verify theme is applied to all diagrams in docs/*.md

Note on Bar Charts (xychart-beta):

• Bar chart colors are automatically converted to light blue (#0098CD) during figure generation
• The xyChart.plotColorPalette config in YAML frontmatter does NOT work reliably with mmdc
• Instead, generate_mermaid_figures.py post-processes SVG to replace default colors (#ECECFF, #FFF4DD)
• No manual color configuration needed in xychart-beta blocks - they will be styled automatically

Files to Review

• docs/00_resumen.md - Resumen/Abstract
• docs/01_introduccion.md - Introducción
• docs/02_contexto_estado_arte.md - Contexto y estado del arte
• docs/03_objetivos_metodologia.md - Objetivos y metodología
• docs/04_desarrollo_especifico.md - Desarrollo específico (resultados)
• docs/05_conclusiones_trabajo_futuro.md - Conclusiones y trabajo futuro
• docs/06_referencias_bibliograficas.md - Referencias
• docs/07_anexo_a.md - Anexo técnico
• README.md - Project overview

4. Report findings with:

   • List of incorrect values found (with file:line references)
   • Formatting issues detected
   • Specific corrections needed
   • Overall documentation health assessment

5. Language: All docs/* files must be in Spanish. README.md and CLAUDE.md can be in English.

6. Audit Run (repeatable process):

   • Validate each Mermaid diagram that contains numbers against its stated source (CSV or metrics file).
   • Confirm every figure/table that includes metrics has a valid *Fuente:* line pointing to:
     • src/results/*.csv, src/results/correlations/*.csv, or docs/metrics/*.md, or
     • External sources listed in docs/07_anexo_a.md.
   • Record any missing or mismatched sources before making edits.

Writing Style (Required)

• Use fluent Spanish with standard punctuation, avoid long dashes.
• Prefer commas, semicolons, or short sentences over em dashes.
• Keep paragraphs concise and clear, avoid overly long sentences.

Data Integrity (Required)

• Do not invent or estimate values. Every numeric claim must be sourced from src/results/*.csv, docs/metrics/*.md, or external documentation explicitly listed in docs/07_anexo_a.md.
• If a value is not present in those sources, remove it or mark it as unknown and request clarification.
• Source of truth for OCR metrics in docs/00-07: use docs/metrics/*.md for both "Resultados del Subconjunto de Ajuste" and "Evaluación del Dataset Completo", and src/results/*.csv for tuning subset values referenced by those sections.

CSV Verification (Required)

Use the CSVs to validate best-trial values and to confirm that tuning-only figures are not confused with full-dataset results.

Interpretation Rules

• The CSVs are from tuning on pages 5-10, not the full 45-page dataset.
• Values like “best trial CER” and “best trial WER” must match the CSVs.
• Full-dataset metrics must be sourced elsewhere and clearly labeled as full evaluation.
• src/raytune_paddle_subproc_results_20251207_192320.csv is CPU-only timing reference; do not use it for accuracy claims.
• GPU results are the primary research driver. CPU results are only used to illustrate timing without GPU.