Discovery Commands (Example Mapping)

Commands for collaborative discovery using Example Mapping.

Overview

Use Example Mapping commands when you need to:

• Add concrete examples to explore behavior
• Add questions that need answers before implementation
• Add business rules that govern the feature
• Add assumptions about requirements or constraints
• Capture architecture notes and non-functional requirements
• Attach supporting files (diagrams, mockups, documents)
• Answer questions collaboratively (AI asks, human answers)
• Generate Gherkin scenarios from examples
• Import/export example maps for collaboration
• Query example mapping coverage statistics

Example Mapping is a collaborative discovery technique that happens before writing Gherkin specifications. It uses colored cards to organize information:

• Yellow - User story (created with fspec set-user-story)
• Blue - Business rules (created with fspec add-rule)
• Green - Concrete examples (created with fspec add-example)
• Red - Questions that need answers (created with fspec add-question)
• Gray - Assumptions about requirements or constraints (created with fspec add-assumption)
• Purple - Architecture notes and NFRs (created with fspec add-architecture-note)
• Paperclip - Supporting files and attachments (created with fspec add-attachment)

User Story

Set User Story

Set the user story for a work unit, capturing the role, action, and benefit.

fspec set-user-story <work-unit-id> [options]

Options:

• --role <role> - User role or persona (e.g., "developer", "system admin")
• --action <action> - What the user wants to do
• --benefit <benefit> - Why the user wants it

Examples:

fspec set-user-story AUTH-001 \
  --role "developer" \
  --action "validate feature files automatically" \
  --benefit "I catch syntax errors before committing"
 
fspec set-user-story DASH-002 \
  --role "system admin" \
  --action "view all work unit statuses in one place" \
  --benefit "I can track team progress at a glance"

Important: Set the user story during the specifying phase to provide context for the feature.

Examples

Add Example

Add a concrete example to a work unit during specification.

fspec add-example <work-unit-id> <example>

Examples:

fspec add-example AUTH-001 "User logs in with valid email"
fspec add-example AUTH-001 "User enters wrong password, sees error"
fspec add-example AUTH-001 "User clicks 'Forgot password' link"

Remove Example

Remove an example by index (0-based).

fspec remove-example <work-unit-id> <index>

Examples:

fspec remove-example AUTH-001 0
fspec remove-example AUTH-001 2

Questions

Add Question

Add a question to a work unit during specification.

fspec add-question <work-unit-id> <question>

Examples:

fspec add-question AUTH-001 "Should we support OAuth?"
fspec add-question AUTH-001 "What happens if user has expired session?"
fspec add-question AUTH-001 "Do we need two-factor authentication?"

Answer Question

Answer a question and optionally convert it to a rule or assumption.

fspec answer-question <work-unit-id> <index> [options]

Options:

• --answer <answer> - Answer text
• --add-to <type> - Add to: rule, assumption, or none (default: none)

Examples:

# Answer and convert to rule
fspec answer-question AUTH-001 0 --answer "Yes, OAuth via Auth0" --add-to rule
 
# Answer and convert to assumption
fspec answer-question AUTH-001 1 --answer "Redirect to login" --add-to assumption
 
# Just answer without adding to rules/assumptions
fspec answer-question AUTH-001 2 --answer "Not in phase 1"

Remove Question

Remove a question by index (0-based).

fspec remove-question <work-unit-id> <index>

Examples:

fspec remove-question AUTH-001 0

Rules

Add Rule

Add a business rule to a work unit during specification.

fspec add-rule <work-unit-id> <rule>

Examples:

fspec add-rule AUTH-001 "Password must be 8+ characters"
fspec add-rule AUTH-001 "Email must be verified before login"
fspec add-rule AUTH-001 "Account locked after 5 failed attempts"

Remove Rule

Remove a rule by index (0-based).

fspec remove-rule <work-unit-id> <index>

Examples:

fspec remove-rule AUTH-001 0
fspec remove-rule AUTH-001 2

Assumptions

Add Assumption

Add an assumption to a work unit during specification.

fspec add-assumption <work-unit-id> <assumption>

Examples:

