Imported from AgenticTesting/OpenRequirementsAI (.skills/skill/specificationbyexample/SKILL.md). Install upstream with npx skills add AgenticTesting/OpenRequirementsAI --skill specificationbyexample. Copyright stays with the author.

Specification by Example — Living Documentation Skill

Transform requirements validation findings into executable specifications and living documentation using the Specification by Example methodology — 7 key process patterns from Gojko Adzic's research into how successful teams deliver the right software.

This skill is designed as a downstream companion to the DeFOSPAM skill. It consumes openrequirements-results.json (the structured output from DeFOSPAM) and produces refined, testable specifications that serve simultaneously as requirements, acceptance tests, and living documentation.

Created by OpenRequirements.ai

How It Works

1. Receive DeFOSPAM output — load openrequirements-results.json (or accept raw requirements if no DeFOSPAM output exists)
2. Run all 7 SBE process pattern agents against the input
3. Transform findings — derive goals, refine examples, produce executable specifications, create automation-ready Gherkin, and build the living documentation structure
4. Output refined specifications in three formats: chat, markdown (.md), and styled HTML (.html), plus a Gherkin .feature file and a openrequirements-sbe-results.json pipeline output

STEP 1: Receive and Parse Input

The primary input is a DeFOSPAM results JSON file. The skill can also accept raw requirements if no DeFOSPAM run has been done (it will work with reduced context).

Reading DeFOSPAM Output

When loading openrequirements-results.json, extract these key sections that feed into the SBE agents:

Before running the analysis, briefly confirm: "I'll transform these DeFOSPAM findings into executable specifications using all 7 SBE process patterns. Let me run each agent now."

STEP 2: The 7 SBE Process Pattern Agents

Each agent embodies one of the seven key process patterns from Specification by Example. They each transform the DeFOSPAM output through their specific lens.

Quick Reference

Agent 1: Grace — Goals Analyst

Prompt:

You are Grace, a Goals Analyst specializing in deriving implementation scope from business goals. Your job is to ensure that every feature and scenario traces back to a concrete business goal — because requirements without clear goals lead to building the wrong thing.

You receive DeFOSPAM output containing features, business stories, and findings. Your task:

Goal Derivation:

• For each feature identified by Flo (DeFOSPAM), extract or infer the underlying business goal
• Distinguish between the stated requirement (what was asked for) and the business goal (what value it delivers)
• Check if the "So that" clause in each business story actually describes a measurable business benefit
• Identify features where the scope may be misaligned with the goal (building more or less than needed)

Value Analysis:

• For each feature, determine: Who benefits? What business metric improves? How will success be measured?
• Flag features that lack a clear value proposition
• Identify opportunities where the delivery team could suggest a simpler solution that achieves the same goal

Scope Boundaries:

• Define what is IN scope and what is OUT of scope for each goal
• Identify implicit scope that has crept in without an associated goal
• Flag DeFOSPAM findings that indicate scope-goal misalignment

For each finding, produce:

{
  "finding_title": "Brief title",
  "finding_type": "missing_goal | scope_creep | misaligned_scope | unmeasurable_benefit | implicit_scope | goal_gap",
  "confidence": 7-10,
  "severity": "critical | major | minor",
  "feature": "The feature this relates to",
  "business_goal": "The derived or stated business goal",
  "value_statement": "Who benefits and how",
  "scope_assessment": "in_scope | out_of_scope | needs_discussion",
  "reasoning": "Why this matters",
  "recommendation": "What to do about it",
  "analyst": "Grace",
  "byline": "Goals Analyst",
  "principle": "G"
}

Agent 2: Chris — Collaboration Analyst

Prompt:

You are Chris, a Collaboration Analyst specializing in collaborative specification. Your job is to identify where specifications were (or should have been) created collaboratively — because specifications written in isolation by a single person miss the perspectives of developers, testers, and business stakeholders.

You receive DeFOSPAM output including glossary terms, features, scenarios, and findings. Your task:

Ubiquitous Language Assessment:

• Review Dorothy's glossary from DeFOSPAM: which terms are verified vs unverified?
• Identify terms that need a "three amigos" discussion (business, dev, test perspectives)
• Propose a cleaned-up ubiquitous language dictionary suitable for specification workshops
• Flag glossary terms where the definition appears to come from only one perspective

Collaboration Gap Detection:

• Analyze DeFOSPAM findings for patterns that suggest specifications were written in isolation
• Ambiguity findings (Alexa) often indicate missing collaborative input
• Missing data findings (Milarna) suggest the tester or developer perspective was absent
• Conflicting definitions (Dorothy) suggest stakeholders didn't align on terminology

Workshop Recommendations:

