skills/autoresearch/references/scenario-workflow.md

# Scenario Workflow — $autoresearch scenario

Scenario-driven use case generator that autonomously explores situations, edge cases, failure modes, and derivative scenarios from a seed scenario. Doesn't stop at obvious paths — iteratively discovers what could go wrong, what's missing, and what nobody thought of.

**Core idea:** Seed scenario in → Decompose into dimensions → Generate situations → Classify (new/duplicate/variant) → Expand edge cases → Log → Repeat. Every iteration explores one unexplored combination.

## Trigger

- User invokes `$autoresearch scenario`
- User says "explore scenarios", "generate use cases", "what could go wrong", "stress test this feature", "edge cases for", "what are all the ways this could fail"
- User wants to enumerate situations for a feature, workflow, or system

## Loop Support

```
# Unlimited — keep generating scenarios until interrupted
$autoresearch scenario

# Bounded — exactly N exploration iterations
$autoresearch scenario
Iterations: 25

# Focused scope
$autoresearch scenario
Scenario: User attempts to checkout with multiple payment methods
Domain: software
Depth: deep
```

## PREREQUISITE: Interactive Setup (when invoked without scenario)

**CRITICAL — BLOCKING PREREQUISITE:** If `$autoresearch scenario` is invoked without a scenario description, you MUST use direct prompting to gather context BEFORE proceeding to ANY phase. DO NOT skip this step. DO NOT jump to Phase 1 without completing interactive setup.

**TOOL AVAILABILITY:** direct prompting may be a deferred tool. If calling it fails or the schema is not available, you MUST use `ToolSearch` to fetch the direct prompting schema first, then retry. NEVER skip interactive setup because of a tool fetch issue — resolve the tool availability, then ask the questions.

The question count adapts (4-8) based on what context is already provided:

**Adaptive question selection rules:**
- No input at all → ask all 8 questions
- Vague scenario only (≤5 words OR no verb/action) → ask questions 2-8 (skip 1)
- Clear scenario (>5 words AND contains actor + action), no domain → ask questions 2, 4, 5, 6, 7 (5 questions)
- Clear scenario + domain (via `--domain` flag or explicit domain keyword like "API", "auth", "UX") → ask questions 4, 6, 7, 8 (4 questions)

**Classification examples:**
- "checkout" → **vague** (1 word, no actor, no action)
- "API rate limiting" → **vague** (no actor, no verb)
- "User resets password" → **clear** (actor=User, action=resets, object=password)
- "Admin deploys to production with rollback" → **clear + domain=software** (skip to 4 questions)

You MUST call direct prompting with the selected questions in ONE batched call:

| # | Header | Question | When to Ask | Options |
|---|--------|----------|-------------|---------|
| 1 | `Scenario` | "Describe the scenario you want to explore" | If not provided inline | Free text input |
| 2 | `Domain` | "What domain is this scenario in?" | If not obvious from scenario | "Software/API (code paths, error handling)", "Product/UX (user journeys, accessibility)", "Business/Process (workflows, approvals, compliance)", "Security/Compliance (threats, access control, data)", "Marketing/Sales (campaigns, funnels, conversions)", "Custom (I'll describe)" |
| 3 | `Actors` | "Who are the key actors/users in this scenario?" | If scenario doesn't mention actors | Detected from codebase/scenario + "End user", "Admin", "System/API", "External service", "Multiple (I'll list)" |
| 4 | `Goal` | "What's your primary goal for exploring this scenario?" | If intent is unclear | "Find edge cases and boundary conditions", "Generate test scenarios (Given/When/Then)", "Explore all user journeys and paths", "Stress test — find what breaks under pressure", "Map failure modes and recovery paths", "All of the above" |
| 5 | `Constraints` | "Any constraints or boundaries I should respect?" | If no scope or limits mentioned | "Technical limitations (infra, performance)", "Business rules (policies, SLAs)", "Regulatory/compliance requirements", "Time/resource constraints", "None — explore freely" |
| 6 | `Depth` | "How deep should I explore?" | Always | "Shallow scan (10 iterations — quick overview)", "Standard exploration (25 iterations — recommended)", "Deep investigation (50+ iterations — comprehensive)", "Unlimited — keep going until interrupted" |
| 7 | `Output` | "What output format is most useful?" | If domain doesn't make it obvious | "Use cases (Given/When/Then format)", "User stories (As a... I want... So that...)", "Test scenarios (input → expected → actual)", "Threat scenarios (attacker goal → vector → impact)", "Mixed — all applicable formats" |
| 8 | `Focus` | "Any specific area to stress test first?" | If scenario is broad | Suggested areas from scenario analysis + "Happy path first, then edge cases", "Jump straight to failure modes", "Explore everything equally" |

