Fixes issue #104 (#120)

Author: raj-jain-aws

aidlc-rules/aws-aidlc-rule-details/common/error-handling.md

@@ -130,7 +130,7 @@
 - **Solution**: Clearly mark as **HUMAN TASK**, provide instructions
 - **Wait**: For user confirmation before proceeding
 
-### Code Planning Errors
+### Code Generation Planning Errors
 
 **Error**: Code generation plan is incomplete
 - **Cause**: Missing design artifacts, unclear requirements

aidlc-rules/aws-aidlc-rule-details/common/process-overview.md

@@ -9,7 +9,7 @@
 
 ## The Three-Phase Lifecycle:
 • **INCEPTION PHASE**: Planning and architecture (Workspace Detection + conditional phases + Workflow Planning)
-• **CONSTRUCTION PHASE**: Design, implementation, build and test (per-unit design + Code Planning/Generation + Build & Test)
+• **CONSTRUCTION PHASE**: Design, implementation, build and test (per-unit design + Code Generation + Build & Test)
 • **OPERATIONS PHASE**: Placeholder for future deployment and monitoring workflows
 
 ## The Adaptive Workflow:

aidlc-rules/aws-aidlc-rule-details/common/terminology.md

@@ -10,13 +10,13 @@
 - 🟡 **OPERATIONS PHASE** - Deployment & Monitoring (future expansion)
 
 **Stage**: An individual workflow activity within a phase
-- Examples: Context Assessment stage, Requirements Assessment stage, Code Planning stage
+- Examples: Context Assessment stage, Requirements Assessment stage, Code Generation stage
 - Each stage has specific prerequisites, steps, and outputs
 - Stages can be ALWAYS-EXECUTE or CONDITIONAL
 
 **Usage Examples**:
 - ✅ "The CONSTRUCTION phase contains 7 stages"
-- ✅ "The Code Planning stage is always executed"
+- ✅ "The Code Generation stage is always executed"
 - ✅ "We're in the INCEPTION phase, executing the Requirements Assessment stage"
 - ❌ "The Requirements Assessment phase" (should be "stage")
 - ❌ "The CONSTRUCTION stage" (should be "phase")
@@ -49,8 +49,7 @@
 - NFR Requirements (CONDITIONAL, per-unit)
 - NFR Design (CONDITIONAL, per-unit)
 - Infrastructure Design (CONDITIONAL, per-unit)
-- Code Planning (ALWAYS)
-- Code Generation (ALWAYS)
+- Code Generation (ALWAYS) — includes Part 1: Planning and Part 2: Generation
 - Build and Test (ALWAYS)
 
 **Outputs**: Design artifacts, NFR implementations, code, tests
@@ -73,8 +72,7 @@
 - **Workspace Detection**: Initial analysis of workspace state and project type
 - **Requirements Analysis**: Gathering requirements (depth varies based on complexity)
 - **Workflow Planning**: Creating execution plan for which phases to run
-- **Code Planning**: Creating detailed implementation plans for code generation
-- **Code Generation**: Generating actual code based on plans and prior artifacts
+- **Code Generation**: Single stage with two parts — Part 1 (Planning) creates detailed implementation plans, Part 2 (Generation) generates actual code based on plans and prior artifacts
 - **Build and Test**: Building all units and executing comprehensive testing
 
 ### Conditional Stages
@@ -156,7 +154,7 @@ Examples:
 - Units Planning → Units Generation
 - Unit Design Planning → Unit Design Generation
 - NFR Planning → NFR Generation
-- Code Planning → Code Generation
+- Code Generation Part 1 (Planning) → Code Generation Part 2 (Generation)
 
 ### Depth Levels
 - **Minimal**: Quick, focused execution for simple changes

aidlc-rules/aws-aidlc-rule-details/common/workflow-changes.md

@@ -85,7 +85,7 @@ Users may request changes to the execution plan or phase execution during the wo
 
 **Handling**:
 1. **Assess Impact**: Identify all stages that depend on the stage to be restarted
-2. **Warn User**: "Restarting Application Design will require redoing: Units Planning, Units Generation, per-unit design (all units), Code Planning, Code Generation. Confirm?"
+2. **Warn User**: "Restarting Application Design will require redoing: Units Planning, Units Generation, per-unit design (all units), Code Generation. Confirm?"
 3. **Get Explicit Confirmation**: User must understand full impact
 4. **If Confirmed**:
    - Archive all affected artifacts

aidlc-rules/aws-aidlc-rule-details/construction/code-generation.md

@@ -87,7 +87,7 @@ This stage generates code for each unit of work through two integrated parts:
 - [ ] Mark the approval status clearly
 
 ## Step 9: Update Progress
