# Requirements Synthesis > Ingest multiple client-provided documents (PDF, DOCX, XLSX, HTML, images, text, code) and synthesize them into a single structured REQUIREMENTS-DRAFT.md. Triggered by "synthesize these requirements", "read these client docs", "requirements synthesis", "combine these documents", "intake these files", "create requirements from these files". - Skill: `sid-surange/requirements-synthesis` (Agent Skill) - Install (CLI): `npx skillmds@latest add sid-surange/requirements-synthesis` - Raw SKILL.md: https://api.skillmd.com/api/skills/sid-surange/requirements-synthesis/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: SID-SURANGE (https://skillmd.com/u/sid-surange) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/sid-surange/requirements-synthesis --- # 📥 Skill: requirements-synthesis ## Purpose Clients send requirements as a mix of PDFs, Word docs, spreadsheets, images, and emails. Reading them individually and reconciling conflicts manually is slow and error-prone. This skill ingests everything in one pass and produces a single `REQUIREMENTS-DRAFT.md` that surfaces goals, constraints, user scenarios, open questions, and conflicts — ready to feed into `requirements-qa` for quality-checking or `spec-driven-development` for implementation planning. ## Trigger phrases - "synthesize these requirements" - "read these client docs" - "requirements synthesis" - "combine these documents into requirements" - "intake these files" - "create requirements from these files" - "summarise what the client sent" ## Supported file formats | Format | Examples | |--------|---------| | Text | `.txt`, `.md`, `.csv`, `.json`, `.xml` | | Code | `.py`, `.ts`, `.js`, `.yaml`, `.toml` | | HTML | `.html`, `.htm` | | PDF | `.pdf` | | Word | `.docx`, `.doc` | | Excel | `.xlsx`, `.xls`, `.csv` | | PowerPoint | `.pptx`, `.ppt` | | Images | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` | --- ## Prerequisites This skill requires **markitdown** to convert DOCX, XLSX, PDF, and other binary formats to readable text. Without it the skill will stop at the prerequisite check step. **Install once:** ```bash pip install "markitdown[all]" ``` Verify: ```bash markitdown --version ``` > markitdown is an MIT-licensed Microsoft open-source tool (110k+ stars). > It runs locally, sends nothing to the cloud, and requires no GPU. > Docs: https://github.com/microsoft/markitdown --- ## Steps ### Step 1 — Check prerequisites Run: ```bash python -c "import markitdown; print('markitdown ok')" 2>/dev/null || echo "NOT_INSTALLED" ``` (use `python3` if `python` is not found) PowerShell equivalent: `python -c "import markitdown; print('markitdown ok')" 2>$null; if (-not $?) { Write-Output 'NOT_INSTALLED' }` If output is `NOT_INSTALLED`, stop and tell the user: ``` markitdown is required for this skill. Install it with: pip install "markitdown[all]" Then re-trigger the skill. ``` Do not proceed until the check passes. --- ### Step 2 — Identify input files Ask the user (if not already provided): > "Which folder or files should I read? You can give me a folder path or list specific files." Accept: - A folder path — read all supported files in it (non-recursive by default; ask if recursive is needed) - A list of file paths List the files you found and confirm with the user before proceeding: ``` I found 6 files to process: 1. brief.pdf 2. user-stories.docx 3. data-model.xlsx 4. wireframes.png 5. api-notes.md 6. scope.html Proceed with all 6? ``` --- ### Step 3 — Convert and read each file For each file: **Text / Markdown / code / HTML / CSV:** Read directly with the Read tool. **All other formats (PDF, DOCX, XLSX, PPTX, images):** Convert with markitdown first: ```bash markitdown "" ``` Capture the markdown output. If conversion fails for a file, note it and continue — do not abort the whole run. Report failed files in the output. --- ### Step 4 — Analyse each document For each converted document, extract: | Element | What to look for | |---------|----------------| | **Goals** | What the client wants to achieve; success criteria | | **User scenarios** | Who uses it, what they do, what they need | | **Constraints** | Technical, legal, timeline, budget, platform limits | | **Out of scope** | Anything explicitly excluded | | **Decisions already made** | Technology choices, vendors, integrations locked in | | **Open questions** | Ambiguous or incomplete statements | | **Conflicts** | Statements that contradict something in another document | Track which source document each item came from. --- ### Step 5 — Synthesize into REQUIREMENTS-DRAFT.md Write the file to the repo root (or a path the user specifies): ```markdown # Requirements Draft — > Synthesized from: > Generated by: requirements-synthesis skill --- ## 1. Goals What success looks like according to the client documents. - *(source: filename)* - *(source: filename)* --- ## 2. User Scenarios Who uses the system and what they need to accomplish. | User / Role | Scenario | Source | |-------------|----------|--------| | | | | --- ## 3. Functional Requirements Specific behaviours the system must have. - [ ] *(source: filename)* - [ ] *(source: filename)* --- ## 4. Constraints Technical, legal, timeline, or budget limits that bound the solution. - *(source: filename)* --- ## 5. Out of Scope Anything the client has explicitly excluded. - *(source: filename)* --- ## 6. Decisions Already Made Technology choices, vendors, or integrations that are locked in. - *(source: filename)* --- ## 7. Open Questions Ambiguous or incomplete statements that need client clarification before implementation. - [ ] — *found in: filename, section: ...* - [ ] — *found in: filename* --- ## 8. Conflicts Between Documents Statements that contradict each other across source files. Do not resolve silently — flag for client. | Conflict | Document A says | Document B says | |----------|----------------|----------------| | | *(file)* | *(file)* | --- ## 9. Source Files Processed | File | Status | Notes | |------|--------|-------| | | ✅ Processed | | | | ❌ Failed | | ``` --- ### Step 6 — Report Tell the user: - File written to (path) - How many source files were processed successfully - Count of open questions found - Count of conflicts found - Recommended next step: *"Run `requirements-qa` to quality-check this draft, or `spec-driven-development` to begin implementation planning."* --- ## What this skill does NOT do - It does not resolve conflicts — it surfaces them for client clarification. - It does not invent requirements that are not in the source files. - It does not write implementation specs — use `spec-driven-development` for that. - It does not quality-check the output — use `requirements-qa` for that. ## Natural next steps ``` requirements-synthesis → requirements-qa → spec-driven-development (this skill) (quality check) (implementation spec) ``` ## Gotchas - markitdown performs text extraction, not OCR — a scanned or image-only PDF converts to empty or near-empty output rather than failing loudly. Check the converted text length against the file's page/size before treating it as processed; a suspiciously short result should be reported as a likely OCR gap, not silently included as "no requirements found here." - Spreadsheet conversion flattens formulas to their last-computed value, not the formula itself — a constraint expressed as a formula (a capacity limit, a pricing tier) may read as an opaque number with no context. Flag cells that look like derived values without an obvious source. - Treating everything markitdown outputs as equally authoritative can bury a throwaway comment in a doc's margin at the same weight as its main requirement — track source location (page/section), not just source file, so downstream conflict resolution can weigh statements appropriately.