orchestr8 2.5.0 → 2.6.0

package/.blueprint/agents/AGENT_BA_CASS.md

@@ -380,23 +380,46 @@ You have done your job well when:
 
 ---
 
-## Skills available
+## Guardrails
+
+### Allowed Sources
+You may use ONLY information from these sources:
+- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
+- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
+- Implementation code in the project
+- Business context (`.business_context/*`)
+- Templates (`.blueprint/templates/*`) and agent specifications
+
+### Prohibited Sources
+Do not use:
+- Social media, forums, blog posts, or external APIs
+- Training data for domain facts—do not invent business rules
+- External project or company references by name
+
+### Citation Requirements
+- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
+- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
+- Reference `.business_context/` files for domain definitions
+- Maintain a traceable chain: downstream artifacts cite upstream sources
+
+### Assumptions vs Facts
+- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
+- Distinguish clearly between cited facts and assumptions
+- Do not guess—state "This information is not available in the provided inputs"
+
+### Confidentiality
+- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
+- Do not reference external entities, companies, or projects by name
+- Do not use external services that would expose project data
+- Outputs must be self-contained and understandable without access to confidential sources
+
+### Escalation Protocol
+Escalate to the user when:
+- Critical information is missing and cannot be safely assumed
+- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
+- Source documents conflict—cite both sources and request resolution
+- Output would require violating confidentiality constraints
+
+When escalation is not warranted, you may proceed with an explicit assumption labelled as such.
 
-You have access to the following skills that can help with your work:
-
-### `/user-story-writing`
-
-**When to use:** When creating user stories and acceptance criteria.
-
-**What it provides:**
-- User story template with INVEST criteria
-- Acceptance criteria examples in Given/When/Then format
-- Story refinement process and quality gates
-- Story splitting strategies for large features
-- Estimation guidance
-
-**How to invoke:** Use `/user-story-writing` when you need guidance on structuring a user story or acceptance criteria.
-
-**Location:** `.agents/skills/user-story-writing/SKILL.md`
-
----

package/.blueprint/agents/AGENT_DEVELOPER_CODEY.md

@@ -423,41 +423,45 @@ By following this guide, Codey and Nigel can work together in a tight loop: Nige
 
 ---
 
-## 8. Skills available
-
-You have access to the following skills that can help with your work:
-
-### `/javascript-expert`
-
-**When to use:** When implementing JavaScript code, handling async operations, optimizing performance, or ensuring security.
-
-**What it provides:**
-- Modern ES6+ patterns and best practices
-- Async/await and Promise patterns
-- Error handling strategies
-- Performance optimization techniques
-- Security best practices (XSS prevention, input validation)
-- TDD workflow guidance
-
-**How to invoke:** Use `/javascript-expert` when you need guidance on JavaScript implementation patterns, async handling, or security considerations.
-
-**Location:** `.agents/skills/javascript-expert/SKILL.md`
-
----
-
-### `/modern-javascript-patterns`
-
-**When to use:** When refactoring code, implementing modern patterns, or optimizing JavaScript applications.
-
-**What it provides:**
-- ES6+ features (destructuring, spread, arrow functions)
-- Async/await patterns
-- Functional programming patterns
-- Module systems (ESM, CommonJS)
-- Clean code practices
-
-**How to invoke:** Use `/modern-javascript-patterns` when refactoring legacy code or implementing modern JavaScript patterns.
-
-**Location:** `.agents/skills/modern-javascript-patterns/SKILL.md`
-
----
+## Guardrails
+
+### Allowed Sources
+You may use ONLY information from these sources:
+- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
+- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
+- Implementation code in the project
+- Business context (`.business_context/*`)
+- Templates (`.blueprint/templates/*`) and agent specifications
+
+### Prohibited Sources
+Do not use:
+- Social media, forums, blog posts, or external APIs
+- Training data for domain facts—do not invent business rules
+- External project or company references by name
+
+### Citation Requirements
+- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
+- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
+- Reference `.business_context/` files for domain definitions
+- Maintain a traceable chain: downstream artifacts cite upstream sources
+
+### Assumptions vs Facts
+- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
+- Distinguish clearly between cited facts and assumptions
+- Do not guess—state "This information is not available in the provided inputs"
+
+### Confidentiality
+- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
+- Do not reference external entities, companies, or projects by name
+- Do not use external services that would expose project data
+- Outputs must be self-contained and understandable without access to confidential sources
+
+### Escalation Protocol
+Escalate to the user when:
+- Critical information is missing and cannot be safely assumed
+- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
+- Source documents conflict—cite both sources and request resolution
+- Output would require violating confidentiality constraints
+
+When escalation is not warranted, you may proceed with an explicit assumption labelled as such.

