olympus-ai 4.5.13 → 4.5.14

package/resources/rules/common/error-handling.md

@@ -1,430 +1,430 @@
-# Error Handling and Recovery Procedures
-
-## General Error Handling Principles
-
-### When Errors Occur
-1. **Identify the error**: Clearly state what went wrong
-2. **Assess impact**: Determine if the error is blocking or can be worked around
-3. **Communicate**: Inform the user about the error and options
-4. **Offer solutions**: Provide clear steps to resolve or work around the error
-5. **Document**: Log the error and resolution in `audit.md`
-
-### Error Severity Levels
-
-**Critical**: Workflow cannot continue
-- Missing required files or artifacts
-- Invalid user input that cannot be processed
-- System errors preventing file operations
-
-**High**: Phase cannot complete as planned
-- Incomplete answers to required questions
-- Contradictory user responses
-- Missing dependencies from prior phases
-
-**Medium**: Phase can continue with workarounds
-- Optional artifacts missing
-- Non-critical validation failures
-- Partial completion possible
-
-**Low**: Minor issues that don't block progress
-- Formatting inconsistencies
-- Optional information missing
-- Non-blocking warnings
-
-## Phase-Specific Error Handling
-
-### Context Assessment Errors
-
-**Error**: Cannot read workspace files
-- **Cause**: Permission issues, missing directories
-- **Solution**: Ask user to verify workspace path and permissions
-- **Workaround**: Proceed with user-provided information only
-
-**Error**: Existing `aidlc-state.md` is corrupted
-- **Cause**: Manual editing, incomplete previous run
-- **Solution**: Ask user if they want to start fresh or attempt recovery
-- **Recovery**: Create backup, start new state file
-
-**Error**: Cannot determine required phases
-- **Cause**: Insufficient information from user
-- **Solution**: Ask clarifying questions about intent and scope
-- **Workaround**: Default to comprehensive execution plan
-
-### Requirements Assessment Errors
-
-**Error**: User provides contradictory requirements
-- **Cause**: Unclear understanding, changing needs
-- **Solution**: Create follow-up questions to resolve contradictions
-- **Do Not Proceed**: Until contradictions are resolved
-
-**Error**: Requirements document cannot be converted
-- **Cause**: Unsupported format, corrupted file
-- **Solution**: Ask user to provide requirements in supported format
-- **Workaround**: Work with user's verbal description
-
-**Error**: Incomplete answers to verification questions
-- **Cause**: User skipped questions, unclear what to answer
-- **Solution**: Highlight unanswered questions, provide examples
-- **Do Not Proceed**: Until all required questions are answered
-
-### Story Development Errors
-
-**Error**: Cannot map requirements to stories
-- **Cause**: Requirements too vague, missing functional details
-- **Solution**: Return to Requirements Assessment for clarification
-- **Workaround**: Create stories based on available information, mark as incomplete
-
-**Error**: User provides ambiguous story planning answers
-- **Cause**: Unclear options, complex decision
-- **Solution**: Add follow-up questions with specific examples
-- **Do Not Proceed**: Until ambiguities are resolved
-
-**Error**: Story generation plan has uncompleted steps
-- **Cause**: Execution interrupted, steps skipped
-- **Solution**: Resume from first uncompleted step
-- **Recovery**: Review completed steps, continue from checkpoint
-
-### Application Design Errors
-
-**Error**: Architectural decision is unclear or contradictory
-- **Cause**: Ambiguous answers, conflicting requirements
-- **Solution**: Add follow-up questions to clarify decision
-- **Do Not Proceed**: Until decision is clear and documented
-
-**Error**: Cannot determine number of services/units
-- **Cause**: Insufficient information about boundaries
-- **Solution**: Ask specific questions about deployment, team structure, scaling
-- **Workaround**: Default to monolith, allow change later
-
-### Design Errors
-
-**Error**: Unit dependencies are circular
-- **Cause**: Poor boundary definition, tight coupling
-- **Solution**: Identify circular dependencies, suggest refactoring
-- **Recovery**: Revise unit boundaries to break cycles
-
-**Error**: Unit design plan has missing steps
-- **Cause**: Plan generation incomplete, template error
-- **Solution**: Regenerate plan with all required steps
-- **Recovery**: Add missing steps to existing plan
-
-**Error**: Cannot generate design artifacts
-- **Cause**: Missing unit information, unclear requirements
-- **Solution**: Return to Units Planning to clarify unit definition
-- **Workaround**: Generate partial design, mark gaps
-
-### NFR Implementation Errors
-
-**Error**: Technology stack choices are incompatible
-- **Cause**: Conflicting requirements, platform limitations
-- **Solution**: Highlight incompatibilities, ask user to choose
-- **Do Not Proceed**: Until compatible choices are made
-
-**Error**: Organizational constraints cannot be met
-- **Cause**: Network restrictions, security policies
-- **Solution**: Document constraints, ask user for workarounds
-- **Escalation**: May require human intervention for setup
-
-**Error**: NFR implementation step requires human action
-- **Cause**: AI cannot perform certain tasks (network config, credentials)
-- **Solution**: Clearly mark as **HUMAN TASK**, provide instructions
-- **Wait**: For user confirmation before proceeding
-
-### Code Planning Errors
-
-**Error**: Code generation plan is incomplete
-- **Cause**: Missing design artifacts, unclear requirements
-- **Solution**: Return to Design phase to complete artifacts
-- **Recovery**: Generate plan with available information, mark gaps
-
-**Error**: Unit dependencies not satisfied
-- **Cause**: Dependent units not yet generated
-- **Solution**: Reorder generation sequence to respect dependencies
-- **Workaround**: Generate with stub dependencies, integrate later
-
-### Code Generation Errors
-
-**Error**: Cannot generate code for a step
-- **Cause**: Insufficient design information, unclear requirements
-- **Solution**: Skip step, document as incomplete, continue
-- **Recovery**: Return to step after gathering more information
-
-**Error**: Generated code has syntax errors
-- **Cause**: Template issues, language-specific problems
-- **Solution**: Fix syntax errors, regenerate if needed
-- **Validation**: Verify code compiles before proceeding
-
-**Error**: Test generation fails
-- **Cause**: Complex logic, missing test framework setup
-- **Solution**: Generate basic test structure, mark for manual completion
-- **Workaround**: Proceed without tests, add in Operations phase
-
-### Operations Errors
-
-**Error**: Cannot determine build tool
-- **Cause**: Unusual project structure, multiple build systems
-- **Solution**: Ask user to specify build tool and commands
-- **Workaround**: Provide generic instructions, user adapts
-
-**Error**: Deployment target is unclear
-- **Cause**: Multiple environments, complex infrastructure
-- **Solution**: Ask user to specify deployment targets and methods
-- **Workaround**: Provide instructions for common platforms
-
-## Recovery Procedures
-
-### Partial Phase Completion
-
-**Scenario**: Phase was interrupted mid-execution
-
-**Recovery Steps**:
-1. Load the phase plan file
-2. Identify last completed step (last [x] checkbox)
-3. Resume from next uncompleted step
-4. Verify all prior steps are actually complete
-5. Continue execution normally
-
-### Corrupted State File
-
-**Scenario**: `aidlc-state.md` is corrupted or inconsistent
-
-**Recovery Steps**:
-1. Create backup: `aidlc-state.md.backup`
-2. Ask user which phase they're actually on
-3. Regenerate state file from scratch
-4. Mark completed phases based on existing artifacts
-5. Resume from current phase
-
-### Missing Artifacts
-
-**Scenario**: Required artifacts from prior phase are missing
-
-**Recovery Steps**:
-1. Identify which artifacts are missing
-2. Determine if they can be regenerated
-3. If yes: Return to that phase, regenerate artifacts
-4. If no: Ask user to provide information manually
-5. Document the gap in `audit.md`
-
-### User Wants to Restart Phase
-
-**Scenario**: User is unhappy with phase results and wants to redo
-
-**Recovery Steps**:
-1. Confirm user wants to restart (data will be lost)
-2. Archive existing artifacts: `{artifact}.backup`
-3. Reset phase status in `aidlc-state.md`
-4. Clear phase checkboxes in plan files
-5. Re-execute phase from beginning
-
-### User Wants to Skip Phase
-
-**Scenario**: User wants to skip a phase that was planned
-
-**Recovery Steps**:
-1. Confirm user understands implications
-2. Document skip reason in `audit.md`
-3. Mark phase as "SKIPPED" in `aidlc-state.md`
-4. Proceed to next phase
-5. Note: May cause issues in later phases if dependencies missing
-
-## Escalation Guidelines
-
-### When to Ask for User Help
-
-**Immediately**:
-- Contradictory or ambiguous user input
-- Missing required information
-- Technical constraints AI cannot resolve
-- Decisions requiring business judgment
-
-**After Attempting Resolution**:
-- Repeated errors in same step
-- Complex technical issues
-- Unusual project structures
-- Integration with external systems
-
-### When to Suggest Starting Over
-
-**Consider Fresh Start If**:
-- Multiple phases have errors
-- State file is severely corrupted
-- User cannot provide missing information
-- Artifacts are inconsistent across phases
-
-## Session Resumption Errors
-
-### Missing Artifacts During Resumption
-
-**Error**: Required artifacts from previous stages are missing
-- **Cause**: Files deleted, moved, or never created
-- **Solution**: 
-  1. Identify which stage created the missing artifacts
-  2. Check if stage was marked complete in aidlc-state.md
-  3. If marked complete but artifacts missing: Regenerate that stage
-  4. If not marked complete: Resume from that stage
-- **Recovery**: Return to the stage that creates missing artifacts and re-execute
-
-**Error**: Artifact file exists but is empty or corrupted
-- **Cause**: Interrupted write, manual editing, file system issues
-- **Solution**:
-  1. Create backup of corrupted file
-  2. Attempt to regenerate from stage that creates it
-  3. If cannot regenerate: Ask user for information to recreate
-- **Recovery**: Re-execute the stage that creates the artifact
-
-### Inconsistent State During Resumption
-
-**Error**: aidlc-state.md shows stage complete but artifacts don't exist
-- **Cause**: State file updated but artifact generation failed
-- **Solution**:
-  1. Mark stage as incomplete in aidlc-state.md
-  2. Re-execute the stage to generate artifacts
-  3. Verify artifacts exist before marking complete
-- **Recovery**: Reset stage status and re-execute
-
-**Error**: Artifacts exist but aidlc-state.md shows stage incomplete
-- **Cause**: Artifact generation succeeded but state update failed
-- **Solution**:
-  1. Verify artifacts are complete and valid
-  2. Update aidlc-state.md to mark stage complete
-  3. Proceed to next stage
-- **Recovery**: Update state file to reflect actual completion
-
-**Error**: Multiple stages marked as "current" in aidlc-state.md
-- **Cause**: State file corruption, manual editing
-- **Solution**:
-  1. Review artifacts to determine actual progress
-  2. Ask user which stage they're actually on
-  3. Correct aidlc-state.md to show single current stage
-- **Recovery**: Rebuild state file based on existing artifacts
-
-### Context Loading Errors
-
-**Error**: Cannot load required context from previous stages
-- **Cause**: Missing files, corrupted content, wrong file paths
-- **Solution**:
-  1. List which artifacts are needed for current stage
-  2. Check which ones are missing or corrupted
-  3. Regenerate missing artifacts or ask user for information
-- **Recovery**: Complete prerequisite stages before resuming current stage
-
-**Error**: Loaded artifacts contain contradictory information
-- **Cause**: Manual editing, multiple people working, incomplete updates
-- **Solution**:
-  1. Identify contradictions and present to user
-  2. Ask user which information is correct
-  3. Update artifacts to resolve contradictions
-- **Recovery**: Reconcile contradictions before proceeding
-
-### Resumption Best Practices
-
-1. **Always validate state**: Check aidlc-state.md matches actual artifacts
-2. **Load incrementally**: Load artifacts stage-by-stage, validate each
-3. **Fail fast**: Stop immediately if critical artifacts are missing
-4. **Communicate clearly**: Tell user exactly what's missing and why it's needed
-5. **Offer options**: Regenerate, provide manually, or start fresh
-6. **Document recovery**: Log all recovery actions in audit.md State file is severely corrupted
-- User requirements have changed significantly
-- Architectural decision needs to be reversed
-
-**Before Starting Over**:
-1. Archive all existing work
-2. Document lessons learned
-3. Identify what to preserve
-4. Get user confirmation
-5. Create new execution plan
-
-## Logging Requirements
-
-### Error Logging Format
-
-```markdown
-## Error - [Phase Name]
-**Timestamp**: [ISO timestamp]
-**Error Type**: [Critical/High/Medium/Low]
-**Description**: [What went wrong]
-**Cause**: [Why it happened]
-**Resolution**: [How it was resolved]
-**Impact**: [Effect on workflow]
-
----
-```
-
-### Recovery Logging Format
-
-```markdown
-## Recovery - [Phase Name]
-**Timestamp**: [ISO timestamp]
-**Issue**: [What needed recovery]
-**Recovery Steps**: [What was done]
-**Outcome**: [Result of recovery]
-**Artifacts Affected**: [List of files]
-
----
-```
-
-## Agent Task Failure Recovery
-
-### When a Delegated Task Fails or Is Lost
-
-**Scenario**: A task delegated via the Task tool returns "No task found with ID", empty output, or an error.
-
-**MANDATORY Rules**:
-1. **NEVER silently do the work yourself** — if you delegated to an agent, the recovery must also use delegation
-2. **NEVER claim the lost agent's work was sufficient** — if you cannot retrieve output, the work is lost
-3. **Retry the delegation** — re-launch the same agent with the same (or refined) prompt
-4. **Maximum 2 retries** — if the agent fails 3 times total, escalate to the user
-5. **Log all failures** — record the task ID, error, and retry attempts in `audit.md`
-
-**Recovery Steps**:
-1. Log the failure: task ID, error message, which agent was used
-2. Re-launch the agent with `run_in_background: false` (foreground) to ensure visibility
-3. If retry fails: try a different agent tier (e.g., escalate from `explore` to `explore-medium`)
-4. If all retries fail: inform the user and ask how to proceed
-5. Document the resolution in `audit.md`
-
-**Error Logging Format**:
-```markdown
-## Agent Task Failure
-**Timestamp**: [ISO timestamp]
-**Task ID**: [lost task ID]
-**Agent**: [agent type]
-**Error**: [error message]
-**Recovery**: [retry attempt or escalation]
-
----
-```
-
-### Background vs Foreground Task Execution
-
-**Default**: Run delegated tasks in the **foreground** (`run_in_background: false`).
-
-Foreground execution provides:
-- Full visibility into agent work (tool calls, progress, decisions)
-- Immediate error detection and recovery
-- Better user experience — the user can see what's happening
-
-**Background execution** (`run_in_background: true`) should ONLY be used for:
-- Non-agent operations: `npm install`, `npm test`, `docker build`, etc.
-- Operations where output is not needed until completion
-
-**NEVER run agent tasks (Task tool with subagent_type) in the background** unless the user explicitly requests it. The risk of silent task loss outweighs the parallelism benefit.
-
-### Parallel Foreground Execution
-
-To run multiple agents in parallel WITHOUT background mode:
-- Launch all agent tasks in the **same response** (multiple Task calls)
-- Do NOT set `run_in_background: true`
-- The system will execute them concurrently while maintaining visibility
-- Wait for all results before proceeding
-
-This gives you parallelism benefits with full transparency.
-
-## Prevention Best Practices
-
-1. **Validate Early**: Check inputs and dependencies before starting work
-2. **Checkpoint Often**: Update checkboxes immediately after completing steps
-3. **Communicate Clearly**: Explain what you're doing and why
-4. **Ask Questions**: Don't assume - clarify ambiguities immediately
-5. **Document Everything**: Log all decisions and changes in `audit.md`
+# Error Handling and Recovery Procedures
+
+## General Error Handling Principles
+
+### When Errors Occur
+1. **Identify the error**: Clearly state what went wrong
+2. **Assess impact**: Determine if the error is blocking or can be worked around
+3. **Communicate**: Inform the user about the error and options
+4. **Offer solutions**: Provide clear steps to resolve or work around the error
+5. **Document**: Log the error and resolution in `audit.md`
+
+### Error Severity Levels
+
+**Critical**: Workflow cannot continue
+- Missing required files or artifacts
+- Invalid user input that cannot be processed
+- System errors preventing file operations
+
+**High**: Phase cannot complete as planned
+- Incomplete answers to required questions
+- Contradictory user responses
+- Missing dependencies from prior phases
+
+**Medium**: Phase can continue with workarounds
+- Optional artifacts missing
+- Non-critical validation failures
+- Partial completion possible
+
+**Low**: Minor issues that don't block progress
+- Formatting inconsistencies
+- Optional information missing
+- Non-blocking warnings
+
+## Phase-Specific Error Handling
+
+### Context Assessment Errors
+
+**Error**: Cannot read workspace files
+- **Cause**: Permission issues, missing directories
+- **Solution**: Ask user to verify workspace path and permissions
+- **Workaround**: Proceed with user-provided information only
+
+**Error**: Existing `aidlc-state.md` is corrupted
+- **Cause**: Manual editing, incomplete previous run
+- **Solution**: Ask user if they want to start fresh or attempt recovery
+- **Recovery**: Create backup, start new state file
+
+**Error**: Cannot determine required phases
+- **Cause**: Insufficient information from user
+- **Solution**: Ask clarifying questions about intent and scope
+- **Workaround**: Default to comprehensive execution plan
+
+### Requirements Assessment Errors
+
+**Error**: User provides contradictory requirements
+- **Cause**: Unclear understanding, changing needs
+- **Solution**: Create follow-up questions to resolve contradictions
+- **Do Not Proceed**: Until contradictions are resolved
+
+**Error**: Requirements document cannot be converted
+- **Cause**: Unsupported format, corrupted file
+- **Solution**: Ask user to provide requirements in supported format
+- **Workaround**: Work with user's verbal description
+
+**Error**: Incomplete answers to verification questions
+- **Cause**: User skipped questions, unclear what to answer
+- **Solution**: Highlight unanswered questions, provide examples
+- **Do Not Proceed**: Until all required questions are answered
+
+### Story Development Errors
+
+**Error**: Cannot map requirements to stories
+- **Cause**: Requirements too vague, missing functional details
+- **Solution**: Return to Requirements Assessment for clarification
+- **Workaround**: Create stories based on available information, mark as incomplete
+
+**Error**: User provides ambiguous story planning answers
+- **Cause**: Unclear options, complex decision
+- **Solution**: Add follow-up questions with specific examples
+- **Do Not Proceed**: Until ambiguities are resolved
+
+**Error**: Story generation plan has uncompleted steps
+- **Cause**: Execution interrupted, steps skipped
+- **Solution**: Resume from first uncompleted step
+- **Recovery**: Review completed steps, continue from checkpoint
+
+### Application Design Errors
+
+**Error**: Architectural decision is unclear or contradictory
+- **Cause**: Ambiguous answers, conflicting requirements
+- **Solution**: Add follow-up questions to clarify decision
+- **Do Not Proceed**: Until decision is clear and documented
+
+**Error**: Cannot determine number of services/units
+- **Cause**: Insufficient information about boundaries
+- **Solution**: Ask specific questions about deployment, team structure, scaling
+- **Workaround**: Default to monolith, allow change later
+
+### Design Errors
+
+**Error**: Unit dependencies are circular
+- **Cause**: Poor boundary definition, tight coupling
+- **Solution**: Identify circular dependencies, suggest refactoring
+- **Recovery**: Revise unit boundaries to break cycles
+
+**Error**: Unit design plan has missing steps
+- **Cause**: Plan generation incomplete, template error
+- **Solution**: Regenerate plan with all required steps
+- **Recovery**: Add missing steps to existing plan
+
+**Error**: Cannot generate design artifacts
+- **Cause**: Missing unit information, unclear requirements
+- **Solution**: Return to Units Planning to clarify unit definition
+- **Workaround**: Generate partial design, mark gaps
+
+### NFR Implementation Errors
+
+**Error**: Technology stack choices are incompatible
+- **Cause**: Conflicting requirements, platform limitations
+- **Solution**: Highlight incompatibilities, ask user to choose
+- **Do Not Proceed**: Until compatible choices are made
+
+**Error**: Organizational constraints cannot be met
+- **Cause**: Network restrictions, security policies
+- **Solution**: Document constraints, ask user for workarounds
+- **Escalation**: May require human intervention for setup
+
+**Error**: NFR implementation step requires human action
+- **Cause**: AI cannot perform certain tasks (network config, credentials)
+- **Solution**: Clearly mark as **HUMAN TASK**, provide instructions
+- **Wait**: For user confirmation before proceeding
+
+### Code Planning Errors
+
+**Error**: Code generation plan is incomplete
+- **Cause**: Missing design artifacts, unclear requirements
+- **Solution**: Return to Design phase to complete artifacts
+- **Recovery**: Generate plan with available information, mark gaps
+
+**Error**: Unit dependencies not satisfied
+- **Cause**: Dependent units not yet generated
+- **Solution**: Reorder generation sequence to respect dependencies
+- **Workaround**: Generate with stub dependencies, integrate later
+
+### Code Generation Errors
+
+**Error**: Cannot generate code for a step
+- **Cause**: Insufficient design information, unclear requirements
+- **Solution**: Skip step, document as incomplete, continue
+- **Recovery**: Return to step after gathering more information
+
+**Error**: Generated code has syntax errors
+- **Cause**: Template issues, language-specific problems
+- **Solution**: Fix syntax errors, regenerate if needed
+- **Validation**: Verify code compiles before proceeding
+
+**Error**: Test generation fails
+- **Cause**: Complex logic, missing test framework setup
+- **Solution**: Generate basic test structure, mark for manual completion
+- **Workaround**: Proceed without tests, add in Operations phase
+
+### Operations Errors
+
+**Error**: Cannot determine build tool
+- **Cause**: Unusual project structure, multiple build systems
+- **Solution**: Ask user to specify build tool and commands
+- **Workaround**: Provide generic instructions, user adapts
+
+**Error**: Deployment target is unclear
+- **Cause**: Multiple environments, complex infrastructure
+- **Solution**: Ask user to specify deployment targets and methods
+- **Workaround**: Provide instructions for common platforms
+
+## Recovery Procedures
+
+### Partial Phase Completion
+
+**Scenario**: Phase was interrupted mid-execution
+
+**Recovery Steps**:
+1. Load the phase plan file
+2. Identify last completed step (last [x] checkbox)
+3. Resume from next uncompleted step
+4. Verify all prior steps are actually complete
+5. Continue execution normally
+
+### Corrupted State File
+
+**Scenario**: `aidlc-state.md` is corrupted or inconsistent
+
+**Recovery Steps**:
+1. Create backup: `aidlc-state.md.backup`
+2. Ask user which phase they're actually on
+3. Regenerate state file from scratch
+4. Mark completed phases based on existing artifacts
+5. Resume from current phase
+
+### Missing Artifacts
+
+**Scenario**: Required artifacts from prior phase are missing
+
+**Recovery Steps**:
+1. Identify which artifacts are missing
+2. Determine if they can be regenerated
+3. If yes: Return to that phase, regenerate artifacts
+4. If no: Ask user to provide information manually
+5. Document the gap in `audit.md`
+
+### User Wants to Restart Phase
+
+**Scenario**: User is unhappy with phase results and wants to redo
+
+**Recovery Steps**:
+1. Confirm user wants to restart (data will be lost)
+2. Archive existing artifacts: `{artifact}.backup`
+3. Reset phase status in `aidlc-state.md`
+4. Clear phase checkboxes in plan files
+5. Re-execute phase from beginning
+
+### User Wants to Skip Phase
+
+**Scenario**: User wants to skip a phase that was planned
+
+**Recovery Steps**:
+1. Confirm user understands implications
+2. Document skip reason in `audit.md`
+3. Mark phase as "SKIPPED" in `aidlc-state.md`
+4. Proceed to next phase
+5. Note: May cause issues in later phases if dependencies missing
+
+## Escalation Guidelines
+
+### When to Ask for User Help
+
+**Immediately**:
+- Contradictory or ambiguous user input
+- Missing required information
+- Technical constraints AI cannot resolve
+- Decisions requiring business judgment
+
+**After Attempting Resolution**:
+- Repeated errors in same step
+- Complex technical issues
+- Unusual project structures
+- Integration with external systems
+
+### When to Suggest Starting Over
+
+**Consider Fresh Start If**:
+- Multiple phases have errors
+- State file is severely corrupted
+- User cannot provide missing information
+- Artifacts are inconsistent across phases
+
+## Session Resumption Errors
+
+### Missing Artifacts During Resumption
+
+**Error**: Required artifacts from previous stages are missing
+- **Cause**: Files deleted, moved, or never created
+- **Solution**: 
+  1. Identify which stage created the missing artifacts
+  2. Check if stage was marked complete in aidlc-state.md
+  3. If marked complete but artifacts missing: Regenerate that stage
+  4. If not marked complete: Resume from that stage
+- **Recovery**: Return to the stage that creates missing artifacts and re-execute
+
+**Error**: Artifact file exists but is empty or corrupted
+- **Cause**: Interrupted write, manual editing, file system issues
+- **Solution**:
+  1. Create backup of corrupted file
+  2. Attempt to regenerate from stage that creates it
+  3. If cannot regenerate: Ask user for information to recreate
+- **Recovery**: Re-execute the stage that creates the artifact
+
+### Inconsistent State During Resumption
+
+**Error**: aidlc-state.md shows stage complete but artifacts don't exist
+- **Cause**: State file updated but artifact generation failed
+- **Solution**:
+  1. Mark stage as incomplete in aidlc-state.md
+  2. Re-execute the stage to generate artifacts
+  3. Verify artifacts exist before marking complete
+- **Recovery**: Reset stage status and re-execute
+
+**Error**: Artifacts exist but aidlc-state.md shows stage incomplete
+- **Cause**: Artifact generation succeeded but state update failed
+- **Solution**:
+  1. Verify artifacts are complete and valid
+  2. Update aidlc-state.md to mark stage complete
+  3. Proceed to next stage
+- **Recovery**: Update state file to reflect actual completion
+
+**Error**: Multiple stages marked as "current" in aidlc-state.md
+- **Cause**: State file corruption, manual editing
+- **Solution**:
+  1. Review artifacts to determine actual progress
+  2. Ask user which stage they're actually on
+  3. Correct aidlc-state.md to show single current stage
+- **Recovery**: Rebuild state file based on existing artifacts
+
+### Context Loading Errors
+
+**Error**: Cannot load required context from previous stages
+- **Cause**: Missing files, corrupted content, wrong file paths
+- **Solution**:
+  1. List which artifacts are needed for current stage
+  2. Check which ones are missing or corrupted
+  3. Regenerate missing artifacts or ask user for information
+- **Recovery**: Complete prerequisite stages before resuming current stage
+
+**Error**: Loaded artifacts contain contradictory information
+- **Cause**: Manual editing, multiple people working, incomplete updates
+- **Solution**:
+  1. Identify contradictions and present to user
+  2. Ask user which information is correct
+  3. Update artifacts to resolve contradictions
+- **Recovery**: Reconcile contradictions before proceeding
+
+### Resumption Best Practices
+
+1. **Always validate state**: Check aidlc-state.md matches actual artifacts
+2. **Load incrementally**: Load artifacts stage-by-stage, validate each
+3. **Fail fast**: Stop immediately if critical artifacts are missing
+4. **Communicate clearly**: Tell user exactly what's missing and why it's needed
+5. **Offer options**: Regenerate, provide manually, or start fresh
+6. **Document recovery**: Log all recovery actions in audit.md State file is severely corrupted
+- User requirements have changed significantly
+- Architectural decision needs to be reversed
+
+**Before Starting Over**:
+1. Archive all existing work
+2. Document lessons learned
+3. Identify what to preserve
+4. Get user confirmation
+5. Create new execution plan
+
+## Logging Requirements
+
+### Error Logging Format
+
+```markdown
+## Error - [Phase Name]
+**Timestamp**: [ISO timestamp]
+**Error Type**: [Critical/High/Medium/Low]
+**Description**: [What went wrong]
+**Cause**: [Why it happened]
+**Resolution**: [How it was resolved]
+**Impact**: [Effect on workflow]
+
+---
+```
+
+### Recovery Logging Format
+
+```markdown
+## Recovery - [Phase Name]
+**Timestamp**: [ISO timestamp]
+**Issue**: [What needed recovery]
+**Recovery Steps**: [What was done]
+**Outcome**: [Result of recovery]
+**Artifacts Affected**: [List of files]
+
+---
+```
+
+## Agent Task Failure Recovery
+
+### When a Delegated Task Fails or Is Lost
+
+**Scenario**: A task delegated via the Task tool returns "No task found with ID", empty output, or an error.
+
+**MANDATORY Rules**:
+1. **NEVER silently do the work yourself** — if you delegated to an agent, the recovery must also use delegation
+2. **NEVER claim the lost agent's work was sufficient** — if you cannot retrieve output, the work is lost
+3. **Retry the delegation** — re-launch the same agent with the same (or refined) prompt
+4. **Maximum 2 retries** — if the agent fails 3 times total, escalate to the user
+5. **Log all failures** — record the task ID, error, and retry attempts in `audit.md`
+
+**Recovery Steps**:
+1. Log the failure: task ID, error message, which agent was used
+2. Re-launch the agent with `run_in_background: false` (foreground) to ensure visibility
+3. If retry fails: try a different agent tier (e.g., escalate from `explore` to `explore-medium`)
+4. If all retries fail: inform the user and ask how to proceed
+5. Document the resolution in `audit.md`
+
+**Error Logging Format**:
+```markdown
+## Agent Task Failure
+**Timestamp**: [ISO timestamp]
+**Task ID**: [lost task ID]
+**Agent**: [agent type]
+**Error**: [error message]
+**Recovery**: [retry attempt or escalation]
+
+---
+```
+
+### Background vs Foreground Task Execution
+
+**Default**: Run delegated tasks in the **foreground** (`run_in_background: false`).
+
+Foreground execution provides:
+- Full visibility into agent work (tool calls, progress, decisions)
+- Immediate error detection and recovery
+- Better user experience — the user can see what's happening
+
+**Background execution** (`run_in_background: true`) should ONLY be used for:
+- Non-agent operations: `npm install`, `npm test`, `docker build`, etc.
+- Operations where output is not needed until completion
+
+**NEVER run agent tasks (Task tool with subagent_type) in the background** unless the user explicitly requests it. The risk of silent task loss outweighs the parallelism benefit.
+
+### Parallel Foreground Execution
+
+To run multiple agents in parallel WITHOUT background mode:
+- Launch all agent tasks in the **same response** (multiple Task calls)
+- Do NOT set `run_in_background: true`
+- The system will execute them concurrently while maintaining visibility
+- Wait for all results before proceeding
+
+This gives you parallelism benefits with full transparency.
+
+## Prevention Best Practices
+
+1. **Validate Early**: Check inputs and dependencies before starting work
+2. **Checkpoint Often**: Update checkboxes immediately after completing steps
+3. **Communicate Clearly**: Explain what you're doing and why
+4. **Ask Questions**: Don't assume - clarify ambiguities immediately
+5. **Document Everything**: Log all decisions and changes in `audit.md`