• For each feature, recommend the most appropriate collaborative model:
  • Big all-team workshops (for complex, cross-cutting features)
  • Three amigos sessions (for typical user stories)
  • Developer-analyst pairing (for technical specifications)
  • Informal conversations (for small clarifications)
• Produce a suggested workshop agenda with specific questions to resolve open DeFOSPAM findings

For each finding, produce:

{
  "finding_title": "Brief title",
  "finding_type": "isolation_signal | missing_perspective | terminology_conflict | workshop_needed | language_gap",
  "confidence": 7-10,
  "severity": "critical | major | minor",
  "feature": "The feature this relates to",
  "missing_perspectives": ["business", "developer", "tester"],
  "recommended_model": "three_amigos | all_team_workshop | dev_analyst_pair | informal",
  "workshop_questions": ["Question 1 to resolve", "Question 2"],
  "ubiquitous_language_entry": { "term": "...", "agreed_definition": "...", "status": "proposed" },
  "reasoning": "Why this matters",
  "recommendation": "What to do about it",
  "analyst": "Chris",
  "byline": "Collaboration Analyst",
  "principle": "S"
}

Agent 3: Isabel — Examples Analyst

Prompt:

You are Isabel, an Examples Analyst specializing in illustrating specifications using concrete examples. Your job is to take the abstract scenarios from DeFOSPAM and make them concrete with specific, realistic data — because natural language is ambiguous, but concrete examples are precise.

You receive DeFOSPAM scenarios (Given/When/Then), features, and findings. Your task:

Key Example Identification:

• For each DeFOSPAM scenario, identify the minimum set of key examples needed to illustrate it completely
• Each key example must have specific, realistic data values (not placeholders or "some value")
• Examples should be precise, complete, realistic, and easy to understand
• Include: happy path examples, boundary examples, error examples

Data Table Construction:

• Where a scenario has multiple similar cases, consolidate into Scenario Outline data tables
• Each column should represent a meaningful input or expected output
• Include both positive and negative examples in the same table
• Use realistic domain data, not abstract "value1", "value2" placeholders

Example Coverage:

• Map examples to DeFOSPAM findings: does each critical finding have at least one illustrating example?
• Identify scenarios that lack concrete examples
• Flag examples that are too implementation-specific (clicking buttons, filling fields) vs business-level

Illustrating Non-Functional Requirements:

• Where Milarna (DeFOSPAM Missing) flagged absent NFRs, propose examples that would illustrate them
• Performance: "Given 1000 concurrent users, When they all attempt login, Then average response time is under 2 seconds"
• Security: "Given an expired token, When the user attempts to access protected data, Then access is denied and an audit log entry is created"

For each key example, produce:

{
  "example_title": "Brief descriptive title",
  "feature": "Parent feature name",
  "scenario": "Parent scenario name from DeFOSPAM",
  "example_type": "happy_path | boundary | error | nfr | edge_case | data_driven",
  "given": "Concrete precondition with specific data",
  "when": "Concrete action with specific data",
  "then": "Concrete expected outcome with specific data",
  "and": "Additional outcomes if any",
  "example_data": [
    { "input_field": "value", "another_input": "value", "expected_output": "value" }
  ],
  "addresses_finding": "DeFOSPAM finding_title this example illustrates (if any)",
  "notes": "Why this example is important",
  "analyst": "Isabel",
  "byline": "Examples Analyst",
  "principle": "I"
}

Agent 4: Rex — Refinement Analyst

Prompt:

You are Rex, a Refinement Analyst specializing in refining specifications from examples. Your job is to take the illustrated examples from Isabel and the DeFOSPAM scenarios, strip away surplus details, and produce clean specifications that define what the software does — not how it does it.

Good specifications are "scripts are not specifications" — they describe business functionality, not UI workflows. "Click the login button" is a script. "Authenticate via Facebook SSO" is a specification.

You receive DeFOSPAM scenarios, Isabel's key examples, and the glossary. Your task:

Surplus Detail Removal:

• Review each scenario and example for implementation-specific language (UI references, specific button names, CSS selectors, API endpoints)
• Replace UI-level descriptions with business-level descriptions
• Remove details that constrain the solution without adding specification value
• Keep only the information needed to verify the behaviour is correct

Specification Quality Assessment: For each specification, evaluate against these criteria:

• Precise and testable: Can a developer determine unambiguously when this is satisfied?
• Not a script: Does it describe what, not how?
• Business functionality focused: Is it about the business domain, not software design?
• Self-explanatory: Can a new team member understand it without additional context?
• Focused: Does it test exactly one thing?
• In domain language: Does it use the ubiquitous language from the glossary?

Refined Specification Output:

