Discovery Commands
Overview
The Discovery commands implement Example Mapping, a collaborative discovery technique that helps teams explore requirements before writing formal specifications. These commands enable structured conversations about features, capturing examples, questions, rules, and assumptions in a format that can be easily converted into Gherkin scenarios.
Use discovery commands when you need to:
- Add concrete examples that explore feature behavior and edge cases
- Capture questions that need answers before implementation can begin
- Document business rules that govern the feature's behavior
- Record assumptions about requirements or technical constraints
- Add architecture notes and non-functional requirements
- Attach supporting files like diagrams, mockups, and reference documents
- Facilitate collaborative Q&A between AI agents and humans
- Generate Gherkin scenarios automatically from captured examples
- Import and export example maps for team collaboration
- Query statistics about example mapping coverage across work units
These commands bridge the gap between initial requirements and formal specifications, ensuring that acceptance criteria are well-understood before development begins.
Commands Reference
EXAMPLE MAPPING
EXAMPLES
Add Example
Adds a concrete example to a work unit during Example Mapping. Examples explore specific behaviors, edge cases, and scenarios that will eventually become acceptance criteria. This is the core command for capturing "what if?" discussions during discovery.
Usage:
fspec add-example <work-unit-id> <example>Description: Add example to work unit during specification
Examples:
fspec add-example AUTH-001 "User logs in with valid email"Remove Example
Removes an example from a work unit by its index position (0-based). Useful for cleaning up duplicate or irrelevant examples during the discovery process.
Usage:
fspec remove-example <work-unit-id> <index>Description: Remove example by index (0-based)
Examples:
fspec remove-example AUTH-001 0QUESTIONS
Add Question
Captures questions that need answers before implementation can proceed. Questions represent unknowns, ambiguities, or dependencies that must be resolved during the specifying phase. This helps track what needs clarification from stakeholders.
Usage:
fspec add-question <work-unit-id> <question>Description: Add question to work unit during specification
Examples:
fspec add-question AUTH-001 "Should we support OAuth?"Answer Question
Provides an answer to a previously captured question, resolving ambiguity and enabling progress. Answered questions become part of the work unit's context and inform scenario generation.
Usage:
fspec answer-question <work-unit-id> <index>Options:
- --answer
<answer>Answer text - --add-to
<type>Add to: rule, assumption, or none (default: none)
Examples:
fspec answer-question AUTH-001 0 --answer "Yes" --add-to ruleRemove Question
Removes a question from a work unit by its index position (0-based). Use this to clean up questions that are no longer relevant or were answered elsewhere.
Usage:
fspec remove-question <work-unit-id> <index>Description: Remove question by index (0-based)
Examples:
fspec remove-question AUTH-001 0RULES
Add Rule
Documents a business rule that governs feature behavior. Rules represent constraints, policies, or logical conditions that must be followed in all scenarios. These become the foundation for scenario preconditions and assertions.
Usage:
fspec add-rule <work-unit-id> <rule>Description: Add business rule to work unit during specification
Examples:
fspec add-rule AUTH-001 "Password must be 8+ characters"Remove Rule
Removes a business rule from a work unit by its index position (0-based). Useful for cleaning up rules that are no longer applicable or were captured incorrectly.
Usage:
fspec remove-rule <work-unit-id> <index>Description: Remove rule by index (0-based)
Examples:
fspec remove-rule AUTH-001 0ASSUMPTIONS
Add Assumption
Captures assumptions about requirements, technical constraints, or dependencies. Assumptions represent things we believe to be true but haven't verified. Tracking them helps identify risks and areas that need validation.
Usage:
fspec add-assumption <work-unit-id> <assumption>Description: Add assumption to work unit during specification
Examples:
fspec add-assumption AUTH-001 "Email verification is handled externally"ARCHITECTURE NOTES
Add Architecture Note
Adds technical architecture notes and non-functional requirements to a work unit. These notes capture implementation details, technical constraints, performance requirements, or security considerations that inform how the feature will be built.
Usage:
fspec add-architecture-note <work-unit-id> <note>Description: Capture architecture decisions, NFRs, dependencies
Examples:
fspec add-architecture-note AUTH-001 "Uses @cucumber/gherkin parser"
fspec add-architecture-note AUTH-001 "Performance: Must complete within 2 seconds"Remove Architecture Note
Removes an architecture note from a work unit by its index position (0-based). Use this to clean up notes that are outdated or no longer relevant.
Usage:
fspec remove-architecture-note <work-unit-id> <index>Description: Remove architecture note by index (0-based)
Examples:
fspec remove-architecture-note AUTH-001 0ATTACHMENTS
Add Attachment
Attaches supporting files (diagrams, mockups, documents, API contracts) to a work unit. Attachments are copied to spec/attachments/<work-unit-id>/ and help provide visual or reference context during discovery and implementation.
Usage:
fspec add-attachment <work-unit-id> <file-path>Description: Add attachment to work unit (diagrams, mockups, docs, etc.)
Options:
- -d, --description
<text>Attachment description
Examples:
fspec add-attachment AUTH-001 diagrams/auth-flow.png
fspec add-attachment UI-002 mockups/dashboard.png --description "Dashboard v2"List Attachments
Lists all files attached to a work unit, showing filenames and optional descriptions. Attachments are displayed when running show-work-unit and help team members find supporting documentation.
Usage:
fspec list-attachments <work-unit-id>Description: List all attachments for a work unit
Examples:
fspec list-attachments AUTH-001Remove Attachment
Removes an attachment from a work unit. By default, this deletes the file from disk. Use --keep-file to preserve the file while removing it from the work unit's tracking.
Usage:
fspec remove-attachment <work-unit-id> <file-name>Description: Remove attachment from work unit
Options:
- --keep-file Keep file on disk
Examples:
fspec remove-attachment AUTH-001 auth-flow.png
fspec remove-attachment AUTH-001 diagram.png --keep-fileIMPORT/EXPORT
Import Example Map
Imports Example Mapping data from a JSON file into a work unit. This enables sharing example maps between team members, migrating from external tools, or restoring backed-up discovery sessions.
Usage:
fspec import-example-map <work-unit-id> <file>Description: Import examples, rules, questions from JSON
Examples:
fspec import-example-map AUTH-001 examples.jsonExport Example Map
Exports Example Mapping data (examples, rules, questions, assumptions) to a JSON file. Useful for sharing with stakeholders, backing up discovery sessions, or integrating with external documentation tools.
Usage:
fspec export-example-map <work-unit-id> <file>Description: Export examples, rules, questions to JSON
Examples:
fspec export-example-map AUTH-001 examples.jsonGENERATION
Generate Scenarios
Automatically generates Gherkin scenarios from captured examples, rules, questions, and assumptions. This command creates a feature file with structured scenarios ready for refinement. It's the bridge between Example Mapping discovery and formal Gherkin specifications.
Usage:
fspec generate-scenarios <work-unit-id>Description: Generate Gherkin scenarios from example mapping data
Examples:
fspec generate-scenarios AUTH-001STATISTICS
Query Example Mapping Stats
Displays statistics about Example Mapping coverage across work units, showing how many examples, questions, rules, and assumptions have been captured. Helps track discovery progress and identify work units that need more exploration.
Usage:
fspec query-example-mapping-statsDescription: Show example mapping coverage
Examples:
fspec query-example-mapping-stats