-- [ ] Mark Code Planning complete in `aidlc-state.md`
+- [ ] Mark Code Generation Part 1 (Planning) complete in `aidlc-state.md`
 - [ ] Update the "Current Status" section
 - [ ] Prepare for transition to Code Generation
 

aidlc-rules/aws-aidlc-rule-details/inception/application-design.md

@@ -38,7 +38,7 @@ Application Design focuses on:
   - [ ] Validate design completeness and consistency
 
 ### 4. Generate Context-Appropriate Questions
-**DIRECTIVE**: Analyze the requirements and stories to generate ONLY questions relevant to THIS specific application design. Use the categories below as inspiration, NOT as a mandatory checklist. Skip entire categories if not applicable.
+**DIRECTIVE**: Analyze the requirements and stories to generate questions relevant to THIS specific application design. Use the categories below as guidance. Evaluate each category and, when in doubt about applicability, ask the question rather than skipping it — overconfidence leads to poor outcomes (see overconfidence-prevention.md).
 
 - EMBED questions using [Answer]: tag format
 - Focus on ambiguities and missing information specific to this context

aidlc-rules/aws-aidlc-rule-details/inception/reverse-engineering.md

@@ -6,7 +6,7 @@
 
 **Skip when**: Greenfield project (no existing code)
 
-**Rerun behavior**: Always rerun when brownfield project detected, even if artifacts exist. This ensures artifacts reflect current code state
+**Rerun behavior**: Rerun is controlled by workspace-detection.md. If existing reverse engineering artifacts are found and are still current, they are loaded and reverse engineering is skipped. If artifacts are stale (older than the codebase's last significant modification) or the user explicitly requests a rerun, reverse engineering executes again to ensure artifacts reflect current code state
 
 ## Step 1: Multi-Package Discovery
 

aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md

@@ -203,7 +203,6 @@ Create Mermaid flowchart showing:
 **Styling rules** (add after flowchart):
 ```
 style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
-style CP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
 style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
 style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
 style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
@@ -271,8 +270,7 @@ flowchart TD
         NFRA["NFR Requirements<br/><b>STATUS</b>"]
         NFRD["NFR Design<br/><b>STATUS</b>"]
         ID["Infrastructure Design<br/><b>STATUS</b>"]
-        CP["Code Planning<br/><b>EXECUTE</b>"]
-        CG["Code Generation<br/><b>EXECUTE</b>"]
+        CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
         BT["Build and Test<br/><b>EXECUTE</b>"]
     end
     
@@ -283,8 +281,7 @@ flowchart TD
     Start --> WD
     WD --> RA
     RA --> WP
-    WP --> CP
-    CP --> CG
+    WP --> CG
     CG --> BT
     BT --> End(["Complete"])
     
@@ -318,10 +315,8 @@ flowchart TD
   - **Rationale**: [Why executing or skipping]
 - [ ] Infrastructure Design - [EXECUTE/SKIP]
   - **Rationale**: [Why executing or skipping]
-- [ ] Code Planning - EXECUTE (ALWAYS)
-  - **Rationale**: Implementation approach needed
 - [ ] Code Generation - EXECUTE (ALWAYS)
-  - **Rationale**: Code implementation needed
+  - **Rationale**: Implementation planning and code generation needed
 - [ ] Build and Test - EXECUTE (ALWAYS)
   - **Rationale**: Build, test, and verification needed
 
@@ -380,7 +375,6 @@ Update `aidlc-docs/aidlc-state.md`:
 - [ ] NFR Requirements - [EXECUTE/SKIP]
 - [ ] NFR Design - [EXECUTE/SKIP]
 - [ ] Infrastructure Design - [EXECUTE/SKIP]
-- [ ] Code Planning - EXECUTE
 - [ ] Code Generation - EXECUTE
 - [ ] Build and Test - EXECUTE
 

aidlc-rules/aws-aidlc-rule-details/inception/workspace-detection.md

@@ -35,7 +35,11 @@ Check if `aidlc-docs/aidlc-state.md` exists:
 **IF workspace has existing code**:
 - Set flag: `brownfield = true`
 - Check for existing reverse engineering artifacts in `aidlc-docs/inception/reverse-engineering/`
-- **IF reverse engineering artifacts exist**: Load them, skip to Requirements Analysis
+- **IF reverse engineering artifacts exist**:
+    - Check if artifacts are stale (compare artifact timestamps against codebase's last significant modification)
+    - **IF artifacts are current**: Load them, skip to Requirements Analysis
+    - **IF artifacts are stale**: Next phase is Reverse Engineering (rerun to refresh artifacts)
+    - **IF user explicitly requests rerun**: Next phase is Reverse Engineering regardless of staleness
 - **IF no reverse engineering artifacts**: Next phase is Reverse Engineering
 
 ## Step 4: Create Initial State File