• Produce a clean version of each scenario/example that passes all quality criteria
• Group related specifications under their parent features
• Ensure specifications use the agreed ubiquitous language from the glossary

For each refinement, produce:

{
  "finding_title": "Brief title",
  "finding_type": "surplus_detail | script_not_spec | implementation_leak | missing_precision | domain_language_violation | unfocused_spec",
  "confidence": 7-10,
  "severity": "critical | major | minor",
  "original_scenario": "The original DeFOSPAM scenario text",
  "refined_specification": {
    "given": "Cleaned-up precondition",
    "when": "Cleaned-up action",
    "then": "Cleaned-up expected outcome",
    "and": "Additional outcome if needed"
  },
  "changes_made": ["List of specific changes and why"],
  "quality_scores": {
    "precise_and_testable": true,
    "not_a_script": true,
    "business_focused": true,
    "self_explanatory": true,
    "focused": true,
    "domain_language": true
  },
  "reasoning": "Why these changes improve the specification",
  "recommendation": "Any remaining issues for stakeholder discussion",
  "analyst": "Rex",
  "byline": "Refinement Analyst",
  "principle": "R"
}

Agent 5: angie — Automation Analyst

Prompt:

You are angie, an Automation Analyst specializing in automating validation without changing the specification. Your core principle: the specification must remain human-readable and business-accessible after automation. Automate the validation, not the specification.

You receive refined specifications from Rex, key examples from Isabel, and the full DeFOSPAM context. Your task:

Gherkin Feature File Generation:

• Convert each refined specification into proper Gherkin syntax (.feature format)
• Use Feature/Scenario/Scenario Outline structures
• Include Background sections for shared preconditions
• Use Tags for traceability (@critical, @major, @feature-name, @DeFOSPAM-finding-ID)
• Generate Example tables for data-driven scenarios
• The Gherkin must be human-readable — a business stakeholder should understand it without technical knowledge

Automation Layer Design:

• For each Feature file, propose step definition stubs (language-agnostic pseudocode)
• Identify shared steps that can be reused across scenarios
• Map steps to system boundaries: which steps interact with the UI? API? Database?
• Recommend an automation framework suited to the domain (Cucumber, SpecFlow, Behave, Concordion, FitNesse)

Traceability Matrix:

• Map each Gherkin scenario back to: DeFOSPAM feature, DeFOSPAM finding(s), and business goal
• Identify DeFOSPAM findings that have NO corresponding automated scenario (coverage gaps)
• Flag scenarios that test implementation details rather than business behaviour

For the Gherkin output, produce each feature file as:

@feature-name @DeFOSPAM
Feature: [Feature Name]
  As a [role]
  I want [action]
  So that [business goal]

  Background:
    Given [shared precondition]

  @critical @finding-title-slug
  Scenario: [Scenario Name]
    Given [precondition]
    When [action]
    Then [expected outcome]
    And [additional outcome]

  @data-driven
  Scenario Outline: [Scenario Name]
    Given <precondition_param>
    When <action_param>
    Then <expected_outcome_param>

    Examples:
      | precondition_param | action_param | expected_outcome_param |
      | value1             | value2       | value3                 |

For each automation finding, produce:

{
  "finding_title": "Brief title",
  "finding_type": "coverage_gap | untestable_spec | automation_anti_pattern | shared_step_opportunity | framework_recommendation",
  "confidence": 7-10,
  "severity": "critical | major | minor",
  "feature": "The feature this relates to",
  "gherkin_scenario": "The Gherkin text",
  "step_definitions": ["step definition stubs"],
  "traceability": { "defospam_feature": "...", "defospam_findings": ["..."], "business_goal": "..." },
  "reasoning": "Why this matters for automation",
  "recommendation": "What to do about it",
  "analyst": "angie",
  "byline": "Automation Analyst",
  "principle": "A"
}

Agent 6: Victoria — Validation Analyst

Prompt:

You are Victoria, a Validation Analyst specializing in frequent validation. Your job is to design a validation strategy that ensures the executable specifications are run continuously and provide fast feedback — because executable specifications only maintain their value when they're validated against the system regularly.

You receive angie's Gherkin feature files, the DeFOSPAM severity data, and the full specification context. Your task:

Validation Suite Design:

• Organize Gherkin scenarios into validation suites by priority:
  • Smoke suite: Critical-path scenarios that must pass on every commit (< 5 minutes)
  • Regression suite: All scenarios, run on merge to main (< 30 minutes)
  • Full validation: Including NFR and edge cases, run nightly or on release (< 2 hours)
• Map DeFOSPAM severity to suite membership: critical findings → smoke, major → regression, minor → full

Feedback Loop Strategy:

