orchestr8 2.4.0 → 2.6.0

package/.blueprint/features/feature_adaptive-retry/FEATURE_SPEC.md

@@ -0,0 +1,239 @@
+# Feature Specification — Adaptive Retry
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+The orchestr8 pipeline currently offers simple retry/skip/abort options when an agent fails (per SKILL.md:Error Handling). This feature introduces **intelligent retry logic** that learns from failure history to make smarter decisions about how to handle failures.
+
+- **Problem being addressed:** Pipeline failures are handled uniformly regardless of context. Repeated failures at the same stage waste time with identical retry attempts.
+- **User need:** Developers want the pipeline to adapt its retry approach based on what has historically worked, reducing manual intervention and improving success rates.
+- **System alignment:** Per SYSTEM_SPEC.md:Section 6 (High-Level Lifecycle), recovery from failure is already supported. This feature enhances that capability by making recovery **adaptive** rather than static.
+
+---
+
+## 2. Scope
+### In Scope
+- Retry configuration file management (`.claude/retry-config.json`)
+- Failure pattern detection using existing history module (`src/history.js`)
+- Strategy selection logic based on failure rates and attempt counts
+- CLI commands for viewing and managing retry configuration
+- Integration with pipeline error handling (advisory, not replacing user choice)
+
+### Out of Scope
+- Automatic prompt rewriting (strategies describe *what* to do; agents execute)
+- Modifications to agent specifications or core pipeline orchestration
+- Machine learning or model-based prediction (rule-based only)
+- Cross-feature failure correlation (each feature is handled independently)
+
+---
+
+## 3. Actors Involved
+
+### Human User
+- Can view current retry configuration via CLI
+- Can modify thresholds and enabled strategies
+- Can reset configuration to defaults
+- Retains final decision authority on retry/skip/abort during pipeline execution
+
+### Pipeline Orchestrator (SKILL.md implementation)
+- Queries retry module when an agent fails
+- Receives recommended strategy and displays it to user
+- Applies strategy modifications to agent prompts when user accepts retry
+
+### History Module (src/history.js)
+- Provides failure data for strategy calculation
+- Is read-only from this feature's perspective
+
+### Insights Module (src/insights.js)
+- Provides `analyzeFailures()` which calculates failure rates by stage
+- Is read-only from this feature's perspective
+
+---
+
+## 4. Behaviour Overview
+
+### Happy Path: Strategy-Guided Retry
+1. Agent fails during pipeline execution
+2. Retry module queries history for recent failures at this stage
+3. Module calculates failure rate over recent window (default: last 10 runs)
+4. If failure rate > threshold (20%), recommend alternative strategy; otherwise recommend simple retry
+5. Display recommendation to user: "Recommended strategy: {strategy}. Retry with this approach? (y/n/abort)"
+6. If user accepts, modify agent prompt per strategy and retry
+7. Record outcome in history
+
+### Alternative: First Failure
+- If this is the first recorded failure for a stage (no history), default to simple retry
+- No prompt modification; standard retry behaviour
+
+### Alternative: Max Retries Exceeded
+- After `maxRetries` (default 3) attempts at same stage for same feature, warn user
+- User can still choose to retry, but recommendation becomes "abort or skip"
+
+### Alternative: User Declines Strategy
+- User can override recommendation and choose different action (retry/skip/abort)
+- System respects user choice; recommendation is advisory only
+
+---
+
+## 5. State & Lifecycle Interactions
+
+### States Affected
+Per SYSTEM_SPEC.md:Section 6, pipeline states are: INIT, ALEX, CASS, NIGEL, CODEY_PLAN, CODEY_IMPLEMENT, COMMIT, COMPLETE, PAUSED, RESUME.
+
+This feature operates within the **transition from any agent state to FAILED**:
+- On agent error, before prompting user, retry module is consulted
+- State remains in current stage during retry attempts
+- State transitions to FAILED only on abort (unchanged from current behaviour)
+
+### Lifecycle Classification
+- **State-constraining:** Does not create new states; constrains how transitions to FAILED are handled
+- **Queue-modifying:** May update `failed` array with additional metadata (strategy attempted, attempt count)
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule 1: Calculate Stage Failure Rate
+- **Description:** Determine how often a specific stage has failed in recent history
+- **Inputs:** Stage name, history entries, window size (default 10)
+- **Outputs:** Failure rate (0.0 to 1.0)
+- **Type:** Deterministic
+
+```
+failureRate = failedRunsAtStage / totalRecentRuns
+```
+
+### Rule 2: Select Retry Strategy
+- **Description:** Choose appropriate strategy based on failure rate and attempt count
+- **Inputs:** Stage name, current attempt number, failure rate, configured strategies
+- **Outputs:** Recommended strategy name
+- **Type:** Deterministic with precedence
+
+```
+if (attemptCount > maxRetries) → "abort-recommended"
+if (failureRate > highFailureThreshold) → alternativeStrategy[stage][attemptCount]
+else → "retry"
+```
+
+### Rule 3: Apply Strategy to Prompt
+- **Description:** Modify agent prompt based on selected strategy
+- **Inputs:** Original prompt, strategy name, stage context
+- **Outputs:** Modified prompt (or original if strategy is "retry")
+- **Type:** Deterministic
+
+Strategy applications:
+| Strategy | Prompt Modification |
+|----------|-------------------|
+| `retry` | No modification |
+| `simplify-prompt` | Add: "Focus on core requirements only. Skip edge cases and optional sections." |
+| `reduce-stories` | Add: "Write only the 2-3 most critical user stories. Defer others to follow-up." |
+| `simplify-tests` | Add: "Write only happy-path tests for each AC. Skip edge cases." |
+| `add-context` | Prepend relevant sections from previous stage outputs |
+| `incremental` | Add: "Implement one test at a time. Stop and report after each." |
+| `rollback` | Execute `git checkout -- .` on implementation files before retry |
+
+### Rule 4: Persist Configuration
+- **Description:** Configuration survives across sessions
+- **Inputs:** User modifications via CLI
+- **Outputs:** Updated `.claude/retry-config.json`
+- **Type:** Deterministic (file write)
+
+---
+
+## 7. Dependencies
+
+### System Components
+- **src/history.js:** `readHistoryFile()` for failure data access (read-only dependency)
+- **src/insights.js:** `analyzeFailures()` for failure pattern analysis (read-only dependency)
+- **src/orchestrator.js:** Queue management; retry module will export functions for orchestrator to call
+- **SKILL.md:** Error handling section will reference retry module recommendations
+
+### File Dependencies
+- **`.claude/pipeline-history.json`:** Must exist with valid structure for accurate analysis
+- **`.claude/retry-config.json`:** Created on first use if not present; gitignored
+
+### Operational Dependencies
+- History module must be functional (feature degrades gracefully if corrupted)
+- File system write access for configuration persistence
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance
+- Strategy calculation should complete in <100ms (simple arithmetic on in-memory data)
+- No blocking I/O during recommendation phase beyond initial history read
+
+### Resilience
+- If history file is corrupted, default to simple retry (no strategy recommendation)
+- If config file is corrupted or missing, use hardcoded defaults
+- All failures in retry module should be caught and logged, not propagated
+
+### Audit/Logging
+- Retry attempts and strategies used should be recorded in history entries
+- New history fields: `retryAttempts`, `strategiesUsed[]`
+
+### Maintainability
+- Strategies should be configurable without code changes
+- New strategies can be added by updating config schema and `applyStrategy()` function
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+- ASSUMPTION: History file format is stable and matches `src/history.js` expectations
+- ASSUMPTION: Pipeline execution is single-threaded; no concurrent retry decisions needed
+- ASSUMPTION: User preference is final; recommendations are advisory only
+- ASSUMPTION: Stage names match exactly between history, insights, and retry module
+
+### Open Questions
+- Should strategy history be factored into recommendations? (e.g., "simplify-prompt worked last time")
+- Should there be a "never retry" option for specific stages?
+- How should retry configuration interact with `--pause-after` flags?
+
+---
+
+## 10. Impact on System Specification
+
+### Reinforces Existing Assumptions
+- Per SYSTEM_SPEC.md:Section 8 (Cross-Cutting Concerns), failure handling already "offers retry, skip, abort"
+- This feature enhances rather than replaces that pattern
+- Per SYSTEM_SPEC.md:Section 7 (Governing Rules), "recovery-safe" queue behaviour is maintained
+
+### Stretches Existing Assumptions
+- History module was designed for reporting/insights; now becomes an active input to pipeline decisions
+- This elevates history from "observability" to "operational dependency"
+
+### No Contradictions Identified
+- Feature operates within existing error handling flow
+- Does not modify agent specifications or pipeline sequence
+- Preserves user authority over final decisions
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+1. **Configuration Management:** User can view, modify, and reset retry configuration
+2. **Strategy Recommendation:** Pipeline recommends retry strategy based on failure history
+3. **Prompt Modification:** Retry strategies modify agent prompts to improve success probability
+4. **History Integration:** Retry decisions are informed by historical failure patterns
+
+### Expected Story Boundaries
+- CLI commands (`retry-config`, `retry-config reset`) as separate story
+- Strategy selection logic as separate story
+- Strategy application (prompt modification) as separate story
+- Graceful degradation (corrupted history/config) as non-functional story or AC within above
+
+### Areas Needing Careful Framing
+- User choice must remain paramount; stories should emphasize "recommendation" not "automation"
+- The "rollback" strategy involves destructive action (`git checkout`); needs explicit user confirmation
+- Incremental strategy changes Codey's execution model; may need coordination with Codey's agent spec
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-02-24 | Initial feature specification | New feature request | Alex |