**IMPORTANT:** You MUST batch ALL selected questions into a SINGLE direct prompting call. NEVER ask questions one at a time — users need full context to make informed decisions together. If direct prompting only supports one question per call, include all questions in a single call with numbered headers.

## Architecture

```
$autoresearch scenario
  ├── Phase 1: Seed — Capture, parse, and analyze the scenario
  ├── Phase 2: Decompose — Break into exploration dimensions
  ├── Phase 3: Generate — Create ONE new situation
  ├── Phase 4: Classify — New? Valuable? Duplicate?
  ├── Phase 5: Expand — Derive edge cases, what-ifs, failure modes
  ├── Phase 6: Log — Record to scenario-results.tsv
  └── Phase 7: Repeat — Next unexplored dimension/combination
```

## Inline Context Parsing Rules

When the user provides arguments inline, parse them in this order (flags take precedence over positional text):

1. **Flags first:** Extract `--domain`, `--depth`, `--scope`, `--format`, `--focus`, `--iterations` (or `Iterations:` inline config)
2. **Scenario text:** Everything that isn't a flag or `Iterations:` config is the scenario description
3. **`Scenario:` prefix:** If text starts with `Scenario:`, strip the prefix
4. **Flag order doesn't matter:** `--domain software User resets password` = `User resets password --domain software`
5. **Conflict resolution:** If `--depth shallow` is set but `Iterations: 50` is also set, `Iterations:` wins (explicit iteration count overrides depth presets)

**Skip setup entirely when:** Scenario text is "clear" (>5 words with actor+action) AND at least `--domain` or `--depth` is provided. Proceed directly to Phase 1.

## Cancel & Interruption Handling

- If user selects "Cancel" in any direct prompting response → exit cleanly with message: "Scenario exploration cancelled. Run `$autoresearch scenario` again when ready."
- If user answers only some questions and stops responding → treat answered questions as config, ask remaining questions in a follow-up call
- If Ctrl+C during setup → no state persisted, clean restart on re-invocation

## Phase 1: Seed — Capture & Analyze Scenario

**STOP: Have you completed the Interactive Setup above?** If invoked without scenario/flags, you MUST complete the direct prompting call above BEFORE entering this phase.

Parse the scenario and build a structured understanding.

**Extract from scenario:**
- Primary actor(s) and their roles
- Goal/objective of the scenario
- Preconditions (what must be true before)
- Postconditions (expected outcomes)
- System components involved
- Data flows and transformations
- External dependencies

**If codebase context exists:**
- Read relevant source files mentioned in or related to the scenario
- Identify API routes, database models, UI components involved
- Map the technical implementation to the scenario description

**Output:** `✓ Phase 1: Seed analyzed — [N] actors, [M] components, [K] preconditions identified`

## Phase 2: Decompose — Break Into Exploration Dimensions

Map the scenario into exploration dimensions. Each dimension represents a category of situations to generate.

**Scenario Dimensions:**

| Dimension | Description | Exploration Focus |
|-----------|-------------|-------------------|
| **Happy path** | Normal successful flow | All steps complete as expected |
| **Error path** | Expected, handled failures | Validation errors, business rule violations |
| **Edge case** | Boundary conditions | Min/max values, empty inputs, unicode, huge payloads |
| **Abuse/misuse** | Adversarial or unintended behavior | Injection, privilege escalation, rate abuse |
| **Scale** | High volume/load scenarios | Concurrent users, large datasets, burst traffic |
| **Concurrent** | Race conditions and ordering | Simultaneous edits, distributed locks, eventual consistency |
| **Temporal** | Time-dependent behavior | Timeouts, expiry, scheduling, timezone edge cases |
| **Data variation** | Different input types and formats | Null, empty, unicode, special chars, max length |
| **Permission** | Access control and authorization | Role escalation, shared resources, delegation |
| **Integration** | External system interactions | API failures, timeouts, malformed responses, version mismatches |
| **Recovery** | System resilience | Crash recovery, retry logic, data consistency after failure |
| **State transition** | Object lifecycle | Invalid state transitions, partial updates, rollback |

