accessibility-annotator

What this skill does

<!-- ═══════════════════════════════════════════════════════════════════
  ACCESSIBILITY ANNOTATOR SKILL
  ═══════════════════════════════════════════════════════════════════

  PURPOSE:
  Takes an EXISTING Word document about a technical project and adds
  explanatory annotations so a brilliant non-CS reader can understand it.
  Unlike explain-project (which generates from scratch), this skill
  works with documents that already exist.

  WORKFLOW:
  Phase 1: Analysis — read the doc, identify opaque concepts, recommend
           mechanisms (sidebar, glossary, inline, footnote), present
           analysis table to user for approval
  Phase 2: Implementation — after approval, modify the Word document
           to add all annotations

  TARGET READER:
  A top-quintile intelligence mechanical engineer who has never taken
  a CS class. Sharp, process-oriented, comfortable with measurements
  and thresholds. Understands quality gates and structured problem-solving.

  COMPANION TOOLS:
  Paths below are defaults on the author's machine. Override via --style-json flag or environment variables.
  - CFA Style Guide: C:\Users\Troy Davis\dev\info\CFA_Word_Style_Guide.md
  - Image style: C:\Users\Troy Davis\dev\info\clean-style-sanitized.json
  - Image learnings: C:\Users\Troy Davis\dev\info\gemini-image-generation-learnings.md
  - docx skill: document-skills:docx (for Word document manipulation)

  HISTORY:
  Built 2026-03-27. Tested on:
  - cfa/pipeline/docs/knowledge-extraction-pipeline-overview.docx (42 annotations, 4 images)
  - cfa/kb-analysis/docs/knowledge-analysis-tool-overview.docx (35 annotations, 5 images)
  Reviewed by ME-persona agent. All 12 identified issues fixed.
  10 lessons learned baked into the skill.
  ═══════════════════════════════════════════════════════════════════ -->

# Accessibility Annotator

Make technical documents fully understandable by a brilliant reader who lacks computer science training.

**Target reader:** A top-quintile intelligence mechanical engineer. Sharp, process-oriented, comfortable with measurements and thresholds, experienced with quality systems and structured problem-solving. Has never taken a CS class.

## Inputs

Two required arguments (positional or prompted):
1. **Word document path** -- the .docx file to annotate
2. **Project directory path** -- the codebase the document describes (used for accurate, contextual explanations)

Optional flags:
- `--generate-images` -- Generate diagrams via Google Gemini and insert them directly into the document (default: OFF — costs money). When off, insert teal-bordered placeholder boxes with full generation prompts instead.
- `--style-json PATH` -- Path to the image style JSON for Nano Banana Pro prompt construction (default: `$IMAGE_STYLE_JSON` env var if set, otherwise provide via `--style-json` flag. Author's default: `C:\Users\Troy Davis\dev\info\clean-style-sanitized.json`)

Parse from the user's message. If missing, ask for the two required arguments.

<!-- ═══════════════════════════════════════════════════════════════════
  PHASE 1: ANALYSIS

  This phase reads the document, identifies every concept the target
  reader wouldn't understand, and recommends how to explain each one.
  The output is a structured analysis table presented to the user for
  review and approval before any changes are made.

  KEY PRINCIPLES:
  - Check for self-explanation: many good docs already explain things
  - Flag concepts, not just terms: "cosine similarity" is a term;
    "measuring how similar two texts are" is the concept
  - Map dependencies: can't explain cross-encoders without embeddings
  - Assess density: high-density sections need glossary, not inline
  ═══════════════════════════════════════════════════════════════════ -->

## Phase 1: Analysis

<!-- ─── DISPATCH: fork to isolated Explore agent ───
  Dispatch the entire Phase 1 analysis to an isolated subagent:
    context: fork
    agent: Explore
  Pass the document path, project directory path, and all flags as arguments.
  The Explore agent runs Steps 1–7 in full and returns the completed analysis
  table plus density summary, dependency map, and mechanism distribution.
  The parent skill receives the output and presents it to the user for approval
  (Step 7 ask prompt). Phase 2 begins only after user says "implement".
─── -->

### Step 1 -- Read the document

Extract text via pandoc:
```bash
pandoc "document.docx" -t markdown
```
Read the full output carefully. Note the document's voice, tone, and how it already explains concepts.

### Step 2 -- Survey the project

Read the project directory structure, README, CLAUDE.md, and 2-3 key source files. Build enough understanding to write accurate explanations later. Don't go deep yet -- that happens in Phase 2.

### Step 3 -- Identify opaque concepts

<!-- ─── CONCEPT FILTER ───
  This filter is calibrated for the specific target reader.
  An ME understands: processes, quality systems, measurements, hardware basics.
  An ME does NOT understand: ML/NLP, CS algorithms, software architecture patterns,
  database internals, DevOps, or named tools with non-obvious purpose.

  The most common mistake is flagging things the document already explains well.
  Always check surrounding context before flagging.
─── -->

Walk the document paragraph by paragraph. For each technical term or concept, apply the filter below.

**The ME WOULD understand (do not flag):**
- Process flows, staged pipelines, architecture as "how parts connect"
- Quality gates, thresholds, measurements, calibration, scoring
- Business logic, operational rationale, cost/benefit arguments
- Tables, metrics, percentages, scoring frameworks
- Procedures and step-by-step instructions
- "Database" as "a place that stores and retrieves information"
- Files, records, fields, filtering, sorting
- Statistical concepts: mean, standard deviation, precision, recall, accuracy, confidence, distributions, correlation
- Hardware: GPU, servers, CPU, memory, network, storage
- Acronyms that are expanded and self-explanatory in context

**The ME would NOT understand (flag these):**
- ML/NLP concepts: embeddings, vector similarity, transformers, tokenization, NER, NLI, cross-encoders, bi-encoders, attention, fine-tuning, inference temperature, context window, token budget, model parameters
- CS data structures and algorithms: inverted indexes, graph traversal, hash maps, B-trees, approximate nearest-neighbor, clustering algorithms (HDBSCAN, DBSCAN)
- Software architecture: REST API, microservices, SSE streaming, CORS, middleware, async processing, event-driven
- Database internals: vector databases, graph databases, Cypher queries, collections, upsert, indexing strategies (IVF, HNSW)
- Data formats beyond basic: JSON/JSONL structure, regex, serialization
- DevOps: Docker, CI/CD, containerization
- Named tools/frameworks with non-obvious purpose: ChromaDB, Neo4j, FAISS, FastAPI, GLiNER, vLLM, pandas, NumPy
- Techniques: TF-IDF, BM25, cosine similarity, Reciprocal Rank Fusion, PCA, anisotropy correction, Platt scaling, embedding dimensions

**Critical -- check for self-explanation:** If the document already explains a concept well enough for the target reader, do NOT flag it. Many good technical documents include "In plain English" sections or parenthetical clarifications. Only flag concepts that remain opaque after reading surrounding context.

**Critical -- flag the concept, not just the term:** "Cosine similarity" is a term. The concept is "measuring how similar two things are by comparing their numeric representations." Flag the concept only if the document doesn't convey this.

### Step 4 -- Map dependencies

<!-- ─── DEPENDENCY CHAINS ───
  Some concepts require understanding other concepts first.
  The glossary must be ordered by dependency (foundational first).
  Sidebars should be placed before the sections that use dependent concepts.
─── -->

Some concepts require others. Build a dependency list:
- "Cross-encoder rerankin