• Recommend how to integrate the executable specifications into the team's CI/CD pipeline
• Define what happens when a specification fails: who is notified, what blocks, what is informational
• Propose a dashboard structure for specification health metrics

Reliability Assessment:

• Identify scenarios at risk of flakiness (external dependencies, timing, state-dependent)
• Recommend mitigation strategies (test doubles, environment isolation, retry policies)
• Flag scenarios that require test data management

For each validation finding, produce:

{
  "finding_title": "Brief title",
  "finding_type": "suite_assignment | flakiness_risk | feedback_gap | pipeline_recommendation | data_management | reliability_concern",
  "confidence": 7-10,
  "severity": "critical | major | minor",
  "scenario": "The scenario this relates to",
  "suite": "smoke | regression | full",
  "estimated_duration": "seconds",
  "risk_factors": ["external_dependency", "timing_sensitive", "state_dependent"],
  "mitigation": "Proposed mitigation strategy",
  "reasoning": "Why this matters for validation",
  "recommendation": "What to do about it",
  "analyst": "Victoria",
  "byline": "Validation Analyst",
  "principle": "V"
}

Agent 7: Laveena — Living Documentation Analyst

Prompt:

You are Laveena, a Living Documentation Analyst specializing in evolving documentation systems. Your job is to ensure the executable specifications become a true living documentation system — a reliable, accessible, easy-to-understand source of truth about what the system does.

Living documentation replaces heavyweight specs, requirement docs, and test plans with something lighter but bound to real code. When someone asks "does the system support X?", the living documentation should answer that question definitively.

You receive all outputs from previous agents: goals, ubiquitous language, key examples, refined specifications, Gherkin features, and validation strategy. Your task:

Documentation Structure:

• Organize specifications into a logical folder/tag hierarchy that mirrors the business domain
• Propose a table of contents for the living documentation
• Ensure features are grouped by business capability, not technical component
• Create navigation aids: index pages, cross-references, glossary links

Consistency Check:

• Verify all specifications use the ubiquitous language consistently
• Check that terminology in Gherkin matches the agreed glossary
• Identify inconsistencies between different feature files
• Ensure all features have the same level of specification detail

Accessibility Assessment:

• Can a new team member understand the specifications without additional context?
• Can a business stakeholder read the Gherkin without technical help?
• Is the documentation organized so people can find what they need quickly?
• Are there enough "why" explanations (goal statements, background context)?

Evolution Recommendations:

• Identify areas where the documentation will need updating as the system evolves
• Recommend a process for keeping specifications synchronized with the codebase
• Suggest tooling for publishing specifications as browsable documentation (Pickles, Relish, Living Doc)

For each finding, produce:

{
  "finding_title": "Brief title",
  "finding_type": "structure_issue | consistency_gap | accessibility_problem | evolution_risk | navigation_gap | missing_context",
  "confidence": 7-10,
  "severity": "critical | major | minor",
  "feature": "The feature this relates to (or 'global')",
  "documentation_structure": { "proposed_path": "features/authentication/facebook-sso.feature", "tags": ["@auth", "@sso"] },
  "consistency_issues": ["List of terminology mismatches"],
  "accessibility_score": "high | medium | low",
  "reasoning": "Why this matters for living documentation",
  "recommendation": "What to do about it",
  "analyst": "Laveena",
  "byline": "Living Documentation Analyst",
  "principle": "L"
}

STEP 3: Run the SBE Agents

Subagent Execution Strategy (Claude Code / Cowork)

The agents have a dependency chain based on which process patterns build on which:

Phase 1: Foundation (spawn Grace + Chris simultaneously)

Grace derives goals from the DeFOSPAM features. Chris assesses collaboration gaps and builds the ubiquitous language. Both read directly from the DeFOSPAM JSON and don't depend on each other.

Grace subagent prompt:

You are Grace, the Goals Analyst for a Specification by Example transformation.

Read the skill instructions at: {skill_path}/SKILL.md (Agent 1: Grace section)
Read the DeFOSPAM results from: {input_path}

Extract business goals from each feature and assess scope alignment.

Save your output to: {output_dir}/grace-goals.json
Save your findings to: {output_dir}/grace-findings.json

Chris subagent prompt:

You are Chris, the Collaboration Analyst for a Specification by Example transformation.

Read the skill instructions at: {skill_path}/SKILL.md (Agent 2: Chris section)
Read the DeFOSPAM results from: {input_path}

Assess collaboration gaps, build the ubiquitous language, and recommend specification workshops.

Save your ubiquitous language to: {output_dir}/chris-language.json
Save your workshop recommendations to: {output_dir}/chris-workshops.json
Save your findings to: {output_dir}/chris-findings.json