**Dimension prioritization:**
1. Start with happy path (baseline understanding)
2. Error paths (most common real-world issues)
3. Edge cases (where bugs hide)
4. Domain-specific dimensions (security → abuse, product → UX, etc.)

**Output:** `✓ Phase 2: Decomposed — [N] dimensions active, [M] exploration vectors identified`

## Phase 3: Generate — Create ONE New Situation

Pick the highest-priority unexplored dimension/combination and generate a concrete situation.

**Situation format:**
```markdown
### [DIMENSION] Situation: [descriptive title]

**Actors:** [who is involved]
**Precondition:** [what must be true]
**Trigger:** [what action initiates this]
**Flow:**
1. [step 1]
2. [step 2]
3. [step N]
**Expected outcome:** [what should happen]
**What could go wrong:** [potential failure points]
**Severity:** [Critical/High/Medium/Low — impact if this fails]
```

**Generation strategies:**

| Strategy | When to Use | Method |
|----------|-------------|--------|
| **Dimension walk** | Early iterations | Pick next unexplored dimension, generate vanilla situation |
| **Combination** | Mid iterations | Combine 2 dimensions (e.g., edge case + concurrent) |
| **Negation** | When stuck | Take a happy path step, negate it ("what if this fails?") |
| **Amplification** | Deep exploration | Take existing situation, amplify one parameter to extreme |
| **Persona shift** | Coverage gaps | Same scenario, different actor (admin vs user vs attacker) |
| **Temporal shift** | After basics covered | Same scenario at different times (peak load, maintenance window, first use) |

**Rules:**
- ONE situation per iteration (atomic — evaluate before generating more)
- Must be concrete and specific (not vague "something goes wrong")
- Must include at least one verifiable expected outcome

## Phase 4: Classify — Evaluate & Deduplicate

Before keeping a generated situation, classify it:

| Classification | Criteria | Action |
|----------------|----------|--------|
| **New** | Not covered by any existing situation | KEEP — add to scenarios |
| **Variant** | Similar to existing but meaningfully different | KEEP — add as sub-scenario |
| **Duplicate** | Already covered by existing situation | DISCARD — log as "duplicate of #N" |
| **Out of scope** | Doesn't match the seed scenario | DISCARD — log as "out of scope" |
| **Low value** | Technically possible but unrealistic | DISCARD — log as "low value" |

**Deduplication check:**
- Compare against ALL previously generated situations
- Check for semantic similarity, not just text matching
- A situation with different actors but identical flow is a variant, not new

## Phase 5: Expand — Edge Cases & Stress Tests

For each KEPT situation, derive additional scenarios:

**Expansion techniques:**

| Technique | Description | Example |
|-----------|-------------|---------|
| **What-if** | Change one variable | "What if the network drops mid-transaction?" |
| **Boundary** | Push values to limits | "What if quantity = 0? -1? MAX_INT?" |
| **Interruption** | Inject failure mid-flow | "What if power loss occurs at step 3?" |
| **Ordering** | Change sequence | "What if step 2 happens before step 1?" |
| **Missing data** | Remove expected input | "What if the required field is null?" |
| **Stale data** | Use outdated information | "What if the cached price changed 5 minutes ago?" |

**For each expansion:**
- Generate as sub-scenario under the parent situation
- Mark with severity (Critical/High/Medium/Low)
- Note if it maps to a known bug pattern

## Phase 6: Log — Record Everything