package/.blueprint/features/feature_adaptive-retry/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,48 @@
+# Implementation Plan - Adaptive Retry
+
+## Summary
+
+This feature adds intelligent retry logic to the orchestr8 pipeline via a new `src/retry.js` module. The module calculates failure rates from history, recommends strategies based on configurable thresholds, and applies prompt modifications when users accept recommended strategies. The implementation integrates with existing `src/history.js` for failure data and provides CLI commands for configuration management.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/retry.js` | Create | Core retry logic: config management, failure rate calculation, strategy recommendation, prompt modification |
+| `src/index.js` | Modify | Export retry module functions |
+| `bin/cli.js` | Modify | Add `retry-config` CLI command with `set` and `reset` subcommands |
+
+## Implementation Steps
+
+1. **Create `src/retry.js` with config management** - Implement `getDefaultConfig()`, `readConfig()`, `writeConfig()`, `resetConfig()` functions for `.claude/retry-config.json`
+
+2. **Add failure rate calculation** - Implement `calculateFailureRate(stage, history, windowSize)` that returns failure rate (0-1) for a stage over the recent window
+
+3. **Add strategy recommendation logic** - Implement `recommendStrategy(stage, attemptCount, failureRate, config)` returning strategy name or "abort-recommended"
+
+4. **Add prompt modification** - Implement `applyStrategy(strategy, originalPrompt)` that returns modified prompt based on strategy
+
+5. **Add graceful degradation** - Wrap all file operations in try/catch; return defaults on corrupted/missing files; log warnings
+
+6. **Add CLI commands to `bin/cli.js`** - Add `retry-config` (view), `retry-config set <key> <value>`, `retry-config reset` commands
+
+7. **Export functions in `src/index.js`** - Export `readConfig`, `writeConfig`, `resetConfig`, `calculateFailureRate`, `recommendStrategy`, `applyStrategy`
+
+8. **Run tests and iterate** - Execute `node --test test/feature_adaptive-retry.test.js` after each step; fix failures
+
+## Key Functions
+
+- `getDefaultConfig()` - Returns hardcoded default configuration object
+- `readConfig()` - Reads `.claude/retry-config.json` or returns defaults if missing/corrupted
+- `writeConfig(config)` - Writes config to file, creates `.claude/` directory if needed
+- `resetConfig()` - Replaces config with defaults
+- `calculateFailureRate(stage, history, windowSize)` - Calculates failure rate for stage over window
+- `recommendStrategy(stage, attemptCount, failureRate, config)` - Returns recommended strategy name
+- `applyStrategy(strategy, originalPrompt)` - Returns modified prompt or original if "retry"
+- `shouldRetry(stage, featureSlug, history, config, attemptCount)` - Orchestrator entry point; returns recommendation object
+
+## Risks/Questions
+
+- **Rollback strategy is destructive**: Per story-prompt-modification.md:AC-6, `git checkout -- .` requires explicit confirmation before execution; implementation must surface this warning
+- **History module dependency**: If `readHistoryFile()` returns `{ error: 'corrupted' }`, module must degrade gracefully per test T-SH-2
+- **Strategy escalation boundary**: When `attemptCount - 1` exceeds strategy list length, use last strategy before switching to "abort-recommended"

package/.blueprint/features/feature_adaptive-retry/story-prompt-modification.md

@@ -0,0 +1,85 @@
+# Story — Prompt Modification
+
+## User Story
+
+As a **developer using orchestr8**, I want the **pipeline to modify agent prompts based on the selected retry strategy** so that **retry attempts have a better chance of success by adjusting the agent's instructions**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 6 (Rule 3), strategies apply specific modifications to agent prompts
+- Per FEATURE_SPEC.md:Section 11 (Areas Needing Careful Framing), the "rollback" strategy requires explicit user confirmation
+- Per FEATURE_SPEC.md:Section 2 (Out of Scope), automatic prompt rewriting is not supported; strategies describe what to do
+- Per SYSTEM_SPEC.md:Section 7 (Agent Rules), agents must not make silent changes
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Apply "simplify-prompt" strategy**
+- Given the user accepts a retry with the "simplify-prompt" strategy,
+- When the agent is re-invoked,
+- Then the prompt is modified to append: "Focus on core requirements only. Skip edge cases and optional sections.",
+- And the modification is visible in the agent's task context.
+
+**AC-2 — Apply "reduce-stories" strategy**
+- Given the user accepts a retry with the "reduce-stories" strategy,
+- When Cass is re-invoked,
+- Then the prompt is modified to append: "Write only the 2-3 most critical user stories. Defer others to follow-up.",
+- And the deferred stories are noted in the summary.
+
+**AC-3 — Apply "simplify-tests" strategy**
+- Given the user accepts a retry with the "simplify-tests" strategy,
+- When Nigel is re-invoked,
+- Then the prompt is modified to append: "Write only happy-path tests for each AC. Skip edge cases.",
+- And edge case tests are explicitly deferred.
+
+**AC-4 — Apply "add-context" strategy**
+- Given the user accepts a retry with the "add-context" strategy,
+- When the agent is re-invoked,
+- Then relevant sections from previous stage outputs are prepended to the prompt,
+- And the source of added context is indicated (e.g., "Context from FEATURE_SPEC.md:Section 4").
+
+**AC-5 — Apply "incremental" strategy**
+- Given the user accepts a retry with the "incremental" strategy,
+- When Codey is re-invoked,
+- Then the prompt is modified to append: "Implement one test at a time. Stop and report after each.",
+- And each implementation step produces a discrete output before continuing.
+
+**AC-6 — Apply "rollback" strategy with confirmation**
+- Given the user accepts a retry with the "rollback" strategy,
+- When the user confirms the destructive action,
+- Then `git checkout -- .` is executed on implementation files before retry,
+- And a confirmation prompt warns: "This will discard uncommitted changes to implementation files. Proceed? (y/n)".
+
+**AC-7 — No modification for "retry" strategy**
+- Given the user accepts a simple "retry" (no strategy modification),
+- When the agent is re-invoked,
+- Then the original prompt is used without any modification,
+- And the retry proceeds identically to the first attempt.
+
+---
+
+## Strategy Reference Table
+
+Per FEATURE_SPEC.md:Section 6 (Rule 3):
+
+| Strategy | Modification Applied |
+|----------|---------------------|
+| `retry` | No modification |
+| `simplify-prompt` | Append: "Focus on core requirements only. Skip edge cases and optional sections." |
+| `reduce-stories` | Append: "Write only the 2-3 most critical user stories. Defer others to follow-up." |
+| `simplify-tests` | Append: "Write only happy-path tests for each AC. Skip edge cases." |
+| `add-context` | Prepend relevant sections from previous stage outputs |
+| `incremental` | Append: "Implement one test at a time. Stop and report after each." |
+| `rollback` | Execute `git checkout -- .` on implementation files before retry |
+
+---
+
+## Out of Scope
+
+- Automatic prompt rewriting based on error analysis (per FEATURE_SPEC.md:Section 2)
+- Custom user-defined prompt modifications (strategies are predefined)
+- Modifying agent specifications themselves (per FEATURE_SPEC.md:Section 2)
+- Combining multiple strategies in a single retry (one strategy per attempt)

package/.blueprint/features/feature_adaptive-retry/story-retry-config.md

@@ -0,0 +1,89 @@
+# Story — Retry Configuration Management
+
+## User Story
+
+As a **developer using orchestr8**, I want to **view, modify, and reset retry configuration** so that **I can customize how the pipeline handles failures based on my project's needs**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 2, retry configuration is managed via `.claude/retry-config.json`
+- Per FEATURE_SPEC.md:Section 3 (Actors), users retain final decision authority and can modify thresholds
+- Per FEATURE_SPEC.md:Section 11 (Handover), this story covers CLI commands for `retry-config` and `retry-config reset`
+- Configuration file is gitignored (per FEATURE_SPEC.md:Section 7)
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — View current configuration**
+- Given the retry configuration file exists at `.claude/retry-config.json`,
+- When I run `orchestr8 retry-config`,
+- Then the current configuration is displayed in a readable format showing thresholds, window size, max retries, and enabled strategies.
+
+**AC-2 — View defaults when no configuration exists**
+- Given no retry configuration file exists,
+- When I run `orchestr8 retry-config`,
+- Then the hardcoded default configuration is displayed,
+- And a message indicates "Using default configuration (no config file found)".
+
+**AC-3 — Modify configuration value**
+- Given I run `orchestr8 retry-config set <key> <value>` (e.g., `orchestr8 retry-config set maxRetries 5`),
+- When the key is valid and value is of correct type,
+- Then the configuration file is updated with the new value,
+- And a confirmation message shows the updated setting.
+
+**AC-4 — Reject invalid configuration key**
+- Given I run `orchestr8 retry-config set <invalidKey> <value>`,
+- When the key is not recognized,
+- Then an error message is displayed listing valid configuration keys,
+- And no file modification occurs.
+
+**AC-5 — Reset configuration to defaults**
+- Given the retry configuration file exists with custom values,
+- When I run `orchestr8 retry-config reset`,
+- Then the configuration file is replaced with default values,
+- And a confirmation message indicates "Retry configuration reset to defaults".
+
+**AC-6 — Create configuration file on first modification**
+- Given no retry configuration file exists,
+- When I run `orchestr8 retry-config set <key> <value>`,
+- Then the configuration file is created with default values plus the specified modification,
+- And the file is created in `.claude/retry-config.json`.
+
+**AC-7 — Handle corrupted configuration gracefully**
+- Given the retry configuration file exists but contains invalid JSON,
+- When I run `orchestr8 retry-config`,
+- Then an error message is displayed indicating the file is corrupted,
+- And a suggestion to run `orchestr8 retry-config reset` is shown.
+
+---
+
+## Configuration Schema
+
+Per FEATURE_SPEC.md:Section 6 (Rules), default configuration includes:
+
+```json
+{
+  "maxRetries": 3,
+  "windowSize": 10,
+  "highFailureThreshold": 0.2,
+  "strategies": {
+    "alex": ["simplify-prompt", "add-context"],
+    "cass": ["reduce-stories", "simplify-prompt"],
+    "nigel": ["simplify-tests", "add-context"],
+    "codey-plan": ["add-context", "simplify-prompt"],
+    "codey-implement": ["incremental", "rollback"]
+  }
+}
+```
+
+---
+
+## Out of Scope
+
+- Modifying strategy definitions themselves (strategies are code, not config)
+- Per-feature configuration overrides (configuration is global)
+- Configuration UI/interactive editor (CLI only)
+- Validating strategy effectiveness (config is just data; strategy logic is separate)

package/.blueprint/features/feature_adaptive-retry/story-should-retry.md

@@ -0,0 +1,98 @@
+# Story — Should Retry Decision Logic
+
+## User Story
+
+As a **developer using orchestr8**, I want the **pipeline to intelligently decide whether to recommend retrying** so that **I receive useful guidance based on attempt count, failure history, and system state**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 4 (Happy Path), retry module is consulted when an agent fails
+- Per FEATURE_SPEC.md:Section 5 (State & Lifecycle), this operates within the transition from any agent state to FAILED
+- Per FEATURE_SPEC.md:Section 8 (Resilience), graceful degradation is required when history/config is corrupted
+- Per SYSTEM_SPEC.md:Section 8 (Failure Handling), each agent spawn currently offers retry, skip, abort
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Consult retry module on agent failure**
+- Given an agent fails during pipeline execution,
+- When the error handling flow is triggered,
+- Then the retry module is consulted before displaying options to the user,
+- And the module returns a recommendation (strategy name or "abort-recommended").
+
+**AC-2 — Record retry attempts in history**
+- Given the user chooses to retry (with or without strategy),
+- When the retry completes (success or failure),
+- Then the outcome is recorded in `.claude/pipeline-history.json`,
+- And the record includes: `retryAttempts` count and `strategiesUsed[]` array.
+
+**AC-3 — Track attempt count per stage per feature**
+- Given an agent fails and user retries,
+- When tracking retry state,
+- Then the attempt count is incremented for the current stage and feature combination,
+- And the count persists across retries within the same pipeline run.
+
+**AC-4 — Degrade gracefully with corrupted history**
+- Given the history file at `.claude/pipeline-history.json` is corrupted or missing,
+- When the retry module is consulted,
+- Then the module defaults to simple retry recommendation,
+- And a warning is logged: "History file unavailable; defaulting to simple retry".
+
+**AC-5 — Degrade gracefully with corrupted configuration**
+- Given the configuration file at `.claude/retry-config.json` is corrupted or missing,
+- When the retry module calculates strategy,
+- Then hardcoded defaults are used for thresholds and strategies,
+- And a warning is logged: "Config file unavailable; using default settings".
+
+**AC-6 — Preserve state transitions**
+- Given a retry is in progress,
+- When the retry attempt completes successfully,
+- Then the pipeline continues to the next stage as normal,
+- And the state transitions per SYSTEM_SPEC.md:Section 6 (e.g., CASS to NIGEL).
+
+**AC-7 — Support abort without retry**
+- Given the user is shown retry options,
+- When the user selects "abort",
+- Then the feature is moved to the failed list in the queue,
+- And no retry is attempted,
+- And the failure is recorded with reason "user-aborted".
+
+---
+
+## Integration Points
+
+Per FEATURE_SPEC.md:Section 7 (Dependencies):
+
+- **src/history.js:** `readHistoryFile()` provides failure data
+- **src/insights.js:** `analyzeFailures()` calculates failure rates by stage
+- **src/orchestrator.js:** Queue management receives retry module functions
+- **SKILL.md:** Error handling section references retry recommendations
+
+---
+
+## History Record Schema
+
+Per FEATURE_SPEC.md:Section 8 (Audit/Logging), new fields in history entries:
+
+```json
+{
+  "featureSlug": "adaptive-retry",
+  "stage": "cass",
+  "outcome": "success",
+  "timestamp": "2026-02-24T10:30:00Z",
+  "retryAttempts": 2,
+  "strategiesUsed": ["retry", "reduce-stories"]
+}
+```
+
+---
+
+## Out of Scope
+
+- Automatic retry without user prompt (user always has final say)
+- Retry across different features (each feature's retry state is independent)
+- Persistent retry state across pipeline invocations (state is per-run only; history is persistent)
+- Batch retry of multiple failed features (single-feature focus per SYSTEM_SPEC.md:Section 10)

package/.blueprint/features/feature_adaptive-retry/story-strategy-recommendation.md

@@ -0,0 +1,85 @@
+# Story — Strategy Recommendation
+
+## User Story
+
+As a **developer using orchestr8**, I want the **pipeline to recommend a retry strategy based on failure history** so that **I can make informed decisions about how to handle failures more effectively**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 4 (Behaviour Overview), recommendations are advisory only; user retains final choice
+- Per FEATURE_SPEC.md:Section 6 (Rule 1 & Rule 2), strategy selection is based on failure rate calculation
+- Per FEATURE_SPEC.md:Section 3 (Actors), the History Module provides failure data (read-only)
+- Per FEATURE_SPEC.md:Section 7 (Dependencies), uses `src/history.js` and `src/insights.js`
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Calculate failure rate from history**
+- Given an agent fails during pipeline execution,
+- When the retry module is consulted,
+- Then the failure rate is calculated as `failedRunsAtStage / totalRecentRuns` over the configured window (default 10 runs),
+- And the calculation uses data from `.claude/pipeline-history.json`.
+
+**AC-2 — Recommend simple retry for low failure rate**
+- Given the calculated failure rate is at or below the threshold (default 20%),
+- When displaying retry options to the user,
+- Then the recommendation is "retry" with no prompt modification suggested,
+- And the message format is: "Recommended: Simple retry. Retry? (y/n/skip/abort)".
+
+**AC-3 — Recommend alternative strategy for high failure rate**
+- Given the calculated failure rate exceeds the threshold (default 20%),
+- When displaying retry options to the user,
+- Then an alternative strategy from the stage's strategy list is recommended,
+- And the message format is: "Recommended strategy: {strategyName}. Retry with this approach? (y/apply/skip/abort)".
+
+**AC-4 — Escalate strategy on subsequent attempts**
+- Given a retry attempt has already been made at the current stage,
+- When another failure occurs and the user is prompted again,
+- Then the next strategy in the stage's strategy list is recommended,
+- And if all strategies have been exhausted, "abort-recommended" is suggested.
+
+**AC-5 — Default to simple retry with no history**
+- Given this is the first recorded run or no history exists for the current stage,
+- When an agent fails,
+- Then the recommendation is "retry" (simple retry),
+- And a note indicates "No failure history for this stage; defaulting to simple retry".
+
+**AC-6 — Warn when max retries exceeded**
+- Given the current attempt count exceeds `maxRetries` (default 3) for the same feature and stage,
+- When displaying options to the user,
+- Then the recommendation is "abort-recommended" or "skip-recommended",
+- And a warning is displayed: "Max retries ({count}) exceeded for {stage}. Consider skipping or aborting."
+
+**AC-7 — Display recommendation without forcing choice**
+- Given a strategy recommendation is displayed,
+- When the user selects a different option (e.g., chooses "skip" when "retry" was recommended),
+- Then the user's choice is respected,
+- And no error or warning is shown for overriding the recommendation.
+
+---
+
+## Session State
+
+During pipeline execution, retry state is tracked:
+
+```js
+retryState = {
+  stage: 'cass',
+  featureSlug: 'adaptive-retry',
+  attemptCount: 2,
+  strategiesUsed: ['retry', 'reduce-stories'],
+  failureRate: 0.3
+}
+```
+
+---
+
+## Out of Scope
+
+- Machine learning or predictive models for strategy selection (per FEATURE_SPEC.md:Section 2)
+- Cross-feature failure correlation (per FEATURE_SPEC.md:Section 2)
+- Automatic retry without user confirmation (user choice is paramount)
+- Modifying the agent prompts (that is story-prompt-modification)