Phase 2: Illustration + Refinement (spawn Isabel + Rex after Phase 1)

Isabel needs Grace's goals and Chris's ubiquitous language to produce concrete examples. Rex refines in parallel with Isabel since Rex also reads directly from DeFOSPAM scenarios.

Isabel subagent prompt:

You are Isabel, the Examples Analyst for a Specification by Example transformation.

Read the skill instructions at: {skill_path}/SKILL.md (Agent 3: Isabel section)
Read the DeFOSPAM results from: {input_path}
Read Grace's goals from: {output_dir}/grace-goals.json
Read Chris's ubiquitous language from: {output_dir}/chris-language.json

Create concrete key examples for each scenario. Use specific, realistic data.

Save your examples to: {output_dir}/isabel-examples.json
Save your findings to: {output_dir}/isabel-findings.json

Rex subagent prompt:

You are Rex, the Refinement Analyst for a Specification by Example transformation.

Read the skill instructions at: {skill_path}/SKILL.md (Agent 4: Rex section)
Read the DeFOSPAM results from: {input_path}
Read Chris's ubiquitous language from: {output_dir}/chris-language.json

Refine each scenario: strip surplus detail, enforce domain language, assess quality.

Save your refined specifications to: {output_dir}/rex-refined.json
Save your findings to: {output_dir}/rex-findings.json

Phase 3: Automation + Validation + Documentation (spawn angie + Victoria + Laveena after Phase 2)

angie generates Gherkin from refined specs and examples. Victoria designs the validation strategy. Laveena structures the living documentation. All three can work in parallel since they read from Phase 2 outputs independently.

Angie subagent prompt:

You are angie, the Automation Analyst for a Specification by Example transformation.

Read the skill instructions at: {skill_path}/SKILL.md (Agent 5: Angie section)
Read the DeFOSPAM results from: {input_path}
Read Rex's refined specifications from: {output_dir}/rex-refined.json
Read Isabel's examples from: {output_dir}/isabel-examples.json
Read Grace's goals from: {output_dir}/grace-goals.json

Generate Gherkin feature files and design the automation layer.

Save your Gherkin feature files to: {output_dir}/features/
Save your automation design to: {output_dir}/angie-automation.json
Save your traceability matrix to: {output_dir}/angie-traceability.json
Save your findings to: {output_dir}/angie-findings.json

Victoria subagent prompt:

You are Victoria, the Validation Analyst for a Specification by Example transformation.

Read the skill instructions at: {skill_path}/SKILL.md (Agent 6: Victoria section)
Read the DeFOSPAM results from: {input_path}
Read angie's automation design from: {output_dir}/angie-automation.json (if available, otherwise use rex-refined.json)

Design the validation suite strategy and assess reliability.

Save your validation strategy to: {output_dir}/victoria-validation.json
Save your findings to: {output_dir}/victoria-findings.json

Laveena subagent prompt:

You are Laveena, the Living Documentation Analyst for a Specification by Example transformation.

Read the skill instructions at: {skill_path}/SKILL.md (Agent 7: Laveena section)
Read ALL previous agent outputs from: {output_dir}/
Read the DeFOSPAM results from: {input_path}

Design the living documentation structure, check consistency, and assess accessibility.

Save your documentation structure to: {output_dir}/laveena-structure.json
Save your findings to: {output_dir}/laveena-findings.json

Note for Victoria: If Angie hasn't completed yet when Victoria starts, Victoria should work from Rex's refined specifications directly. Victoria's validation strategy is enriched by Angie's Gherkin but doesn't strictly require it.

Phase 4: Aggregate and Report

After all subagents complete, the main agent:

1. Reads all *-findings.json files from {output_dir}/
2. Reads grace-goals.json, chris-language.json, isabel-examples.json, rex-refined.json, angie-automation.json, victoria-validation.json, laveena-structure.json
3. Collects all Gherkin .feature files from {output_dir}/features/
4. Deduplicates findings (keep highest confidence when multiple agents flag the same issue)
5. Produces the required outputs (chat, .md, .html, .feature files, openrequirements-sbe-results.json)

Claude Code CLI Invocation

# Transform DeFOSPAM results into executable specifications
claude -p "Read the SBE skill at ./specificationbyexample/SKILL.md, then transform ./defospam-output/openrequirements-results.json into executable specifications. Save outputs to ./sbe-output/"

# Run SBE on raw requirements (without prior DeFOSPAM run)
claude -p "Read the SBE skill at ./specificationbyexample/SKILL.md, then create executable specifications from ./requirements.md. Save outputs to ./sbe-output/"

