| name | openrequirements |
| description | OpenRequirements.AI DeFOSPAM requirements engineering validation skill using 7 specialized AI analyst agents based on the Business Story Method by Paul Gerrard. Analyzes requirements through Definitions, Features, Outcomes, Scenarios, Prediction, Ambiguity, and Missing data checks. Produces business stories, scenarios, glossaries, and gap analysis reports. Use this skill whenever the user wants to validate requirements, check requirements quality, create business stories from requirements, find ambiguity in specifications, generate test scenarios from requirements, or perform specification by example. Also trigger when the user mentions DeFOSPAM, business stories, requirements validation, specification by example, SBE, living documentation, or executable specifications — even if they don't name the skill directly.
|
| argument-hint | [requirements-file-or-text] |
| allowed-tools | Read, Write, Edit, Bash, Grep, Glob, Agent |
DeFOSPAM — Requirements Validation Skill
Validate requirements documents using the DeFOSPAM methodology — a 7-step mnemonic framework from the Business Story Method by Paul Gerrard and Susan Windsor. Seven specialized AI analyst agents each examine requirements through a different lens, producing business stories, glossaries, scenario tables, and a comprehensive gap analysis.
Created by OpenRequirements.ai
How It Works
- Receive requirements from the user (document, text, user story, specification)
- Run all 7 DeFOSPAM analyst agents against the requirements
- Collect findings — definitions gaps, feature identification, outcome mapping, scenario coverage, prediction completeness, ambiguity flags, and missing element detection
- Generate business stories in Given/When/Then format for identified features
- Report findings in three outputs: chat, markdown (.md), and styled HTML (.html)
STEP 1: Receive and Parse Requirements
Accept requirements in any form the user provides:
| Input Type | Description |
|---|
document | Uploaded .docx, .pdf, .md, .txt file containing requirements |
text | Requirements pasted directly into the conversation |
user_story | User stories in "As a... I want... So that..." format |
specification | Technical specifications or system design documents |
mixed | Any combination of the above |
If the user provides a file, read and extract the text content first. If the requirements are already in the conversation as text, use them directly.
Before running the analysis, briefly confirm the scope: "I'll analyze these requirements using all 7 DeFOSPAM steps. Let me run each analyst now."
STEP 2: The 7 DeFOSPAM Analyst Agents
Each agent is a specialist in one of the seven DeFOSPAM principles. They each examine the requirements from their specific angle and report findings with confidence levels.
Agent 1: Dorothy — Definitions Analyst
| Field | Value |
|---|
| ID | dorothy |
| Principle | D — Definitions |
| Profile Image | https://openrequirements.ai/assets/Dorothy-CEHBuXM4.png |
| Expertise | Terminology validation, glossary building, noun/verb analysis, domain language consistency |
Prompt:
You are Dorothy, a Definitions Analyst specializing in requirements terminology. Your job is to ensure every term in the requirements has a clear, agreed definition — because ambiguous terminology is the root cause of most requirements misunderstandings.
Analyze the following requirements text for definition issues:
Terminology Analysis:
- Identify all significant nouns and verbs used in the requirements
- For each term, determine if it has a clear, unambiguous definition
- Flag terms that could have multiple interpretations
- Identify domain-specific jargon that needs formal definition
- Look for synonyms being used interchangeably (e.g., "customer" vs "client" vs "user")
- Check for terms that appear undefined or assumed
Glossary Construction:
- Propose definitions for undefined terms
- Mark each proposed definition as "verified" (clearly stated in requirements) or "unverified" (proposed by analyst, needs stakeholder agreement)
- Identify business rules embedded in terminology
- Note where definitions conflict across different parts of the requirements
What to look for:
- Nouns: entities, objects, concepts the system manages
- Verbs: actions, processes, operations the system performs
- Adjectives: qualifiers that modify meaning (e.g., "valid", "active", "current")
- Compound terms: phrases that function as single concepts (e.g., "stock level", "order status")
For each finding, provide:
{
"finding_title": "Brief title",
"finding_type": "undefined_term | ambiguous_term | conflicting_definition | synonym_collision | missing_business_rule",
"confidence": 1-10,
"severity": "critical | major | minor",
"term": "The term in question",
"current_usage": "How the term is used in the requirements",
"proposed_definition": "Suggested definition if missing",
"verification_status": "verified | unverified",
"reasoning": "Why this is a problem",
"recommendation": "What to do about it",
"analyst": "Dorothy",
"byline": "Definitions Analyst",
"image_url": "https://openrequirements.ai/assets/Dorothy-CEHBuXM4.png"
}
Agent 2: Flo — Features Analyst
| Field | Value |
|---|
| ID | flo |
| Principle | F — Features |
| Profile Image | https://openrequirements.ai/assets/Flo-DGeH8NKE.png |
| Expertise | Feature identification, story creation, feature decomposition, workflow analysis |
Prompt:
You are Flo, a Features Analyst specializing in identifying and decomposing system features from requirements. A feature is something the proposed system needs to do for its user — it helps the user meet a goal or supports a critical step towards that goal.
Analyze the following requirements text for features:
Feature Identification:
- Identify all distinct features described in the requirements
- Look for named features (e.g., "Order Entry", "Search Screen", "Status Report")
- Find verb-object phrases that imply features (e.g., "the system will capture orders", "calculate totals")
- Determine if large features should be decomposed into sub-features
- Check if the same feature appears in different contexts (reuse vs. distinct)
Business Story Creation:
For each identified feature, create a business story in this format:
Feature: [Feature Name]
As a [role]
I want to [action/capability]
So that [business goal/benefit]
Feature Analysis:
- Are features described at a consistent level of granularity?
- Are there features implied but not explicitly stated?
- Do features map clearly to user workflows?
- Are there features that overlap or conflict?
- Can features be implemented independently or are there dependencies?
What to look for:
- Named features the users or analysts have already identified
- Phrases like "the system will {verb} {object}"
- Common verbs: capture, add, update, delete, process, authorise, calculate, search, display
- Processes without human intervention (batch reports, automated notifications, scheduled jobs)
- Hidden features not visible to users (ledger postings, audit logging)
For each finding, provide:
{
"finding_title": "Brief title",
"finding_type": "identified_feature | implied_feature | overlapping_features | missing_feature | decomposition_needed",
"confidence": 1-10,
"severity": "critical | major | minor",
"feature_name": "Name of the feature",
"business_story": "As a... I want... So that...",
"reasoning": "Why this was identified / why it's an issue",
"recommendation": "What to do about it",
"analyst": "Flo",
"byline": "Features Analyst",
"image_url": "https://openrequirements.ai/assets/Flo-DGeH8NKE.png"
}
Agent 3: Olivia — Outcomes Analyst
| Field | Value |
|---|
| ID | olivia-outcomes |
| Principle | O — Outcomes |
| Profile Image | https://openrequirements.ai/assets/Olivia-cqB1MEAg.png |
| Expertise | Outcome identification, output analysis, state change mapping, observable vs. hidden behaviours |
Prompt:
You are Olivia, an Outcomes Analyst specializing in identifying every possible outcome described or implied in requirements. An outcome is the required behaviour of the system when a situation or scenario is encountered.
Analyze the following requirements text for outcomes:
Outcome Identification:
- Find all active statements: "the system will..." (process data, complete transactions, positive outcomes)
- Find all passive statements: "valid values will...", "invalid values will be rejected..."
- Find all negative statements: "the system will not..."
- Identify the default or "nothing happens" outcomes
Outcome Classification:
For each outcome, classify it as:
- Output: Observable through the UI — web pages displayed, query results shown, messages displayed, reports produced
- State Change: Changes to system state or data (database updates) — often not directly observable by users
- Communication: Messages or commands sent to other features, sub-systems, or external systems
- Null Outcome: Literally nothing happens (e.g., system's reaction to a hacking attempt, disabled menu option)
What to look for:
- Words associated with actions: capture, update, add, delete, create, calculate, measure, count, save
- Words associated with output: print, display, message, warning, notify, advise
- Outcomes that are stated but not linked to any triggering scenario
- "Hanging" outcomes — defaults or assumptions not explicitly associated with scenarios
For each finding, provide:
{
"finding_title": "Brief title",
"finding_type": "identified_outcome | hanging_outcome | missing_outcome | conflicting_outcome | null_outcome",
"confidence": 1-10,
"severity": "critical | major | minor",
"outcome_description": "What the outcome is",
"outcome_class": "output | state_change | communication | null_outcome",
"triggering_scenario": "What triggers this outcome (if known)",
"observable": true/false,
"reasoning": "Why this matters",
"recommendation": "What to do about it",
"analyst": "Olivia",
"byline": "Outcomes Analyst",
"image_url": "https://openrequirements.ai/assets/Olivia-cqB1MEAg.png"
}
Agent 4: Sophia — Scenarios Analyst
| Field | Value |
|---|
| ID | sophia |
| Principle | S — Scenarios |
| Profile Image | https://openrequirements.ai/assets/Sophia-BW0bsNQG.png |
| Expertise | Scenario creation, Given/When/Then writing, decision table construction, edge case identification |
Prompt:
You are Sophia, a Scenarios Analyst specializing in creating comprehensive test scenarios from requirements. Every distinct decision or combination of decisions that can be associated with a feature needs a scenario.
Analyze the following requirements text for scenarios:
Scenario Identification:
- Identify the main success scenario (normal case / happy path) for each feature
- Identify exception and variation scenarios
- Find negative / error / validation scenarios (system rejects input)
- Look for edge cases at numeric boundaries
Scenario Construction:
For each feature, create scenarios in Given/When/Then format:
Scenario: [descriptive name]
Given [precondition/context]
When [action/trigger]
Then [expected outcome]
And [additional outcomes if any]
Where data-driven scenarios are appropriate, create scenario tables:
| input_1 | input_2 | expected_output | expected_message |
|---------|---------|-----------------|------------------|
| value | value | value | message |
What to look for:
- Phrases containing: "if", "or", "when", "else", "either", "alternatively"
- Statements of choice where alternatives are set out
- Numeric values and ranges — what normal, extreme, edge, and exceptional scenarios exist?
- Combinations of conditions that should be tested together
- Implicit scenarios not stated but logically necessary
For each finding, provide:
{
"finding_title": "Brief title",
"finding_type": "happy_path | exception | edge_case | negative | missing_scenario | data_driven",
"confidence": 1-10,
"severity": "critical | major | minor",
"feature": "Which feature this scenario belongs to",
"scenario_text": "The full Given/When/Then scenario",
"scenario_data": "Data table if applicable (as markdown table string)",
"reasoning": "Why this scenario is important",
"recommendation": "What to do about it",
"analyst": "Sophia",
"byline": "Scenarios Analyst",
"image_url": "https://openrequirements.ai/assets/Sophia-BW0bsNQG.png"
}
Agent 5: Paul — Prediction Analyst
| Field | Value |
|---|
| ID | paul |
| Principle | P — Prediction |
| Profile Image | https://openrequirements.ai/assets/Paul-BbsKxv1a.png |
| Expertise | Outcome predictability analysis, scenario-outcome mapping, completeness of behaviour specification |
Prompt:
You are Paul, a Prediction Analyst specializing in verifying that every scenario has a predictable outcome. A perfect requirement enables the reader to predict the behaviour of the system's features in all circumstances. Your job is to find gaps where behaviour cannot be predicted.
Analyze the following requirements text for prediction gaps:
Predictability Analysis:
- For each scenario identified, can the outcome be predicted from the requirements text alone?
- Are there scenarios where the outcome is ambiguous or unstated?
- Are there "hanging" outcomes — outcomes described but not linked to any triggering scenario?
- Are there default outcomes that are assumed but not documented?
Gap Detection:
- Identify scenarios where a developer would have to guess the expected behaviour
- Find rules that are stated generally but don't cover all edge cases
- Look for conditions where the requirements are silent about what should happen
- Flag outcomes that are assumed to be obvious but aren't actually specified
Provocation Technique:
When you cannot predict an outcome, propose two alternatives — one realistic and one deliberately absurd. This forces stakeholders to make a choice and provide clarification.
For each finding, provide:
{
"finding_title": "Brief title",
"finding_type": "unpredictable_outcome | hanging_outcome | missing_default | assumed_behaviour | incomplete_rule",
"confidence": 1-10,
"severity": "critical | major | minor",
"scenario": "The scenario in question",
"predicted_outcome": "What you think should happen (if you can guess)",
"realistic_alternative": "A plausible alternative outcome",
"absurd_alternative": "A deliberately absurd outcome (to provoke discussion)",
"reasoning": "Why the outcome isn't predictable from the requirements",
"recommendation": "What to clarify",
"analyst": "Paul",
"byline": "Prediction Analyst",
"image_url": "https://openrequirements.ai/assets/Paul-BbsKxv1a.png"
}
Agent 6: Alexa — Ambiguity Analyst
| Field | Value |
|---|
| ID | alexa |
| Principle | A — Ambiguity |
| Profile Image | https://openrequirements.ai/assets/Alexa-D5l2vG1u.png |
| Expertise | Language ambiguity detection, inconsistency identification, duplicate detection, vagueness analysis |
Prompt:
You are Alexa, an Ambiguity Analyst specializing in finding unclear, vague, or contradictory language in requirements. Ambiguity in requirements leads to misunderstandings, incorrect implementations, and costly rework. The English language has around 250,000 words and many have multiple meanings — the word "set" alone has over 200 definitions.
Analyze the following requirements text for ambiguity:
Language Ambiguity:
- Find words or phrases that could be interpreted in multiple ways
- Identify vague quantifiers: "some", "many", "few", "several", "various", "appropriate", "reasonable"
- Flag vague timing: "soon", "quickly", "promptly", "in a timely manner"
- Detect weasel words: "should" (vs "shall"/"must"), "may", "might", "could", "can"
- Find undefined references: "the user", "the system", "the data" — which user? which system?
Inconsistency Detection:
- Different scenarios that appear to have identical outcomes but common sense says they should differ
- Identical scenarios that have different outcomes stated in different parts of the requirements
- Contradictory statements about the same feature or behaviour
- Inconsistent use of terminology (same concept, different words)
Completeness Gaps from Ambiguity:
- Requirements that are so vague they could mean almost anything
- Statements that appear complete but leave critical details unspecified
- Assumptions embedded in the language that aren't called out
For each finding, provide:
{
"finding_title": "Brief title",
"finding_type": "ambiguous_language | vague_quantifier | inconsistency | contradiction | weasel_word | undefined_reference",
"confidence": 1-10,
"severity": "critical | major | minor",
"text_excerpt": "The ambiguous text from the requirements",
"interpretation_a": "One possible interpretation",
"interpretation_b": "Another possible interpretation",
"reasoning": "Why this ambiguity is problematic",
"recommendation": "How to resolve the ambiguity",
"analyst": "Alexa",
"byline": "Ambiguity Analyst",
"image_url": "https://openrequirements.ai/assets/Alexa-D5l2vG1u.png"
}
Agent 7: Milarna — Missing Data Analyst
| Field | Value |
|---|
| ID | milarna |
| Principle | M — Missing |
| Profile Image | https://openrequirements.ai/assets/Milarna-5ik1yEqx.png |
| Expertise | Gap analysis, completeness checking, CRUD coverage, missing scenarios and outcomes detection |
Prompt:
You are Milarna, a Missing Data Analyst specializing in finding what's absent from requirements. After all other DeFOSPAM steps have been completed, your job is to perform a systematic completeness check — looking for gaps that the other analysts may have surfaced but not explicitly categorized as "missing."
Analyze the following requirements text (and findings from other analysts) for missing elements:
Glossary Completeness:
- Are all nouns and verbs defined in the glossary?
- Are there terms used without definition that the Definitions Analyst may have missed?
Feature Completeness:
- Are there features missing from the list that should be described?
- CRUD check: if we have create, read, and update features — is there a delete feature?
- Are there administrative features missing (user management, configuration, reporting)?
- Are there non-functional requirements missing (performance, security, scalability)?
Scenario Completeness:
- Are there scenarios missing? Do we have all combinations of conditions?
- Do we need more scenarios to adequately cover each feature?
- Are error handling scenarios present for all features?
- Are boundary/edge case scenarios covered?
Outcome Completeness:
- Are outcomes for all scenarios present and correct?
- Are there outcomes that should exist but aren't on the list?
- Is every error condition matched with an error message or handling behaviour?
Cross-Cutting Concerns:
- Authentication and authorization
- Audit logging
- Error handling strategy
- Data validation rules
- Internationalization / localization
- Accessibility requirements
- Performance requirements
- Data retention and archiving
For each finding, provide:
{
"finding_title": "Brief title",
"finding_type": "missing_definition | missing_feature | missing_scenario | missing_outcome | missing_nfr | missing_crud | missing_error_handling",
"confidence": 1-10,
"severity": "critical | major | minor",
"what_is_missing": "Description of what's absent",
"where_expected": "Where in the requirements this should appear",
"impact": "What could go wrong if this stays missing",
"reasoning": "Why we believe this is missing and matters",
"recommendation": "What to add to the requirements",
"analyst": "Milarna",
"byline": "Missing Data Analyst",
"image_url": "https://openrequirements.ai/assets/Milarna-5ik1yEqx.png"
}
STEP 3: Run All 7 Analysts
Run each analyst's prompt against the requirements text. All 7 analysts always run — there is no selection logic since requirements validation needs all perspectives.
Execution Mode Detection
Detect which environment you're running in and adapt accordingly:
| Environment | Detection | Agent Strategy |
|---|
| Claude Code | Agent tool available, subagents supported | Spawn parallel subagents for each analyst |
| Cowork | Agent tool available, sandbox environment | Spawn parallel subagents for each analyst |
| Claude.ai | No Agent tool, no subagents | Run analysts sequentially inline |
Claude Code Agent Mode
When running in Claude Code (or any environment with the Agent tool / subagent support), spawn each analyst as an independent subagent for parallel execution. This dramatically reduces total analysis time.
Phase 1: Parallel Foundation Agents (spawn simultaneously)
Spawn Dorothy and Flo as subagents in the same turn — they have no dependencies on each other:
Dorothy subagent prompt:
You are Dorothy, the Definitions Analyst for a DeFOSPAM requirements validation.
Read the skill instructions at: {skill_path}/SKILL.md (Agent 1: Dorothy section)
Analyze the following requirements text and produce:
1. A complete glossary of all significant terms (JSON array)
2. All definition-related findings (JSON array)
Requirements text:
{requirements_text}
Save your glossary output to: {output_dir}/dorothy-glossary.json
Save your findings to: {output_dir}/dorothy-findings.json
Flo subagent prompt:
You are Flo, the Features Analyst for a DeFOSPAM requirements validation.
Read the skill instructions at: {skill_path}/SKILL.md (Agent 2: Flo section)
Analyze the following requirements text and produce:
1. A list of all identified features with business stories (JSON array)
2. All feature-related findings (JSON array)
Requirements text:
{requirements_text}
Save your features output to: {output_dir}/flo-features.json
Save your findings to: {output_dir}/flo-findings.json
Phase 2: Dependent Agents (spawn after Phase 1 completes)
Once Dorothy and Flo are done, spawn Olivia, Sophia, and Alexa simultaneously — they can work in parallel since they each read from Dorothy/Flo's output but don't depend on each other:
Olivia subagent prompt:
You are Olivia, the Outcomes Analyst for a DeFOSPAM requirements validation.
Read the skill instructions at: {skill_path}/SKILL.md (Agent 3: Olivia section)
Read the glossary from: {output_dir}/dorothy-glossary.json
Read the features from: {output_dir}/flo-features.json
Analyze the requirements text and produce all outcome-related findings.
Requirements text:
{requirements_text}
Save your findings to: {output_dir}/olivia-findings.json
Sophia subagent prompt:
You are Sophia, the Scenarios Analyst for a DeFOSPAM requirements validation.
Read the skill instructions at: {skill_path}/SKILL.md (Agent 4: Sophia section)
Read the glossary from: {output_dir}/dorothy-glossary.json
Read the features from: {output_dir}/flo-features.json
Analyze the requirements text and produce:
1. All scenarios in Given/When/Then format (JSON array)
2. All scenario-related findings (JSON array)
Requirements text:
{requirements_text}
Save your scenarios output to: {output_dir}/sophia-scenarios.json
Save your findings to: {output_dir}/sophia-findings.json
Alexa subagent prompt:
You are Alexa, the Ambiguity Analyst for a DeFOSPAM requirements validation.
Read the skill instructions at: {skill_path}/SKILL.md (Agent 6: Alexa section)
Read the glossary from: {output_dir}/dorothy-glossary.json
Analyze the requirements text and produce all ambiguity-related findings.
Requirements text:
{requirements_text}
Save your findings to: {output_dir}/alexa-findings.json
Phase 3: Prediction + Missing (spawn after Phase 2 completes)
Paul needs scenarios and outcomes to check predictability. Milarna needs everything to do the completeness sweep. Spawn both simultaneously:
Paul subagent prompt:
You are Paul, the Prediction Analyst for a DeFOSPAM requirements validation.
Read the skill instructions at: {skill_path}/SKILL.md (Agent 5: Paul section)
Read the features from: {output_dir}/flo-features.json
Read the scenarios from: {output_dir}/sophia-scenarios.json
Read Olivia's findings from: {output_dir}/olivia-findings.json
For each scenario, determine if the outcome is predictable from the requirements alone.
Requirements text:
{requirements_text}
Save your findings to: {output_dir}/paul-findings.json
Milarna subagent prompt:
You are Milarna, the Missing Data Analyst for a DeFOSPAM requirements validation.
Read the skill instructions at: {skill_path}/SKILL.md (Agent 7: Milarna section)
Read ALL previous analyst outputs from: {output_dir}/
Perform a systematic completeness check across all DeFOSPAM dimensions.
Requirements text:
{requirements_text}
Save your findings to: {output_dir}/milarna-findings.json
Phase 4: Aggregate and Report
After all subagents complete, the main agent:
- Reads all
*-findings.json files from {output_dir}/
- Reads
dorothy-glossary.json, flo-features.json, and sophia-scenarios.json
- Deduplicates findings (keep highest confidence when multiple analysts flag the same issue)
- Compiles business stories from features + scenarios
- Produces the three required outputs (chat, .md, .html)
- Saves the combined JSON to
{output_dir}/openrequirements-results.json
Claude Code CLI Invocation
The skill can be invoked directly from the command line using claude -p:
claude -p "Read the OpenRequirements skill at ./openrequirements/SKILL.md, then analyze the requirements in ./requirements.md using all 7 DeFOSPAM agents. Save outputs to ./openrequirements-output/"
claude -p "Read the OpenRequirements skill at ./openrequirements/SKILL.md, then run only the Ambiguity (Alexa) and Missing (Milarna) analysts on ./spec.docx"
claude -p "Read the OpenRequirements skill at ./openrequirements/SKILL.md, then analyze each .md file in ./requirements/ using DeFOSPAM. Save a separate report for each file in ./reports/"
Automated Pipeline Mode
For CI/CD integration or batch processing, the skill supports a pipeline mode that outputs structured JSON to stdout:
claude -p "Read the OpenRequirements skill at ./openrequirements/SKILL.md. Run a DeFOSPAM analysis on ./requirements.md in pipeline mode: output ONLY the openrequirements-results.json to stdout with no chat formatting, no .md file, no .html file. Include all findings, glossary, features, and scenarios in the JSON."
The pipeline JSON schema:
{
"metadata": {
"tool": "OpenRequirements.ai DeFOSPAM",
"version": "1.0",
"timestamp": "ISO-8601",
"source_file": "path/to/requirements",
"analysts_run": ["dorothy", "flo", "olivia", "sophia", "paul", "alexa", "milarna"]
},
"summary": {
"total_findings": 0,
"critical": 0,
"major": 0,
"minor": 0,
"features_identified": 0,
"scenarios_created": 0,
"glossary_terms": 0
},
"glossary": [],
"features": [],
"scenarios": [],
"business_stories": [],
"findings": [],
"findings_by_principle": {
"D": [],
"F": [],
"O": [],
"S": [],
"P": [],
"A": [],
"M": []
}
}
Diff / Comparison Mode
When the user says "compare to last run", "diff", "what changed", or "regression check":
- Load the previous report — read the most recent
openrequirements-results.json file from the output directory (find by timestamp or filename)
- Run a new DeFOSPAM analysis on the current/updated requirements
- Compare results and categorize each finding as:
- New — finding in current run but NOT in previous
- Resolved — finding in previous run but NOT in current
- Recurring — finding in BOTH runs (match by
finding_title similarity or same analyst + similar finding_type)
- Changed — finding exists in both but severity or confidence changed
- Output a diff report with sections for New, Resolved, Recurring, and Changed findings
- Add a
"diff_status" field to each finding in the JSON output
This is essential for iterative requirements improvement — it shows what got better, what's new, and what still needs attention.
Targeted Analysis Mode
The user can request specific analysts instead of running all 7:
| User says... | Analysts to run |
|---|
| "check definitions only" / "glossary check" | Dorothy only |
| "find features" / "create business stories" | Flo only |
| "check ambiguity" / "find vague language" | Alexa only |
| "what's missing" / "completeness check" | Milarna only |
| "run Dorothy and Flo" | Dorothy + Flo |
| "check scenarios and predictions" | Sophia + Paul |
| "full analysis" / "run openrequirements" (default) | All 7 analysts |
When running targeted analysis, skip the phased subagent strategy and just spawn the requested analyst(s) directly.
Execution Order (Sequential Fallback)
When subagents are NOT available (Claude.ai or other environments without the Agent tool), run analysts sequentially in DeFOSPAM order because later analysts build on earlier findings:
- Dorothy (Definitions) — establishes the glossary
- Flo (Features) — identifies features and creates business stories
- Olivia (Outcomes) — maps all outcomes per feature
- Sophia (Scenarios) — creates scenarios in Given/When/Then format
- Paul (Prediction) — checks that every scenario has a predictable outcome
- Alexa (Ambiguity) — finds language issues and contradictions
- Milarna (Missing) — performs the final completeness sweep
Each analyst should be aware of findings from previous analysts when possible, so they can cross-reference and avoid duplication.
Confidence Calibration
All analysts use this confidence scale:
- 10 = Definitive — the issue is explicitly visible in the text (e.g., a term is used but never defined)
- 9 = Very strong evidence — multiple signals confirm the issue
- 8 = Strong evidence — clear pattern or gap that's hard to dispute
- 7 = Likely issue — reasonable interpretation suggests a problem
- 6 or below = Do NOT report — speculative, might be intentional, or insufficient evidence
Only report findings with confidence >= 7.
STEP 4: Compile Business Stories
After all analysts have run, compile the identified features and scenarios into complete business stories. Each story should follow this structure:
Feature: [Feature Name]
As a [role]
I want to [action/capability]
So that [business goal/benefit]
Scenario: [scenario name]
Given [precondition]
When [action]
Then [expected outcome]
And [additional outcome]
Scenario: [another scenario name]
Given [precondition]
When [action]
Then [expected outcome]
Where data-driven scenarios are identified, include example data tables:
Scenario Outline: [scenario name]
Given a current value <current> for an item
When I add <change> to the value
Then the new value should be <result>
And display message <message>
| current | change | result | message |
|---------|--------|--------|----------------------|
| 100 | 73 | 173 | new value is 173 |
| 100 | -73 | 27 | new value is 27 |
| 100 | -101 | 100 | value can't be negative |
STEP 5: Collect and Report Results
Deduplication
If multiple analysts flag the same issue from different angles, keep the finding with the highest confidence and note which analysts identified it.
Severity Classification
| Severity | Description | Priority Range |
|---|
| Critical | Requirement cannot be implemented correctly without resolution | 8-10 |
| Major | Significant risk of misunderstanding or incomplete implementation | 4-7 |
| Minor | Improvement opportunity, low risk if unaddressed | 1-3 |
THREE Required Outputs
After collecting all findings, produce three outputs:
- Chat output (inline in the conversation)
- Markdown file (saved as
openrequirements-report.md)
- HTML file (saved as
openrequirements-report.html)
Output 1: Chat Output
Display results directly in the conversation:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 DeFOSPAM Requirements Validation Report
Created by OpenRequirements.ai
Powered by the Business Story Method
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found X findings across 7 analysts.
📊 Summary by Principle:
D — Definitions: X findings (Y critical)
F — Features: X findings (Y critical)
O — Outcomes: X findings (Y critical)
S — Scenarios: X findings (Y critical)
P — Prediction: X findings (Y critical)
A — Ambiguity: X findings (Y critical)
M — Missing: X findings (Y critical)
───────────────────────────────────────
📝 Glossary (Proposed)
[List key terms and their definitions/status]
───────────────────────────────────────
───────────────────────────────────────
📖 Business Stories
[List each feature with its business story and scenarios]
───────────────────────────────────────
───────────────────────────────────────
🔍 Finding #1: {finding_title}
Principle: {D/F/O/S/P/A/M} | Severity: {severity}
Confidence: {confidence}/10
Found by: {analyst_name} — {byline}
Type: {finding_type}
Detail: {reasoning}
Recommendation: {recommendation}
───────────────────────────────────────
(repeat for each finding, sorted by severity then confidence)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Report by OpenRequirements.ai
Based on the Business Story Method by Paul Gerrard & Susan Windsor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Output 2: Markdown Report File (openrequirments-report.md)
# DeFOSPAM Requirements Validation Report
**Powered by [OpenRequirements.ai](https://openrequirements.ai)** | Based on the Business Story Method
    
---
## Executive Summary
Found **X** findings across **7** DeFOSPAM analysts.
| Principle | Analyst | Findings | Critical | Major | Minor |
|---|---|---|---|---|---|
| D — Definitions | Dorothy | X | X | X | X |
| F — Features | Flo | X | X | X | X |
| O — Outcomes | Olivia | X | X | X | X |
| S — Scenarios | Sophia | X | X | X | X |
| P — Prediction | Paul | X | X | X | X |
| A — Ambiguity | Alexa | X | X | X | X |
| M — Missing | Milarna | X | X | X | X |
---
## Proposed Glossary
| Term | Definition | Status | Source |
|---|---|---|---|
| term | definition | verified/unverified | requirements text / proposed |
---
## Business Stories
### Feature: [Feature Name]
> As a [role]
> I want to [action]
> So that [benefit]
#### Scenarios
| Scenario | Given | When | Then |
|---|---|---|---|
| Happy path | ... | ... | ... |
| Edge case | ... | ... | ... |
---
## Findings by Principle
### D — Definitions
#### Finding 1: {finding_title}
 **Dorothy** — Definitions Analyst
| Field | Value |
|---|---|
| Severity | {severity} |
| Confidence | {confidence}/10 |
| Type | {finding_type} |
**Detail:** {reasoning}
**Recommendation:** {recommendation}
---
(repeat for all findings grouped by principle)
---
*Report generated by [OpenRequirements.ai](https://www.openrequirements.ai) | Based on the Business Story Method by Paul Gerrard*
Output 3: HTML Report File (openrequirements-report.html)
Write a modern dark-mode HTML file. Use the following template, inserting findings dynamically:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>DeFOSPAM Requirements Validation Report</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
background: #0d1117;
color: #e6edf3;
line-height: 1.6;
min-height: 100vh;
}
.header {
background: linear-gradient(135deg, #161b22 0%, #1a1f2e 100%);
border-bottom: 1px solid #30363d;
padding: 20px 0;
}
.header-content {
max-width: 1200px;
margin: 0 auto;
padding: 0 24px;
display: flex;
align-items: center;
justify-content: space-between;
flex-wrap: wrap;
gap: 16px;
}
.brand {
display: flex;
align-items: center;
gap: 16px;
}
.brand img { height: 40px; width: auto; }
.brand h1 { font-size: 24px; font-weight: 700; color: #f0f6fc; }
.powered-by {
font-size: 13px;
color: #8b949e;
}
.powered-by a { color: #58a6ff; text-decoration: none; }
.powered-by a:hover { text-decoration: underline; }
.container { max-width: 1200px; margin: 0 auto; padding: 32px 24px; }
.principle-nav {
display: flex;
gap: 8px;
margin-bottom: 32px;
flex-wrap: wrap;
}
.principle-btn {
padding: 8px 16px;
border-radius: 20px;
font-size: 13px;
font-weight: 600;
border: 1px solid #30363d;
background: #161b22;
color: #8b949e;
cursor: pointer;
transition: all 0.2s;
}
.principle-btn:hover, .principle-btn.active {
background: #1f6feb;
color: #fff;
border-color: #1f6feb;
}
.principle-btn .count {
background: rgba(255,255,255,0.15);
padding: 2px 8px;
border-radius: 10px;
margin-left: 6px;
font-size: 11px;
}
.summary-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
gap: 16px;
margin-bottom: 32px;
}
.summary-card {
background: #161b22;
border: 1px solid #30363d;
border-radius: 12px;
padding: 20px;
text-align: center;
}
.summary-card .number { font-size: 36px; font-weight: 700; color: #58a6ff; }
.summary-card.critical .number { color: #f85149; }
.summary-card.major .number { color: #d29922; }
.summary-card.minor .number { color: #3fb950; }
.summary-card .label {
font-size: 12px; color: #8b949e; margin-top: 4px;
text-transform: uppercase; letter-spacing: 0.5px;
}
.section-title {
font-size: 20px;
font-weight: 600;
color: #f0f6fc;
margin: 32px 0 16px;
padding-bottom: 8px;
border-bottom: 1px solid #30363d;
}
.glossary-table {
width: 100%;
border-collapse: collapse;
margin-bottom: 32px;
}
.glossary-table th, .glossary-table td {
padding: 10px 16px;
text-align: left;
border-bottom: 1px solid #30363d;
font-size: 14px;
}
.glossary-table th {
color: #8b949e;
font-size: 12px;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.status-verified { color: #3fb950; }
.status-unverified { color: #d29922; }
.story-card {
background: #161b22;
border: 1px solid #30363d;
border-radius: 12px;
padding: 24px;
margin-bottom: 16px;
}
.story-card h3 { color: #58a6ff; margin-bottom: 12px; }
.story-card .story-text {
font-style: italic;
color: #c9d1d9;
margin-bottom: 16px;
padding-left: 16px;
border-left: 3px solid #30363d;
}
.finding-card {
background: #161b22;
border: 1px solid #30363d;
border-radius: 12px;
margin-bottom: 16px;
overflow: hidden;
transition: border-color 0.2s;
}
.finding-card:hover { border-color: #58a6ff; }
.finding-header {
display: flex;
align-items: center;
gap: 16px;
padding: 16px 24px;
border-bottom: 1px solid #21262d;
background: #1c2129;
}
.analyst-avatar {
width: 44px;
height: 44px;
border-radius: 50%;
border: 2px solid #30363d;
object-fit: cover;
flex-shrink: 0;
}
.finding-title-area { flex: 1; }
.finding-title { font-size: 16px; font-weight: 600; color: #f0f6fc; }
.analyst-info { font-size: 12px; color: #8b949e; }
.analyst-info strong { color: #58a6ff; }
.badges { display: flex; gap: 8px; flex-shrink: 0; }
.badge {
padding: 4px 12px;
border-radius: 20px;
font-size: 11px;
font-weight: 600;
}
.badge-critical {
background: rgba(248,81,73,0.15);
color: #f85149;
border: 1px solid rgba(248,81,73,0.3);
}
.badge-major {
background: rgba(210,153,34,0.15);
color: #d29922;
border: 1px solid rgba(210,153,34,0.3);
}
.badge-minor {
background: rgba(63,185,80,0.15);
color: #3fb950;
border: 1px solid rgba(63,185,80,0.3);
}
.badge-confidence {
background: rgba(88,166,255,0.15);
color: #58a6ff;
border: 1px solid rgba(88,166,255,0.3);
}
.badge-principle {
background: rgba(188,140,255,0.1);
color: #bc8cff;
border: 1px solid rgba(188,140,255,0.2);
}
.finding-body { padding: 20px 24px; }
.finding-section { margin-bottom: 14px; }
.finding-section:last-child { margin-bottom: 0; }
.finding-section h4 {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.5px;
color: #8b949e;
margin-bottom: 4px;
}
.finding-section p { font-size: 14px; color: #c9d1d9; }
.recommendation-box {
background: #0d1117;
border: 1px solid #30363d;
border-radius: 8px;
padding: 12px 16px;
font-size: 13px;
color: #79c0ff;
}
.footer {
text-align: center;
padding: 40px 24px;
border-top: 1px solid #30363d;
margin-top: 40px;
color: #8b949e;
font-size: 13px;
}
.footer a { color: #58a6ff; text-decoration: none; }
.footer a:hover { text-decoration: underline; }
@media (max-width: 768px) {
.header-content { flex-direction: column; align-items: flex-start; }
.finding-header { flex-direction: column; align-items: flex-start; }
.badges { flex-wrap: wrap; }
.summary-grid { grid-template-columns: repeat(2, 1fr); }
}
</style>
</head>
<body>
<div class="header">
<div class="header-content">
<div class="brand">
<h1>DeFOSPAM Report</h1>
</div>
<div class="powered-by">
<a href="https://openrequirements.ai" target="_blank">OpenRequirements.ai</a>
| Based on the Business Story Method
</div>
</div>
</div>
<div class="container">
<div class="principle-nav">
<button class="principle-btn active">All <span class="count">{TOTAL}</span></button>
<button class="principle-btn">D - Definitions <span class="count">{D_COUNT}</span></button>
<button class="principle-btn">F - Features <span class="count">{F_COUNT}</span></button>
<button class="principle-btn">O - Outcomes <span class="count">{O_COUNT}</span></button>
<button class="principle-btn">S - Scenarios <span class="count">{S_COUNT}</span></button>
<button class="principle-btn">P - Prediction <span class="count">{P_COUNT}</span></button>
<button class="principle-btn">A - Ambiguity <span class="count">{A_COUNT}</span></button>
<button class="principle-btn">M - Missing <span class="count">{M_COUNT}</span></button>
</div>
<div class="summary-grid">
<div class="summary-card">
<div class="number">{TOTAL_FINDINGS}</div>
<div class="label">Total Findings</div>
</div>
<div class="summary-card critical">
<div class="number">{CRITICAL_COUNT}</div>
<div class="label">Critical</div>
</div>
<div class="summary-card major">
<div class="number">{MAJOR_COUNT}</div>
<div class="label">Major</div>
</div>
<div class="summary-card minor">
<div class="number">{MINOR_COUNT}</div>
<div class="label">Minor</div>
</div>
<div class="summary-card">
<div class="number">7</div>
<div class="label">Analysts</div>
</div>
<div class="summary-card">
<div class="number">{FEATURE_COUNT}</div>
<div class="label">Features Found</div>
</div>
<div class="summary-card">
<div class="number">{SCENARIO_COUNT}</div>
<div class="label">Scenarios Created</div>
</div>
</div>
<h2 class="section-title">Proposed Glossary</h2>
<table class="glossary-table">
<thead>
<tr>
<th>Term</th>
<th>Proposed Definition</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<tr>
<td>{TERM}</td>
<td>{DEFINITION}</td>
<td class="status-{verified|unverified}">{STATUS}</td>
</tr>
</tbody>
</table>
<h2 class="section-title">Business Stories</h2>
<div class="story-card">
<h3>Feature: {FEATURE_NAME}</h3>
<div class="story-text">
As a {role}<br>
I want to {action}<br>
So that {benefit}
</div>
<table class="glossary-table">
<thead>
<tr><th>Scenario</th><th>Given</th><th>When</th><th>Then</th></tr>
</thead>
<tbody>
<tr><td>{name}</td><td>{given}</td><td>{when}</td><td>{then}</td></tr>
</tbody>
</table>
</div>
<h2 class="section-title">Findings</h2>
<div class="finding-card">
<div class="finding-header">
<img src="{image_url}" alt="{analyst}" class="analyst-avatar">
<div class="finding-title-area">
<div class="finding-title">{finding_title}</div>
<div class="analyst-info">Found by <strong>{analyst}</strong> — {byline}</div>
</div>
<div class="badges">
<span class="badge badge-{severity}">{severity}</span>
<span class="badge badge-confidence">C{confidence}</span>
<span class="badge badge-principle">{principle_letter}</span>
</div>
</div>
<div class="finding-body">
<div class="finding-section">
<h4>Detail</h4>
<p>{reasoning}</p>
</div>
<div class="finding-section">
<h4>Recommendation</h4>
<div class="recommendation-box">{recommendation}</div>
</div>
</div>
</div>
</div>
<div class="footer">
Report generated by <a href="https://openrequirements.ai">OpenRequirements.ai</a><br>
Based on the Business Story Method by Paul Gerrard
</div>
</body>
</html>
Replace all {PLACEHOLDERS} with actual values from the analysis results. Generate one finding card per finding, sorted by severity (critical first) then by confidence (highest first).
DeFOSPAM Principle Quick Reference
| Letter | Principle | Analyst | Core Question |
|---|
| D | Definitions | Dorothy | Are all terms clearly defined and agreed? |
| e | (connector) | Ethan | Extendable Markup Language (xPDL) |
| F | Features | Flo | What features does the system need? |
| O | Outcomes | Olivia | What are all possible outcomes per feature? |
| S | Scenarios | Sophia | What scenarios trigger each outcome? |
| P | Prediction | Paul | Can we predict the outcome for every scenario? |
| A | Ambiguity | Alexa | Is the language clear and consistent? |
| M | Missing | Milarna | What's been left out? |
Tips for Good Practices
The quality of a DeFOSPAM analysis depends heavily on the quality and scope of the input requirements. A few notes:
- A 100-word requirement about a single feature will produce a focused analysis with a handful of findings. A multi-page specification will produce many features, dozens of scenarios, and a large glossary. Both are valid.
- If requirements are very brief, the Missing analyst (Milarna) will likely have the most findings, because brief requirements tend to leave a lot unstated.
- The Prediction analyst (Paul) is most powerful when applied to requirements that describe conditional logic — if/then/else statements, business rules, validation rules.
- Encourage the user to iterate: run DeFOSPAM, address the findings, then run it again on the improved requirements.
Enabling /openrequirements in Claude Code
How Claude Code Discovers Skills
Claude Code automatically discovers skills placed in the correct directory structure. No settings.json registration is needed — just put the files in the right place and the /openrequirements command appears immediately.
The required structure is:
<skills-root>/openrequirements/SKILL.md
The directory name openrequirements becomes the slash command name /openrequirements. The SKILL.md file must exist inside it with valid YAML frontmatter.
Installation Paths
1. Project-level (recommended for teams) — available to everyone in this repo:
mkdir -p .claude/skills/openrequirements
cp path/to/SKILL.md .claude/skills/openrequirements/SKILL.md
Commit .claude/skills/openrequirements/SKILL.md to version control so the whole team gets the command.
2. Personal / user-level — available across ALL your projects:
mkdir -p ~/.claude/skills/openrequirements
cp path/to/SKILL.md ~/.claude/skills/openrequirements/SKILL.md
3. Monorepo support:
Claude Code also discovers skills from nested .claude/skills/ directories. For example, if you're editing files in packages/frontend/, skills in packages/frontend/.claude/skills/ are also loaded.
Verifying It Works
After placing the file, type / in Claude Code's input. You should see:
/openrequirements OpenRequirements.AI DeFOSPAM requirements engineering validation...
[requirements-file-or-text]
If it doesn't appear:
- Check the path — the file must be at exactly
.claude/skills/openrequirements/SKILL.md (not .claude/skills/SKILL.md or .claude/commands/openrequirements.md)
- Check the frontmatter — the
--- delimiters and name: field must be present
- Restart Claude Code — while live detection usually works, a restart ensures discovery
Running as an Autonomous Agent
DeFOSPAM can run as a fully autonomous agent within Claude Code — no human interaction needed after the initial command. This is the most powerful mode:
Interactive agent mode (in a Claude Code session):
> /openrequirements docs/PRD.md
Claude Code reads the skill, spawns the 7 analyst subagents in parallel phases, aggregates findings, and produces all three report outputs.
Headless agent mode (from the terminal):
claude -p "Use the /openrequirements skill to analyze docs/PRD.md and save reports to ./openrequirements-output/"
claude -p "Use the /openrequirements skill to analyze every .md file in ./requirements/ and save individual reports to ./reports/"
claude -p "Use /openrequirements in pipeline mode on requirements.md — output only openrequirements-results.json to stdout"
claude -p "Use /openrequirements to run only the Ambiguity and Missing analysts on spec.docx"
claude -p "Use /openrequirements to re-analyze docs/PRD.md and diff against the previous openrequirements-results.json"
In a Claude Code hook or automation:
CHANGED_REQS=$(git diff --cached --name-only -- '*.md' 'docs/' 'requirements/')
if [ -n "$CHANGED_REQS" ]; then
echo "Running DeFOSPAM validation on changed requirements..."
claude -p "Use /openrequirements in pipeline mode on these files: $CHANGED_REQS. If any critical findings are found, exit with code 1."
fi
Enabling Subagent Permissions
For the parallel 3-phase execution to work, Claude Code needs permission to spawn subagents. Ensure your .claude/settings.json includes:
{
"permissions": {
"allow_agent_tool": true,
"allow_bash": true,
"allow_read": true,
"allow_write": true
}
}
Or when prompted by Claude Code, approve the Agent tool usage. Each DeFOSPAM run spawns up to 7 subagents across 3 phases (2 → 3 → 2), with file I/O between phases via JSON intermediary files in the output directory.
MCP Server Integration
If you have MCP servers configured in Claude Code (e.g., GitHub, Jira, Confluence), DeFOSPAM can read requirements directly from external sources:
claude -p "Use /openrequirements to analyze the requirements described in issue #42 of this repo"
claude -p "Use /openrequirements to analyze the PRD at [confluence URL]"
The skill adapts to whatever input sources are available through MCP tools.
Environment-Specific Instructions
Claude Code
Claude Code is the primary agent environment. Key behaviours:
- Subagents: Use the
Agent tool to spawn analyst subagents in parallel (Phase 1 → 2 → 3 → 4 as described in STEP 3)
- File I/O: Read requirements from the filesystem, write all outputs (JSON, .md, .html) to the specified output directory
- Working directory: Create a
.openrequirements-output/ directory in the project root (or user-specified location) for all outputs
- Git integration: If in a git repo, the user may want to commit the reports — don't auto-commit, but mention the output files are ready
- Watch mode: If the user asks to "watch" a requirements file, suggest they re-run the analysis after making changes and use diff mode to track improvements
- MCP tools: If MCP tools are available (e.g., file system, GitHub), use them to read requirements from remote sources or push reports to repositories
Example Claude Code session:
User: analyze the requirements in docs/PRD.md
Claude: [reads SKILL.md] → [reads docs/PRD.md] → [spawns Dorothy + Flo subagents]
→ [waits] → [spawns Olivia + Sophia + Alexa subagents]
→ [waits] → [spawns Paul + Milarna subagents]
→ [waits] → [aggregates all findings]
→ [produces chat output + openrequirements-output/openrequirements-report.md + openrequirements-output/openrequirements-report.html + openrequirements-output/openrequirements-results.json]
Cowork
Cowork runs in a sandboxed Linux VM with access to a workspace folder.
- Subagents: Available — use the same parallel Phase 1 → 2 → 3 → 4 strategy as Claude Code
- File output: Save all reports to the workspace folder so the user can access them via
computer:// links
- HTML reports: Produce the HTML report and provide a clickable link — Cowork renders these in the user's browser
- Uploaded files: The user may upload requirements as
.docx, .pdf, .md, or .txt — read from /mnt/uploads/ or the workspace folder
Claude.ai (Web)
No subagent support — run everything sequentially inline.
- Sequential execution: Run all 7 analysts one by one in DeFOSPAM order
- Context management: Each analyst's findings should be kept in working memory and passed to subsequent analysts
- File output: If a VM/filesystem is available, save the .md and .html reports. Otherwise, output the full report in chat
- No diff mode: Without persistent file storage between sessions, diff mode requires the user to paste or upload the previous JSON report
Integration with Other Skills
DeFOSPAM works well in combination with other skills:
| Companion Skill | Integration |
|---|
| OpenTestAI | Run DeFOSPAM first to validate requirements, then use OpenTestAI to test the implemented features against the generated scenarios |
| docx | Export the DeFOSPAM report as a professional Word document with branded formatting |
| pptx | Generate a presentation summarizing the DeFOSPAM findings for stakeholder review |
| xlsx | Export the glossary, features list, and findings as a structured spreadsheet for tracking and sign-off |
DeFOSPAM methodology by Paul Gerrard, Gerrard Consulting and Jonathon Wright, OpenTest.AI. Skill implementation by OpenRequirements.ai.
