This skill should be used when the user asks to "upload a document", "import a diagram", "read this Word file", "use this PDF as input", "parse the completed interview", "import my answers from Word", "ingest an existing architecture document", or when processing uploaded files to extract EA-relevant content for use in artifacts or interviews.
This skill handles reading, parsing, and converting uploaded documents and diagrams into clean intermediate files before passing them to the ea-document-analyst for EA mapping.
Every uploaded document passes through three stages:
Upload (uploads/)
│
▼
ea-document-converter ← this skill governs this stage
Converts to .md or .mmd
Writes to uploads/converted/
│
▼
ea-document-analyst ← EA mapping: what to extract and where it goes
Maps content to artifacts
Presents confirmation summary
│
▼
Artifact population ← user-confirmed writes with 📎 source attribution
The converter stage produces a single canonical text representation regardless of source format. The analyst always receives either a Markdown file or a Mermaid file — never raw binary formats.
| Format | Conversion target | Use case |
|---|
.md / .txt | .md (pass-through) | Requirements, notes, existing artifacts |
.docx (Word) | .md | Architecture docs, completed interview forms |
.pdf | .md | Strategy documents, reports |
.xlsx / .csv | .md (tables) | Requirements lists, stakeholder registers |
.mmd | .mmd (pass-through) | Mermaid diagrams |
.dot | .mmd | Graphviz diagrams |
.drawio | .mmd | Draw.io diagrams |
.excalidraw | .mmd | Excalidraw diagrams |
.png / .jpg | .md (description + inferred diagram) | Architecture screenshots, scanned docs |
All uploaded files are stored in EA-projects/{slug}/uploads/ before processing. Converted intermediates are written to EA-projects/{slug}/uploads/converted/.
uploads/ with a timestamped name: {YYYY-MM-DD}-{original-filename}Invoke the ea-document-converter agent with the file path. The agent:
.md (document types) or .mmd (diagram types)uploads/converted/Conversion targets by format:
| Format | Output | Method |
|---|---|---|
.docx | {stem}.md | Read tool → structured Markdown; headings, tables, lists preserved |
.pdf | {stem}.md | Read tool → extracted text; heading levels inferred from whitespace |
.xlsx / .csv | {stem}.md | Rows → Markdown table(s); one table per sheet |
.drawio | {stem}.mmd | Parse <mxCell> XML → Mermaid flowchart |
.excalidraw | {stem}.mmd | Parse elements JSON → Mermaid flowchart |
.dot | {stem}.mmd | Translate nodes/edges → Mermaid graph |
.png / .jpg | {stem}.md | View image → description + inferred Mermaid block |
.md / .txt / .mmd | Pass-through | Copied with conversion header |
The converter adds a provenance comment to every output file:
<!-- Converted from: {original-filename} | Date: {YYYY-MM-DD} | Source format: {ext} -->
After conversion, invoke the ea-document-analyst agent with the converted file path. The analyst:
.md or .mmd from uploads/converted/⚠️ Needs clarificationOnly after user confirmation:
artifacts/📎 Source: uploads/{original-filename}When the uploaded document is a completed interview Word form:
ea-document-converter converts the .docx to .md preserving the Q&A structureea-document-analyst detects the interview form structure and applies the interview parsing workflow: maps each answer to its artifact field, applies answer state markers (⚠️, ➖, etc.)Approved artifacts from uploaded content without explicit user confirmation📎 Source: uploads/{filename}agents/ea-document-converter.md — Full conversion logic and format-specific methodsreferences/file-format-guide.md — Detailed parsing notes per file formatreferences/interview-form-structure.md — Interview Word export/import format specification