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:

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"

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:

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

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