**Append to scenario-results.tsv:**
```tsv
iteration	dimension	classification	severity	title	description	parent
1	happy_path	new	-	Successful checkout	User completes standard checkout flow	-
2	error_path	new	HIGH	Payment declined	Card rejected during checkout	-
3	edge_case	new	MEDIUM	Empty cart checkout	User clicks checkout with 0 items	-
4	edge_case	variant	LOW	Single-item cart	User checks out with exactly 1 item	#1
5	concurrent	new	CRITICAL	Double-submit	User clicks pay twice rapidly	-
6	abuse	new	CRITICAL	Price manipulation	User modifies price client-side	-
```

**Every 5 iterations, print progress:**
```
=== Scenario Progress (iteration 15) ===
Scenarios generated: 12 (8 new, 3 variants, 1 discarded)
Dimensions covered: 7/12 (58%)
Edge cases found: 18
Severity breakdown: 2 Critical, 4 High, 8 Medium, 4 Low
Coverage gaps: scale, temporal, recovery — unexplored
```

## Phase 7: Repeat — Next Exploration Vector

**Prioritization for next iteration:**
1. Unexplored dimensions with highest expected severity
2. Combinations of dimensions not yet tested together
3. Expansions of high-severity situations
4. Domain-specific patterns not yet covered
5. Coverage gaps identified in progress summary

**When to stop (unbounded mode):**
- Never stop automatically — user interrupts
- Print "diminishing returns" warning after 5 iterations with no new unique situations

**When to stop (bounded mode):**
- After N iterations, print final summary and stop

## Flags

| Flag | Purpose |
|------|---------|
| `--domain <type>` | Set domain context (software, product, business, security, marketing) |
| `--depth <level>` | Set exploration depth (shallow=10, standard=25, deep=50+) |
| `--scope <glob>` | Limit to specific files/features for codebase-aware generation |
| `--format <type>` | Output format (use-cases, user-stories, test-scenarios, threat-scenarios, mixed) |
| `--focus <area>` | Prioritize specific dimension (edge-cases, failures, security, scale) |
| `--chain <targets>` | Chain to downstream tool(s) after completion. Comma-separated for multi-chain. Spaces after commas tolerated. |

## Composite Metric

For bounded loops, scenario exploration thoroughness:

```
scenario_score = scenarios_generated * 10
              + edge_cases_found * 15
              + (dimensions_covered / total_dimensions) * 30
              + unique_actors_explored * 5
              + (high_severity_found * 3)
```

Higher = more thorough. Incentivizes breadth (cover dimensions) AND depth (find edge cases).

### Chain Conversion

#### `--chain debug`

Each high-risk scenario (Critical or High severity) becomes a hypothesis for the debug investigation loop. Scope is derived from the files mentioned in or related to each scenario.

```
$autoresearch debug
Scope: {files from scenario scope or codebase map}
Symptom: scenarios predict high-risk failure modes — {N} hypotheses queued
Hypotheses:
  H-01 [CRITICAL] {scenario title} — {trigger description}
  H-02 [HIGH] {scenario title} — {trigger description}
```

#### `--chain fix`

Edge case failures and failure mode scenarios become fix targets sorted by severity.

```
$autoresearch fix
Target: {top Critical/High scenario title}
Scope: {file paths related to failure scenarios}
```

#### `--chain security`

Threat scenarios and abuse-dimension findings feed the security audit focus areas.

```
$autoresearch security
Scope: {files from abuse/permission/data_variation scenarios}
Focus: threat scenarios from exploration: {comma-separated scenario titles}
```

#### `--chain predict`

Scenarios become the goal for multi-persona swarm impact analysis — "what broader impact do these scenarios predict."

```
$autoresearch predict
Scope: {file paths from scenario scope}
Goal: predict broader impact of identified failure scenarios and edge cases
```

#### `--chain plan`

Scenario findings become requirements for implementation planning — gaps and failure modes become planned features or hardening tasks.

```
$autoresearch plan
Goal: address failure modes and edge cases uncovered by scenario exploration
Source: scenario/{slug}/summary.md
```

#### `--chain learn`

The full scenario tree is documented for codebase learning — future features can reference coverage gaps.

```
$autoresearch learn
Topic: scenario coverage, edge cases, and failure modes
Source: scenario/{slug}/scenarios.md
```

#### `--chain reason`

Complex scenarios with no clear resolution become tasks for adversarial refinement.