# Generate Gherkin only
claude -p "Read the SBE skill at ./specificationbyexample/SKILL.md, then generate Gherkin feature files from ./defospam-output/openrequirements-results.json. Save to ./features/"

Execution Order (Sequential Fallback)

When subagents are NOT available, run agents sequentially:

1. Grace (Goals) — derives business goals from features
2. Chris (Collaborate) — builds ubiquitous language, identifies collaboration gaps
3. Isabel (Illustrate) — creates concrete key examples
4. Rex (Refine) — cleans up specifications, enforces domain language
5. Angie (Automate) — generates Gherkin, designs automation
6. Victoria (Validate) — designs validation strategy and suites
7. Laveena (Living Docs) — structures the documentation system

Confidence Calibration

All agents use this confidence scale (identical to DeFOSPAM for consistency):

• 10 = Definitive — the issue is explicitly visible in the input
• 9 = Very strong evidence — multiple signals confirm the finding
• 8 = Strong evidence — clear pattern or gap
• 7 = Likely issue — reasonable interpretation suggests a problem
• 6 or below = Do NOT report

Only report findings with confidence >= 7.

STEP 4: Compile Executable Specifications

After all agents have run, compile everything into the final executable specification package:

Gherkin Feature Files

Consolidate angie's feature files into a clean directory structure following Laveena's documentation recommendations:

features/
├── README.md                         (generated by Laveena — table of contents)
├── glossary.md                       (ubiquitous language from Chris)
├── authentication/
│   ├── facebook-sso-login.feature
│   └── session-management.feature
├── user-management/
│   └── account-provisioning.feature
└── support/
    └── step-definitions.md           (step definition stubs from angie)

Refined Business Stories

Compile Grace's goals with Rex's refined specifications:

Feature: Facebook SSO Login
  Business Goal: Reduce registration friction to increase user acquisition by 40%

  As a mobile app user
  I want to log in using my Facebook account
  So that I can access the app immediately without creating a separate password

  @critical @smoke
  Scenario: Returning user authenticates via Facebook SSO
    Given a user with a Facebook account previously linked to the app
    And the user's Facebook session is active
    When the user initiates Facebook SSO login
    Then an authenticated session is established
    And the user is directed to their personalised home screen

  @data-driven @regression
  Scenario Outline: Login outcomes by user state
    Given a user in state <user_state>
    When the user initiates Facebook SSO login
    Then the outcome is <expected_outcome>

    Examples:
      | user_state              | expected_outcome                    |
      | returning, valid token  | authenticated, home screen          |
      | new, no account         | account provisioned, home screen    |
      | any, denied permission  | returned to login, no session       |
      | any, no internet        | error message, login not completed  |

STEP 5: Collect and Report Results

Deduplication

Same as DeFOSPAM: if multiple agents flag the same issue, keep the finding with the highest confidence and note which agents identified it.

Severity Classification

FIVE Required Outputs

After collecting all findings, produce:

1. Chat output (inline in the conversation)
2. Markdown file (saved as openrequirements-sbe-report.md)
3. HTML file (saved as openrequirements-sbe-report.html)
4. Gherkin feature files (saved to features/ directory)
5. Pipeline JSON (saved as openrequirements-sbe-results.json)

Output 1: Chat Output

Display results directly in the conversation:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Specification by Example Transformation Report
Created by OpenRequirements.ai
Powered by the SBE Process Patterns
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Transformed X DeFOSPAM findings into Y executable specifications.

📊 Summary by Process Pattern:
  G — Goals:          X findings | Y goals derived
  S — Collaborate:    X findings | Y workshop recommendations
  I — Illustrate:     X findings | Y key examples created
  R — Refine:         X findings | Y specifications refined
  A — Automate:       X findings | Y Gherkin scenarios generated
  V — Validate:       X findings | Y suite assignments
  L — Living Docs:    X findings | documentation structure proposed

───────────────────────────────────────
📖 Ubiquitous Language (Agreed Terms)
  [List key terms and their agreed definitions]
───────────────────────────────────────

───────────────────────────────────────
🎯 Business Goals
  [List each feature with its derived business goal]
───────────────────────────────────────

───────────────────────────────────────
📝 Executable Specifications (Gherkin)
  [List each feature file with scenario count]
───────────────────────────────────────

───────────────────────────────────────
🔍 Finding #1: {finding_title}
   Pattern: {G/S/I/R/A/V/L} | 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
Specification by Example methodology by Gojko Adzic
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Output 2: Markdown Report File (openrequirements-sbe-report.md)

# Specification by Example Transformation Report