fspec add-assumption AUTH-001 "Email verification is handled externally"
fspec add-assumption AUTH-001 "We have rate limiting middleware"
fspec add-assumption AUTH-001 "Password hashing uses bcrypt"

Architecture Notes

Add Architecture Note

Capture architecture decisions, non-functional requirements, and technical constraints during discovery.

fspec add-architecture-note <work-unit-id> <note>

Architecture notes are included as docstrings in generated feature files, providing critical context for implementation.

Examples:

fspec add-architecture-note AUTH-001 "Uses @cucumber/gherkin parser for validation"
fspec add-architecture-note AUTH-001 "Performance: Must complete login within 2 seconds"
fspec add-architecture-note AUTH-001 "Security: Passwords hashed with bcrypt, salt rounds = 10"
fspec add-architecture-note API-005 "Depends on Redis for session storage"

Use Cases:

• Technical dependencies (libraries, services, APIs)
• Performance requirements (latency, throughput)
• Security constraints (encryption, authentication)
• Scalability notes (caching, load balancing)
• Integration points (external systems, webhooks)

Remove Architecture Note

Remove an architecture note by index (0-based).

fspec remove-architecture-note <work-unit-id> <index>

Examples:

fspec remove-architecture-note AUTH-001 0
fspec remove-architecture-note AUTH-001 2

Attachments

Add Attachment

Attach supporting files (diagrams, mockups, documents) to work units during discovery.

fspec add-attachment <work-unit-id> <file-path> [options]

Options:

• -d, --description <text> - Attachment description

Attachments are copied to spec/attachments/<work-unit-id>/ and tracked in the work unit metadata.

Mermaid Diagram Validation: Files with Mermaid extensions (.mmd, .mermaid, .md) are automatically validated for syntax errors before being attached. Invalid diagrams will be rejected with detailed error messages.

Examples:

fspec add-attachment AUTH-001 diagrams/auth-flow.png
fspec add-attachment AUTH-001 mockups/login-page.png --description "Login UI v2"
fspec add-attachment UI-002 docs/dashboard-spec.pdf --description "Dashboard requirements"
fspec add-attachment API-001 swagger.yaml --description "API specification"
fspec add-attachment ARCH-001 diagrams/system-flow.mmd --description "System architecture"

Supported File Types:

• Images: .png, .jpg, .svg, .gif
• Documents: .pdf, .md, .txt
• Diagrams: .mmd (Mermaid), .mermaid, .drawio
• Specifications: .yaml, .json, .xml

Note: Mermaid diagram files (.mmd, .mermaid) and Markdown files (.md) containing Mermaid code blocks are validated using the same validation logic as the add-diagram command. This ensures diagram syntax is correct before attachment.

List Attachments

List all attachments for a work unit.

fspec list-attachments <work-unit-id>

Examples:

fspec list-attachments AUTH-001

Output:

Attachments for AUTH-001:
  1. auth-flow.png (45.2 KB)
  2. login-page.png - Login UI v2 (128.5 KB)

Remove Attachment

Remove an attachment from a work unit.

fspec remove-attachment <work-unit-id> <file-name> [options]

Options:

• --keep-file - Keep the file on disk (only remove from work unit metadata)

Examples:

fspec remove-attachment AUTH-001 auth-flow.png
fspec remove-attachment AUTH-001 diagram.png --keep-file

Import/Export

Import Example Map

Import examples, rules, and questions from a JSON file.

fspec import-example-map <work-unit-id> <file>

Examples:

fspec import-example-map AUTH-001 examples.json

JSON Format:

{
  "rules": [
    "Password must be 8+ characters",
    "Email must be verified"
  ],
  "examples": [
    "User logs in with valid email",
    "User enters wrong password"
  ],
  "questions": [
    "Should we support OAuth?"
  ],
  "assumptions": [
    "Email verification handled externally"
  ]
}

Export Example Map

Export examples, rules, questions, and assumptions to a JSON file.

fspec export-example-map <work-unit-id> <file>

Examples:

fspec export-example-map AUTH-001 examples.json

Generation

Generate Scenarios

Generate Gherkin scenarios from Example Mapping data.

fspec generate-scenarios <work-unit-id>

This command:

1. Takes rules, examples, questions, and architecture notes from the work unit
2. Generates a Gherkin feature file with proper structure
3. Creates scenarios based on examples
4. Includes business rules as Given conditions
5. Adds architecture notes as docstrings in the feature file
6. Marks unanswered questions as TODO comments

Examples:

fspec generate-scenarios AUTH-001

Prerequisites:

• Work unit should have rules, examples, or both
• All red cards (questions) should be answered

Output:

• Creates or updates spec/features/<feature-name>.feature
• Creates Scenario for each example
• Adds architecture notes as docstrings (triple-quoted comments)
• Includes business rules in scenario steps

Statistics

Query Example Mapping Stats

Show example mapping coverage across all work units.

fspec query-example-mapping-stats

This command shows:

• Total work units
• How many have rules, examples, questions
• Average cards per work unit
• Work units ready for scenario generation

Examples:

fspec query-example-mapping-stats

Example Mapping Workflow

The typical Example Mapping workflow with fspec:

1. Create Work Unit and Set User Story

fspec create-work-unit AUTH "User login"
fspec update-work-unit-status AUTH-001 specifying
 
fspec set-user-story AUTH-001 \
  --role "registered user" \
  --action "log in to my account" \
  --benefit "I can access my personalized dashboard"

2. Add Business Rules (Blue Cards)

fspec add-rule AUTH-001 "Password must be 8+ characters"
fspec add-rule AUTH-001 "Email must be verified before login"
fspec add-rule AUTH-001 "Account locked after 5 failed attempts"

3. Add Concrete Examples (Green Cards)

fspec add-example AUTH-001 "User logs in with valid email and password"
fspec add-example AUTH-001 "User enters wrong password, sees error message"
fspec add-example AUTH-001 "User with unverified email cannot log in"
fspec add-example AUTH-001 "User locked out after 5 failures"

4. Add Questions (Red Cards)

fspec add-question AUTH-001 "Should we support OAuth providers?"
fspec add-question AUTH-001 "What happens to expired sessions?"
fspec add-question AUTH-001 "Do we need two-factor authentication?"

5. Answer Questions

# Convert answered question to rule
fspec answer-question AUTH-001 0 \
  --answer "Yes, support Google and GitHub via Auth0" \
  --add-to rule
 
# Convert answered question to assumption
fspec answer-question AUTH-001 1 \
  --answer "Redirect to login page" \
  --add-to assumption
 
# Just answer without adding to rules
fspec answer-question AUTH-001 2 \
  --answer "Not in phase 1, defer to AUTH-010"

6. Add Architecture Notes (Purple Cards)

fspec add-architecture-note AUTH-001 "Uses bcrypt for password hashing, salt rounds = 10"
fspec add-architecture-note AUTH-001 "Session timeout: 30 minutes of inactivity"
fspec add-architecture-note AUTH-001 "Depends on Auth0 for OAuth providers"

7. Attach Supporting Files (Optional)

fspec add-attachment AUTH-001 diagrams/auth-flow.png --description "Authentication flow diagram"
fspec add-attachment AUTH-001 mockups/login-ui.png --description "Login page mockup"

8. Generate Scenarios

Once all questions are answered:

fspec generate-scenarios AUTH-001

This creates spec/features/user-login.feature with:

• Scenarios generated from examples
• Architecture notes as docstrings (triple-quoted comments)
• Business rules as Given conditions
• Assumptions documented in the feature

9. Move to Testing

fspec update-work-unit-status AUTH-001 testing

Now write failing tests that implement the scenarios!

Benefits of Example Mapping

1. Collaborative Discovery - AI asks questions, human provides answers
2. Structured Exploration - Rules, examples, questions organized systematically
3. Reduces Ambiguity - Red cards (questions) must be answered before implementation
4. Better Specifications - Examples become concrete scenarios
5. Faster Estimation - Card count correlates with complexity
6. Prevents Scope Creep - Out-of-scope questions become new work units

See Also

• Example Mapping Concepts - Understanding the four card types
• Specification Commands - Create and manage Gherkin features
• Work Management - Manage work units and workflow
• ACDD Concepts - Acceptance Criteria Driven Development