Nw Jtbd Bdd IntegrationSAFE

AI agents that guide you from idea to working code, with you in control at every step.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nw-jtbd-bdd-integration
description: Translating JTBD analysis to BDD scenarios - job story to Given-When-Then patterns, forces-based test discovery, job-map-based test discovery, and property-shaped criteria
user-invocable: false
disable-model-invocation: true
---

# JTBD to BDD Integration

Use when translating JTBD discoveries (job stories, forces, job map) into testable BDD scenarios. Job stories map naturally to Given-When-Then because both emphasize context (situation/given), action (motivation/when), and outcome (result/then).

## Job Story to Given-When-Then Translation

### The Pattern

```
Job Story:
  When [situation],
  I want to [motivation],
  so I can [outcome].

BDD Scenario:
  Given [the situation from the job story]
  When [user takes action aligned with the motivation]
  Then [the outcome is achieved and measurable]
```

### Worked Example

**Job Story**: "When I receive an alert that a production service is degraded, I want to see the most likely root cause with supporting evidence, so I can begin remediation within minutes instead of hours."

```gherkin
Scenario: Root cause surfaced from degradation alert
  Given the monitoring system has detected degraded response times on the payment service
  And the degradation started 5 minutes ago
  When the operator opens the incident dashboard
  Then the system displays the top 3 probable root causes ranked by likelihood
  And each root cause includes supporting metrics and log evidence
  And the most likely root cause is displayed within 10 seconds

Scenario: Remediation guidance from identified root cause
  Given the operator has identified the root cause as database connection pool exhaustion
  When the operator selects the recommended remediation action
  Then the system presents a runbook with step-by-step instructions
  And the estimated time to remediate is displayed
  And the operator can execute the first step directly from the dashboard
```

### Translation Rules

1. **Given** = situation from job story, made concrete with specific data
2. **When** = user action fulfilling the motivation
3. **Then** = measurable outcome, including quality attributes (time, confidence, completeness)

### Multi-Scenario Expansion

One job story typically produces 3-5 BDD scenarios:
- **Happy path**: Outcome achieved as described
- **Anxiety path**: User's fear about new solution addressed
- **Habit path**: User transitioning from old workflow supported
- **Edge cases**: Derived from job map steps (see below)

## Forces-Based Test Discovery

Use Four Forces to discover test scenarios that feature-driven thinking misses.

### Force-to-Scenario Mapping

| Force | Test Question | Scenario Pattern |
|-------|--------------|-----------------|
| **Push** | What frustration drove the user here? | `Given [user has experienced the frustration]...` |
| **Pull** | What outcome is the user hoping for? | `Then [the promised improvement is measurable]` |
| **Anxiety** | What could go wrong with the new solution? | `Given [user has specific fear] When [fear-triggering event] Then [safety net activates]` |
| **Habit** | What existing workflow might resist adoption? | `Given [user accustomed to old way] When [new approach encountered] Then [familiar patterns preserved]` |

### Worked Example: Automated Deployment Tool

**Forces analysis**:
- Push: Manual deployments cause errors and take hours
- Pull: One-command deployment with automatic rollback
- Anxiety: "What if the automated rollback breaks worse than the original deploy?"
- Habit: Team SSH-es into servers and runs scripts manually

**Derived scenarios**:

```gherkin
# Push scenario: validates the frustration is resolved
Scenario: Deployment completes without manual intervention
  Given the operator has configured deployment for the payment service
  And the previous manual deployment took 3 hours with 2 errors
  When the operator runs the automated deployment command
  Then deployment completes within 15 minutes
  And zero manual steps are required

# Pull scenario: validates the promised outcome
Scenario: Automatic rollback on health check failure
  Given the deployment has completed and health checks are running
  When the payment endpoint returns 500 errors for 30 seconds
  Then the system automatically rolls back to the previous version
  And the operator receives a notification with rollback details

# Anxiety scenario: addresses the specific fear
Scenario: Rollback preserves database state
  Given the deployment included a database migration
  And the health check has triggered an automatic rollback
  When the rollback completes
  Then the database schema matches the previous stable version
  And no data is lost during the rollback process
  And the operator can verify data integrity from the dashboard

# Habit scenario: eases the transition
Scenario: Manual override available during automated deployment
  Given the operator is accustomed to SSH-based manual deployments
  When the automated deployment is in progress
  Then the operator can view real-time logs (familiar output format)
  And the operator can pause or cancel the deployment at any stage
  And manual SSH access remains available as a fallback
```

## Job-Map-Based Test Discovery

Walk each of the 8 job map steps and generate at least one test scenario per step. Surfaces edge cases that happy-path thinking misses.

| Job Map Step | Missing Scenario Pattern | Example |
|-------------|------------------------|---------|
| **Define** | User lacks information to start | `Given the user has not reviewed the change log When they attempt to deploy Then the system warns about unreviewed changes` |
| **Locate** | Required inputs unavailable or stale | `Given the build artifact is 30 days old When the user selects it for deployment Then the system flags the artifact as potentially stale` |
| **Prepare** | Setup fails or environment misconfigured | `Given the target environment has a port conflict When preparation runs Then the s

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.