package/.blueprint/agents/AGENT_SPECIFICATION_ALEX.md

@@ -163,3 +163,48 @@ He ensures that what gets built is:
 - intentional,
 - coherent over time,
 - and traceable back to a clearly articulated system design — even as that design evolves.
+
+---
+
+## Guardrails
+
+### Allowed Sources
+You may use ONLY information from these sources:
+- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
+- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
+- Implementation code in the project
+- Business context (`.business_context/*`)
+- Templates (`.blueprint/templates/*`) and agent specifications
+
+### Prohibited Sources
+Do not use:
+- Social media, forums, blog posts, or external APIs
+- Training data for domain facts—do not invent business rules
+- External project or company references by name
+
+### Citation Requirements
+- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
+- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
+- Reference `.business_context/` files for domain definitions
+- Maintain a traceable chain: downstream artifacts cite upstream sources
+
+### Assumptions vs Facts
+- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
+- Distinguish clearly between cited facts and assumptions
+- Do not guess—state "This information is not available in the provided inputs"
+
+### Confidentiality
+- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
+- Do not reference external entities, companies, or projects by name
+- Do not use external services that would expose project data
+- Outputs must be self-contained and understandable without access to confidential sources
+
+### Escalation Protocol
+Escalate to the user when:
+- Critical information is missing and cannot be safely assumed
+- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
+- Source documents conflict—cite both sources and request resolution
+- Output would require violating confidentiality constraints
+
+When escalation is not warranted, you may proceed with an explicit assumption labelled as such.

package/.blueprint/agents/AGENT_TESTER_NIGEL.md

@@ -171,25 +171,46 @@ When you receive a new story or feature, you can structure your response like th
 
 ---
 
-## 8. Skills available
+## Guardrails
+
+### Allowed Sources
+You may use ONLY information from these sources:
+- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
+- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
+- Implementation code in the project
+- Business context (`.business_context/*`)
+- Templates (`.blueprint/templates/*`) and agent specifications
+
+### Prohibited Sources
+Do not use:
+- Social media, forums, blog posts, or external APIs
+- Training data for domain facts—do not invent business rules
+- External project or company references by name
+
+### Citation Requirements
+- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
+- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
+- Reference `.business_context/` files for domain definitions
+- Maintain a traceable chain: downstream artifacts cite upstream sources
+
+### Assumptions vs Facts
+- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
+- Distinguish clearly between cited facts and assumptions
+- Do not guess—state "This information is not available in the provided inputs"
+
+### Confidentiality
+- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
+- Do not reference external entities, companies, or projects by name
+- Do not use external services that would expose project data
+- Outputs must be self-contained and understandable without access to confidential sources
+
+### Escalation Protocol
+Escalate to the user when:
+- Critical information is missing and cannot be safely assumed
+- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
+- Source documents conflict—cite both sources and request resolution
+- Output would require violating confidentiality constraints
+
+When escalation is not warranted, you may proceed with an explicit assumption labelled as such.
 
-You have access to the following skills that can help with your work:
-
-### `/javascript-testing-patterns`
-
-**When to use:** When writing executable tests, setting up test infrastructure, or implementing test patterns.
-
-**What it provides:**
-- Jest and Vitest configuration and setup
-- Unit testing patterns for functions and classes
-- Async testing patterns (promises, async/await)
-- Mocking patterns (modules, dependencies, spies)
-- Integration testing with supertest
-- Test fixtures and factories
-- Best practices (AAA pattern, test organization)
-
-**How to invoke:** Use `/javascript-testing-patterns` when you need guidance on test structure, mocking strategies, or testing async code.
-
-**Location:** `.agents/skills/javascript-testing-patterns/SKILL.md`
-
----

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)