beam-ai-team/extract-requirements

Extract Requirements

Extract requirements from source materials (meeting transcripts, documents, emails, wikis) and organize them into structured, traceable requirement domain files.

Safety Contract

Before reading source folders or generating requirement files, show the projects in scope, source paths, output directory, proposed domain files, and whether quotes/speaker attribution will be included. Require explicit user approval in the current turn before writing or overwriting local files. Do not share source transcripts or generated requirements externally from this skill.

---

Purpose

This skill helps teams consolidate scattered requirements from various sources into well-organized, traceable documentation. It:

• Reads source materials chronologically
• Extracts requirements per project/agent/product
• Clusters requirements into logical domains
• Generates structured files with full source traceability
• Includes quotes and speaker attribution

---

Workflow

┌─────────────────────────────────────────────────────────────┐
│  1. DISCOVERY                                               │
│     • What projects to extract requirements for?            │
│     • Where are the source materials?                       │
│     • Any additional sources to consider?                   │
│     • Where to save output?                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  2. PROCESSING                                              │
│     • Read all sources chronologically                      │
│     • Extract requirements per project                      │
│     • Identify speakers/attributions                        │
│     • Note source file and date for each requirement        │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  3. DOMAIN PROPOSAL                                         │
│     • Cluster requirements into logical domains             │
│     • Present proposed domains to user                      │
│     • User confirms, adjusts, or requests changes           │
│     • Iterate until user approves                           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  4. GENERATION                                              │
│     • Create folder structure per project                   │
│     • Generate numbered domain files                        │
│     • Include source references, quotes, speakers           │
│     • Create README index for each project                  │
└─────────────────────────────────────────────────────────────┘

---

Step 1: Discovery

Questions to Ask User

MANDATORY - Ask these questions before starting extraction:

1.1 Projects/Products

What projects, agents, or products should I extract requirements for?

Examples:
- "B2B Check Agent and Email Triage Agent"
- "Mobile App v2"
- "Customer Portal redesign"

You can specify multiple - I'll create separate folders for each.

1.2 Source Materials

Where can I find the source materials?

Please provide:
- Folder path(s) containing meeting transcripts, documents, etc.
- File types to include (e.g., .md, .txt, .pdf)

Example: "04-workspace/client-meetings/"

1.3 Additional Sources (Optional)

Are there any additional sources I should consider?

Options:
- Additional folders with documents
- Specific files to include
- None - just the main folder

Example: "Also check 04-workspace/project-docs/ for technical specs"

1.4 Output Location

Where should I save the extracted requirements?

Default: 04-workspace/project-requirements/
Custom: Specify your preferred path

---

Step 2: Processing

2.1 Read Sources Chronologically

• Sort all source files by date (from filename or metadata)
• Process oldest to newest to capture requirement evolution
• Use parallel agents for efficiency when processing many files

2.2 Extract Per Project

For each source file, extract:

| Element | Description | |---------|-------------| | Requirement | The specific requirement or detail | | Project | Which project it applies to | | Context | Why this requirement exists | | Constraints | Any limitations or edge cases | | Source file | Path to source document | | Date | Meeting/document date | | Speaker | Who stated this (if available) | | Quote | Exact quote from source |

2.3 Handling Multiple Projects

When extracting, tag each requirement with the relevant project:

• Some requirements may apply to multiple projects
• Some sources may only discuss one project
• Keep requirements separated by project for output

---

Step 3: Domain Proposal

3.1 Clustering Logic

Group requirements into domains based on:

• Functional area (e.g., "Authentication", "Data Validation")
• Integration type (e.g., "Jira Integration", "API Connections")
• Workflow stage (e.g., "Trigger & Input", "Processing", "Output")
• Technical concern (e.g., "Error Handling", "Testing")

3.2 Present to User

For each project, present:

## [Project Name] - Proposed Requirement Domains

| # | Domain | Description | Est. Requirements |
|---|--------|-------------|-------------------|
| 1 | [Domain Name] | [Brief description] | ~X |
| 2 | [Domain Name] | [Brief description] | ~X |
...

Questions:
1. Does this domain structure make sense?
2. Should any domains be merged or split?
3. Any domains to add or rename?

3.3 Iterate Until Approved

• Accept user feedback
• Adjust domain structure
• Re-present if significant changes
• Proceed only after user confirms

---

Step 4: Generation

4.1 Folder Structure

{output-path}/
├── {project-1-slug}/
│   ├── README.md
│   ├── 01-{domain-1-slug}.md
│   ├── 02-{domain-2-slug}.md
│   └── ...
├── {project-2-slug}/
│   ├── README.md
│   ├── 01-{domain-1-slug}.md
│   └── ...

4.2 Output Format Example

Domain file structure:

# {Domain Name}

> **Project**: {Project Name}
> **Domain**: {Domain Name}
> **Last Updated**: {YYYY-MM-DD}

---

## Overview

{Brief description of what this domain covers}

---

## 1. {Section Name}

| Requirement | Details |
|-------------|---------|
| {Requirement} | {Description} |

**Source**: [2025-09-29 Meeting Title](relative/path/to/file.md)
> "Exact quote from source." — Speaker Name

---

## Open Questions / Blockers

| Item | Owner | Status |
|------|-------|--------|
| {Question} | {Person} | {Status} |

README structure:

# {Project Name} - Requirements Documentation

> **Generated**: {YYYY-MM-DD}
> **Source**: {N} files from {date range}

## Requirement Domains

| # | Domain | Description |
|---|--------|-------------|
| 1 | [{Domain}](01-domain.md) | {Brief description} |

## Key Metrics / Integrations / Timeline / Contacts
(Include sections as relevant based on extracted content)

---

Supported Source Types

| Type | Extensions | Notes | |------|------------|-------| | Meeting transcripts | .md, .txt | Primary source type | | Documents | .md, .txt, .pdf | Technical specs, PRDs | | Emails | .md, .txt, .eml | If exported as text | | Wiki exports | .md, .html | Confluence, Notion exports |

---

Best Practices

For Source Materials

• Use consistent date format in filenames (YYYY-MM-DD)
• Include speaker names in transcripts when possible
• Store related documents in date-based folders

For Extraction

• Process chronologically to capture requirement evolution
• Tag requirements that changed over time
• Note superseded requirements

For Domain Organization

• Aim for 5-15 domains per project
• Each domain should be cohesive
• Avoid too many small domains or too few large ones

---

Error Handling

| Scenario | Handling | |----------|----------| | Empty source folder | Inform user, ask for correct path | | No requirements found for a project | Confirm project name, suggest alternatives | | Speaker not identifiable | Use "— Source document" instead | | Ambiguous project assignment | Ask user to clarify |

---

Example Usage

User: "Extract requirements from our client meetings"

AI Response:

I'll help you extract and organize requirements. Let me ask a few questions:

1. What projects should I extract requirements for?
   (e.g., "API Gateway" and "Admin Dashboard")

2. Where are your meeting transcripts?
   (e.g., "04-workspace/client-meetings/")

3. Any additional sources to include?
   (e.g., technical docs, emails)

4. Where should I save the output?
   Default: 04-workspace/project-requirements/

---

Integration

• Works with any project structure
• Output compatible with other Nexus skills
• Can be re-run to update requirements as new sources are added