Cursor rule

1---
2alwaysApply: false
3---
4 
5# Error Handling and Recovery Procedures
6 
7## General Error Handling Principles
8 
9### When Errors Occur
101. **Identify the error**: Clearly state what went wrong
112. **Assess impact**: Determine if the error is blocking or can be worked around
123. **Communicate**: Inform the user about the error and options
134. **Offer solutions**: Provide clear steps to resolve or work around the error
145. **Document**: Log the error and resolution in `audit.md`
15 
16### Error Severity Levels
17 
18**Critical**: Workflow cannot continue
19- Missing required files or artifacts
20- Invalid user input that cannot be processed
21- System errors preventing file operations
22 
23**High**: Stage cannot complete as planned
24- Incomplete answers to required questions
25- Contradictory user responses
26- Missing dependencies from prior stages
27 
28**Medium**: Stage can continue with workarounds
29- Optional artifacts missing
30- Non-critical validation failures
31- Partial completion possible
32 
33**Low**: Minor issues that don't block progress
34- Formatting inconsistencies
35- Optional information missing
36- Non-blocking warnings
37 
38## Stage-Specific Error Handling
39 
40### Workspace Detection Errors
41 
42**Error**: Cannot read workspace files
43- **Cause**: Permission issues, missing directories
44- **Solution**: Ask user to verify workspace path and permissions
45- **Workaround**: Proceed with user-provided information only
46 
47**Error**: Existing `aidlc-state.md` is corrupted
48- **Cause**: Manual editing, incomplete previous run
49- **Solution**: Ask user if they want to start fresh or attempt recovery
50- **Recovery**: Create backup, start new state file
51 
52**Error**: Cannot determine required stages
53- **Cause**: Insufficient information from user
54- **Solution**: Ask clarifying questions about intent and scope
55- **Workaround**: Default to comprehensive execution plan
56 
57### Requirements Analysis Errors
58 
59**Error**: User provides contradictory requirements
60- **Cause**: Unclear understanding, changing needs
61- **Solution**: Create follow-up questions to resolve contradictions
62- **Do Not Proceed**: Until contradictions are resolved
63 
64**Error**: Requirements document cannot be converted
65- **Cause**: Unsupported format, corrupted file
66- **Solution**: Ask user to provide requirements in supported format
67- **Workaround**: Work with user's verbal description
68 
69**Error**: Incomplete answers to verification questions
70- **Cause**: User skipped questions, unclear what to answer
71- **Solution**: Highlight unanswered questions, provide examples
72- **Do Not Proceed**: Until all required questions are answered
73 
74### User Stories Errors
75 
76**Error**: Cannot map requirements to stories
77- **Cause**: Requirements too vague, missing functional details
78- **Solution**: Return to Requirements Analysis for clarification
79- **Workaround**: Create stories based on available information, mark as incomplete
80 
81**Error**: User provides ambiguous story planning answers
82- **Cause**: Unclear options, complex decision
83- **Solution**: Add follow-up questions with specific examples
84- **Do Not Proceed**: Until ambiguities are resolved
85 
86**Error**: Story generation plan has uncompleted steps
87- **Cause**: Execution interrupted, steps skipped
88- **Solution**: Resume from first uncompleted step
89- **Recovery**: Review completed steps, continue from checkpoint
90 
91### Application Design Errors
92 
93**Error**: Architectural decision is unclear or contradictory
94- **Cause**: Ambiguous answers, conflicting requirements
95- **Solution**: Add follow-up questions to clarify decision
96- **Do Not Proceed**: Until decision is clear and documented
97 
98**Error**: Cannot determine number of services/units
99- **Cause**: Insufficient information about boundaries
100- **Solution**: Ask specific questions about deployment, team structure, scaling
101- **Workaround**: Default to monolith, allow change later
102 
103### Design Errors
104 
105**Error**: Unit dependencies are circular
106- **Cause**: Poor boundary definition, tight coupling
107- **Solution**: Identify circular dependencies, suggest refactoring
108- **Recovery**: Revise unit boundaries to break cycles
109 
110**Error**: Unit design plan has missing steps
111- **Cause**: Plan generation incomplete, template error
112- **Solution**: Regenerate plan with all required steps
113- **Recovery**: Add missing steps to existing plan
114 
115**Error**: Cannot generate design artifacts
116- **Cause**: Missing unit information, unclear requirements
117- **Solution**: Return to Units Planning to clarify unit definition
118- **Workaround**: Generate partial design, mark gaps
119 
120### NFR Implementation Errors
121 
122**Error**: Technology stack choices are incompatible
123- **Cause**: Conflicting requirements, platform limitations
124- **Solution**: Highlight incompatibilities, ask user to choose
125- **Do Not Proceed**: Until compatible choices are made
126 
127**Error**: Organizational constraints cannot be met
128- **Cause**: Network restrictions, security policies
129- **Solution**: Document constraints, ask user for workarounds
130- **Escalation**: May require human intervention for setup
131 
132**Error**: NFR implementation step requires human action
133- **Cause**: AI cannot perform certain tasks (network config, credentials)
134- **Solution**: Clearly mark as **HUMAN TASK**, provide instructions
135- **Wait**: For user confirmation before proceeding
136 
137### Code Generation Planning Errors
138 
139**Error**: Code generation plan is incomplete
140- **Cause**: Missing design artifacts, unclear requirements
141- **Solution**: Return to Design stage to complete artifacts
142- **Recovery**: Generate plan with available information, mark gaps
143 
144**Error**: Unit dependencies not satisfied
145- **Cause**: Dependent units not yet generated
146- **Solution**: Reorder generation sequence to respect dependencies
147- **Workaround**: Generate with stub dependencies, integrate later
148 
149### Code Generation Errors (Part 2: Code Generation)
150 
151**Error**: Cannot generate code for a step
152- **Cause**: Insufficient design information, unclear requirements
153- **Solution**: Skip step, document as incomplete, continue
154- **Recovery**: Return to step after gathering more information
155 
156**Error**: Generated code has syntax errors
157- **Cause**: Template issues, language-specific problems
158- **Solution**: Fix syntax errors, regenerate if needed
159- **Validation**: Verify code compiles before proceeding
160 
161**Error**: Test generation fails
162- **Cause**: Complex logic, missing test framework setup
163- **Solution**: Generate basic test structure, mark for manual completion
164- **Workaround**: Proceed without tests, add in Operations phase
165 
166### Operations Errors
167 
168**Error**: Cannot determine build tool
169- **Cause**: Unusual project structure, multiple build systems
170- **Solution**: Ask user to specify build tool and commands
171- **Workaround**: Provide generic instructions, user adapts
172 
173**Error**: Deployment target is unclear
174- **Cause**: Multiple environments, complex infrastructure
175- **Solution**: Ask user to specify deployment targets and methods
176- **Workaround**: Provide instructions for common platforms
177 
178## Recovery Procedures
179 
180### Partial Stage Completion
181 
182**Scenario**: Stage was interrupted mid-execution
183 
184**Recovery Steps**:
1851. Load the stage plan file
1862. Identify last completed step (last [x] checkbox)
1873. Resume from next uncompleted step
1884. Verify all prior steps are actually complete
1895. Continue execution normally
190 
191### Corrupted State File
192 
193**Scenario**: `aidlc-state.md` is corrupted or inconsistent
194 
195**Recovery Steps**:
1961. Create backup: `aidlc-state.md.backup`
1972. Ask user which stage they're actually on
1983. Regenerate state file from scratch
1994. Mark completed stages based on existing artifacts
2005. Resume from current stage
201 
202### Missing Artifacts
203 
204**Scenario**: Required artifacts from prior stage are missing
205 
206**Recovery Steps**:
2071. Identify which artifacts are missing
2082. Determine if they can be regenerated
2093. If yes: Return to that stage, regenerate artifacts
2104. If no: Ask user to provide information manually
2115. Document the gap in `audit.md`
212 
213### User Wants to Restart Stage
214 
215**Scenario**: User is unhappy with stage results and wants to redo
216 
217**Recovery Steps**:
2181. Confirm user wants to restart (data will be lost)
2192. Archive existing artifacts: `{artifact}.backup`
2203. Reset stage status in `aidlc-state.md`
2214. Clear stage checkboxes in plan files
2225. Re-execute stage from beginning
223 
224### User Wants to Skip Stage
225 
226**Scenario**: User wants to skip a stage that was planned
227 
228**Recovery Steps**:
2291. Confirm user understands implications
2302. Document skip reason in `audit.md`
2313. Mark stage as "SKIPPED" in `aidlc-state.md`
2324. Proceed to next stage
2335. Note: May cause issues in later stages if dependencies missing
234 
235## Escalation Guidelines
236 
237### When to Ask for User Help
238 
239**Immediately**:
240- Contradictory or ambiguous user input
241- Missing required information
242- Technical constraints AI cannot resolve
243- Decisions requiring business judgment
244 
245**After Attempting Resolution**:
246- Repeated errors in same step
247- Complex technical issues
248- Unusual project structures
249- Integration with external systems
250 
251### When to Suggest Starting Over
252 
253**Consider Fresh Start If**:
254- Multiple stages have errors
255- State file is severely corrupted
256- User requirements have changed significantly
257- Architectural decision needs to be reversed
258- User cannot provide missing information
259- Artifacts are inconsistent across phases
260 
261**Before Starting Over**:
2621. Archive all existing work
2632. Document lessons learned
2643. Identify what to preserve
2654. Get user confirmation
2665. Create new execution plan
267 
268## Session Resumption Errors
269 
270### Missing Artifacts During Resumption
271 
272**Error**: Required artifacts from previous stages are missing
273- **Cause**: Files deleted, moved, or never created
274- **Solution**: 
275  1. Identify which stage created the missing artifacts
276  2. Check if stage was marked complete in aidlc-state.md
277  3. If marked complete but artifacts missing: Regenerate that stage
278  4. If not marked complete: Resume from that stage
279- **Recovery**: Return to the stage that creates missing artifacts and re-execute
280 
281**Error**: Artifact file exists but is empty or corrupted
282- **Cause**: Interrupted write, manual editing, file system issues
283- **Solution**:
284  1. Create backup of corrupted file
285  2. Attempt to regenerate from stage that creates it
286  3. If cannot regenerate: Ask user for information to recreate
287- **Recovery**: Re-execute the stage that creates the artifact
288 
289### Inconsistent State During Resumption
290 
291**Error**: aidlc-state.md shows stage complete but artifacts don't exist
292- **Cause**: State file updated but artifact generation failed
293- **Solution**:
294  1. Mark stage as incomplete in aidlc-state.md
295  2. Re-execute the stage to generate artifacts
296  3. Verify artifacts exist before marking complete
297- **Recovery**: Reset stage status and re-execute
298 
299**Error**: Artifacts exist but aidlc-state.md shows stage incomplete
300- **Cause**: Artifact generation succeeded but state update failed
301- **Solution**:
302  1. Verify artifacts are complete and valid
303  2. Update aidlc-state.md to mark stage complete
304  3. Proceed to next stage
305- **Recovery**: Update state file to reflect actual completion
306 
307**Error**: Multiple stages marked as "current" in aidlc-state.md
308- **Cause**: State file corruption, manual editing
309- **Solution**:
310  1. Review artifacts to determine actual progress
311  2. Ask user which stage they're actually on
312  3. Correct aidlc-state.md to show single current stage
313- **Recovery**: Rebuild state file based on existing artifacts
314 
315### Context Loading Errors
316 
317**Error**: Cannot load required context from previous stages
318- **Cause**: Missing files, corrupted content, wrong file paths
319- **Solution**:
320  1. List which artifacts are needed for current stage
321  2. Check which ones are missing or corrupted
322  3. Regenerate missing artifacts or ask user for information
323- **Recovery**: Complete prerequisite stages before resuming current stage
324 
325**Error**: Loaded artifacts contain contradictory information
326- **Cause**: Manual editing, multiple people working, incomplete updates
327- **Solution**:
328  1. Identify contradictions and present to user
329  2. Ask user which information is correct
330  3. Update artifacts to resolve contradictions
331- **Recovery**: Reconcile contradictions before proceeding
332 
333### Resumption Best Practices
334 
3351. **Always validate state**: Check aidlc-state.md matches actual artifacts
3362. **Load incrementally**: Load artifacts stage-by-stage, validate each
3373. **Fail fast**: Stop immediately if critical artifacts are missing
3384. **Communicate clearly**: Tell user exactly what's missing and why it's needed
3395. **Offer options**: Regenerate, provide manually, or start fresh
3406. **Document recovery**: Log all recovery actions in audit.md
341 
342## Logging Requirements
343 
344### Error Logging Format
345 
346```markdown
347## Error - [Stage Name]
348**Timestamp**: [ISO timestamp]
349**Error Type**: [Critical/High/Medium/Low]
350**Description**: [What went wrong]
351**Cause**: [Why it happened]
352**Resolution**: [How it was resolved]
353**Impact**: [Effect on workflow]
354 
355---
356```
357 
358### Recovery Logging Format
359 
360```markdown
361## Recovery - [Stage Name]
362**Timestamp**: [ISO timestamp]
363**Issue**: [What needed recovery]
364**Recovery Steps**: [What was done]
365**Outcome**: [Result of recovery]
366**Artifacts Affected**: [List of files]
367 
368---
369```
370 
371## Prevention Best Practices
372 
3731. **Validate Early**: Check inputs and dependencies before starting work
3742. **Checkpoint Often**: Update checkboxes immediately after completing steps
3753. **Communicate Clearly**: Explain what you're doing and why
3764. **Ask Questions**: Don't assume - clarify ambiguities immediately
3775. **Document Everything**: Log all decisions and changes in `audit.md`
378