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

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:

pip install "markitdown[all]"

Verify:

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:

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:

markitdown "<file_path>"

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:

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):

# Requirements Draft — <date>

> Synthesized from: <list source files>
> Generated by: requirements-synthesis skill

---

## 1. Goals

What success looks like according to the client documents.

- <goal> *(source: filename)*
- <goal> *(source: filename)*

---

## 2. User Scenarios

Who uses the system and what they need to accomplish.

| User / Role | Scenario | Source |
|-------------|----------|--------|
| <role> | <what they do / need> | <file> |

---

## 3. Functional Requirements

Specific behaviours the system must have.

- [ ] <requirement> *(source: filename)*
- [ ] <requirement> *(source: filename)*

---

## 4. Constraints

Technical, legal, timeline, or budget limits that bound the solution.

- <constraint> *(source: filename)*

---

## 5. Out of Scope

Anything the client has explicitly excluded.

- <item> *(source: filename)*

---

## 6. Decisions Already Made

Technology choices, vendors, or integrations that are locked in.

- <decision> *(source: filename)*

---

## 7. Open Questions

Ambiguous or incomplete statements that need client clarification before implementation.

- [ ] <question> — *found in: filename, section: ...*
- [ ] <question> — *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 |
|----------|----------------|----------------|
| <topic> | <statement> *(file)* | <statement> *(file)* |

---

## 9. Source Files Processed

| File | Status | Notes |
|------|--------|-------|
| <filename> | ✅ Processed | |
| <filename> | ❌ Failed | <reason> |

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.