```
$autoresearch reason
Task: determine best handling strategy for complex/unresolved scenarios
Evidence: scenario/{slug}/edge-cases.md
```

#### `--chain ship`

Scenario coverage becomes a ship readiness gate — Critical failures block, High failures warn.

```
$autoresearch ship
Gate: {FAIL if any unaddressed Critical scenarios, WARN if High scenarios unresolved}
Blockers: {count of unaddressed Critical scenarios}
```

#### `--chain probe`

Scenarios reveal requirement gaps — situations the system can't handle expose missing or ambiguous requirements.

```
$autoresearch probe
Topic: requirement gaps revealed by scenario exploration
Source: scenario/{slug}/summary.md
```

### Multi-Chain Execution

`--chain debug,fix,ship` executes sequentially:

1. Write `handoff.json` after scenario exploration completes
2. Launch `debug` with chain conversion above
3. After `debug` completes, convert debug findings + `handoff.json` → `fix` targets
4. After `fix` completes, convert fix session results → `ship` gate
5. Each stage's output feeds the next via updated `handoff.json`

**Empirical evidence rule:** Downstream loop results ALWAYS override upstream scenario consensus. If debug disproves a scenario's predicted failure mode, the empirical finding wins — update the scenario report with `DISPROVEN by debug loop`.

## Output Directory

Creates `scenario/{YYMMDD}-{HHMM}-{scenario-slug}/` with:
- `scenarios.md` — all generated scenarios grouped by dimension, with full situation format
- `use-cases.md` — formal use cases (Given/When/Then) derived from scenarios
- `edge-cases.md` — edge cases and failure modes with severity ratings
- `scenario-results.tsv` — iteration log
- `summary.md` — executive summary with coverage matrix, dimension heatmap, recommendations

## Domain-Specific Templates

When a domain is specified (or detected), load domain-specific dimension priorities:

### Software/API Domain
**Priority dimensions:** error_path, edge_case, concurrent, integration, data_variation
**Default format:** test-scenarios
**Extra checks:** API contract violations, backward compatibility, idempotency

### Product/UX Domain
**Priority dimensions:** happy_path, error_path, permission, temporal, state_transition
**Default format:** user-stories
**Extra checks:** Accessibility, mobile responsiveness, offline behavior, onboarding

### Business/Process Domain
**Priority dimensions:** happy_path, error_path, permission, temporal, recovery
**Default format:** use-cases
**Extra checks:** Approval chains, SLA violations, audit trail, escalation paths

### Security/Compliance Domain
**Priority dimensions:** abuse, permission, data_variation, integration, concurrent
**Default format:** threat-scenarios
**Extra checks:** OWASP Top 10 mapping, data exposure, privilege escalation, injection vectors

### Marketing/Sales Domain
**Priority dimensions:** happy_path, data_variation, temporal, scale, state_transition
**Default format:** user-stories
**Extra checks:** A/B test interference, attribution edge cases, funnel drop-offs, localization

## Chaining Patterns

```bash
# Explore scenarios, then hunt for bugs in those areas
$autoresearch scenario
Iterations: 25

$autoresearch debug --scope src/checkout/**
Symptom: edge cases from scenario exploration

# Explore, then security audit the weak spots
$autoresearch scenario --domain security
Iterations: 15

$autoresearch security --scope src/auth/**

# Generate test scenarios, then use them to write tests
$autoresearch scenario --format test-scenarios --domain software
Iterations: 20

# Output can feed into test generation workflows
```

## What NOT to Do — Anti-Patterns

| Anti-Pattern | Why It Fails |
|---|---|
| **Generate 50 happy paths** | No value — one happy path reveals the baseline, then explore what breaks |
| **Stay in one dimension** | Missing coverage — force dimension rotation after 3 consecutive same-dimension iterations |
| **Vague situations** | "Something bad happens" is not a scenario — require specific trigger, flow, and outcome |
| **Skip classification** | Duplicates waste iterations and inflate metrics without adding value |
| **Ignore domain context** | A security scenario needs threat-focused dimensions, not UX-focused ones |
| **Abstract without concrete** | "User might experience issues" — name the issue, the trigger, and the impact |