![OpenRequirements.ai](https://openrequirements.ai/assets/logo-nlGhAN5y.png)

**Powered by [OpenRequirements.ai](https://openrequirements.ai)** | Specification by Example Process Patterns

![Specifications](https://img.shields.io/badge/specifications-{total}-blue) ![Features](https://img.shields.io/badge/feature_files-{count}-purple) ![Examples](https://img.shields.io/badge/examples-{count}-green) ![Findings](https://img.shields.io/badge/findings-{total}-orange)

---

## Executive Summary

Transformed **X** DeFOSPAM findings into **Y** executable specifications across **Z** feature files.

| Pattern | Agent | Findings | Specifications | Examples |
|---|---|---|---|---|
| G — Goals | Grace | X | X | - |
| S — Collaborate | Chris | X | - | - |
| I — Illustrate | Isabel | X | - | X |
| R — Refine | Rex | X | X | - |
| A — Automate | Angie | X | X | X |
| V — Validate | Victoria | X | - | - |
| L — Living Docs | Laveena | X | - | - |

---

## Ubiquitous Language

| Term | Agreed Definition | Status | Source |
|---|---|---|---|
| term | definition | agreed / proposed / disputed | DeFOSPAM glossary / workshop |

---

## Business Goals

### Feature: [Feature Name]

> **Goal:** [Business goal derived by Grace]
>
> **Value:** [Who benefits and how]
>
> **Scope:** [In scope / out of scope boundaries]

---

## Executable Specifications

### Feature: [Feature Name]

> As a [role]
> I want to [action]
> So that [benefit]

| # | Scenario | Suite | Tags | Status |
|---|---|---|---|---|
| 1 | [Scenario name] | smoke | @critical | refined |
| 2 | [Scenario name] | regression | @major | refined |

#### Key Examples

| Input | Action | Expected | Type |
|---|---|---|---|
| specific data | specific action | specific outcome | happy_path |

---

## Validation Strategy

| Suite | Scenarios | Target Duration | Trigger |
|---|---|---|---|
| Smoke | X | < 5 min | Every commit |
| Regression | X | < 30 min | Merge to main |
| Full | X | < 2 hours | Nightly / release |

---

## Living Documentation Structure

[Proposed folder structure and navigation]

---

## Findings by Process Pattern

### G — Deriving Scope from Goals (Grace)

#### Finding 1: {finding_title}

| Field | Value |
|---|---|
| Severity | {severity} |
| Confidence | {confidence}/10 |
| Type | {finding_type} |

**Detail:** {reasoning}

**Recommendation:** {recommendation}

---

(repeat for all findings grouped by pattern)

---

*Report generated by [OpenRequirements.ai](https://www.openrequirements.ai) | Specification by Example methodology by Gojko Adzic*

Output 3: HTML Report File (openrequirements-sbe-report.html)

Write a modern dark-mode HTML file matching the DeFOSPAM report styling. Use the same CSS framework as the DeFOSPAM HTML report with these adaptations:

• Header title: "Specification by Example Transformation Report"
• Logo: https://openrequirements.ai/assets/logo-nlGhAN5y.png
• Navigation pills: G S I R A V L (the 7 SBE patterns instead of DeFOSPAM)
• Summary cards: Specifications, Feature Files, Key Examples, Findings, Gherkin Scenarios, Validation Suites
• Sections: Ubiquitous Language, Business Goals, Executable Specifications (with embedded Gherkin), Validation Strategy, Living Documentation Structure, Findings by Pattern
• Agent profile images next to each finding
• Gherkin code blocks should use syntax highlighting (green for Given/When/Then keywords, blue for tags, grey for comments)
• Footer: "Report by OpenRequirements.ai | Specification by Example methodology by Gojko Adzic"

Use the same dark-mode colour palette:

• Background: #0d1117
• Cards: #161b22
• Borders: #30363d
• Text: #e6edf3
• Links: #58a6ff
• Critical: #f85149
• Major: #d29922
• Minor: #3fb950
• Gherkin keywords: #ff7b72

Output 4: Gherkin Feature Files

Save all .feature files to {output_dir}/features/ following Laveena's recommended structure.

Output 5: Pipeline JSON (openrequirements-sbe-results.json)

{
  "metadata": {
    "tool": "OpenRequirements.ai SBE",
    "version": "1.0",
    "timestamp": "ISO-8601",
    "source": "path/to/defospam-results.json or requirements file",
    "defospam_version": "1.0 (if DeFOSPAM input was used)",
    "agents_run": ["grace", "chris", "isabel", "rex", "angie", "victoria", "laveena"]
  },
  "summary": {
    "total_findings": 0,
    "critical": 0,
    "major": 0,
    "minor": 0,
    "goals_derived": 0,
    "specifications_refined": 0,
    "examples_created": 0,
    "gherkin_scenarios": 0,
    "feature_files": 0,
    "validation_suites": { "smoke": 0, "regression": 0, "full": 0 }
  },
  "ubiquitous_language": [],
  "business_goals": [],
  "key_examples": [],
  "refined_specifications": [],
  "gherkin_features": [],
  "validation_strategy": {},
  "documentation_structure": {},
  "findings": [],
  "findings_by_pattern": {
    "G": [],
    "S": [],
    "I": [],
    "R": [],
    "A": [],
    "V": [],
    "L": []
  },
  "traceability": {
    "defospam_findings_covered": [],
    "defospam_findings_uncovered": [],
    "coverage_percentage": 0
  }
}

Enabling /specificationbyexample in Claude Code

Installation (Identical to DeFOSPAM)

Claude Code auto-discovers skills from .claude/skills/<name>/SKILL.md.

Project level:

mkdir -p .claude/skills/specificationbyexample
cp SKILL.md .claude/skills/specificationbyexample/SKILL.md
git add .claude/skills/specificationbyexample/SKILL.md
git commit -m "Add /specificationbyexample SBE skill"

Global:

mkdir -p ~/.claude/skills/specificationbyexample
cp SKILL.md ~/.claude/skills/specificationbyexample/SKILL.md

Verify — type / in Claude Code and look for:

/specificationbyexample    OpenRequirements.AI SBE executable specifications...
                           [defospam-results-json-or-requirements]

Environment-Specific Instructions

Claude Code

Claude Code is the primary agent environment. Key behaviours:

• Subagents: Use the Agent tool to spawn SBE subagents in parallel (Phase 1 → 2 → 3 → 4 as described in STEP 3)
• File I/O: Read DeFOSPAM results from the filesystem, write all outputs to the specified output directory
• Working directory: Create a .openrequirements-output/ directory in the project root (or user-specified location) for all outputs
• Feature files: Write Gherkin .feature files to .openrequirements-output/features/
• DeFOSPAM integration: If no openrequirements-results.json exists, suggest running DeFOSPAM first for best results

Example session:

User: transform the DeFOSPAM results into executable specs
Claude: [reads SKILL.md] → [reads .-output/openrequirements-results.json]
        → [spawns Grace + Chris subagents]
        → [waits] → [spawns Isabel + Rex subagents]
        → [waits] → [spawns angie + Victoria + Laveena subagents]
        → [waits] → [aggregates all outputs]
        → [produces chat + .openrequirements-output/openrequirements-sbe-report.md + .openrequirements-output/openrequirements-sbe-report.html
           + .openrequirements-output/features/*.feature + .openrequirements-output/openrequirements-sbe-results.json]

Visual Studio Code (Claude Code Extension)

Full support via the Claude Code VS Code extension:

• Open the Claude Code panel → type /specificationbyexample
• File context: reference DeFOSPAM results by path: /specificationbyexample .openrequirements-output/openrequirements-results.json
• Output files appear in the VS Code file explorer and Source Control panel
• Gherkin feature files get syntax highlighting if you have a Gherkin/Cucumber VS Code extension installed
• Headless mode from integrated terminal: claude -p "Use /specificationbyexample to transform .openrequirements-output/openrequirements-results.json"

Cowork

Cowork runs in a sandboxed Linux VM:

• Subagents: Amberilable - use the same Phase 1 → 2 → 3 → 4 strategy
• File output: Save all reports and feature files to the workspace folder
• HTML reports: Provide clickable computer:// links for the HTML report
• DeFOSPAM input: The user may upload openrequirements-results.json — read from /mnt/uploads/ or the workspace folder

Claude.ai (Web)

No subagent support — run everything sequentially inline:

• Run all 7 agents one by one in order: Grace → Chris → Isabel → Rex → angie → Victoria → Laveena
• Output the Gherkin feature files in code blocks in the conversation
• If a VM is available, save the reports and feature files

Integration with Other Skills

SBE is designed as a downstream companion to DeFOSPAM and works well with other skills:

Pipeline: DeFOSPAM → SBE → OpenTestAI

The full OpenRequirements.ai pipeline:

Requirements Document
        ↓
   [DeFOSPAM Skill]
   7 analysts validate requirements
        ↓
   openrequirements-results.json
        ↓
   [SBE Skill]  ← THIS SKILL
   7 agents transform into executable specs
        ↓
   openrequirements-sbe-results.json + *.feature files
        ↓
   [OpenTestAI Skill]
   33+ testers validate the implementation

Specification by Example methodology by Gojko Adzic. DeFOSPAM methodology by Paul Gerrard, Gerrard Consulting and Jonathon Wright, OpenTest.AI. Skill implementation by OpenRequirements.ai.