fix(rules): reconcile Units Planning ghost stage with canonical Units Generation (#156)

* fix(rules): reconcile Units Planning ghost stage with canonical Units Generation

Units Planning was referenced as a separate workflow stage in 5 files
(workflow-planning.md, units-generation.md, terminology.md,
workflow-changes.md, error-handling.md) but was never defined as a
top-level stage in core-workflow.md. It is actually Part 1 (an internal
sub-step) of the Units Generation stage.

This inconsistency caused:
- State tracking confusion (aidlc-state.md would have two entries for
  one stage)
- Session continuity breakage (stage names in state file wouldn't match
  what the rules expect)
- Mermaid diagram showing 2 nodes for a single stage

Changes:
- Merge UP/UG Mermaid nodes into single Units Generation node
- Remove duplicate Units Planning checklist items from execution plans
- Clarify that planning/generation are internal sub-steps, not stages
- Update all impact assessments and error recovery references

* docs: add full prompt engineering review TODO with 25 prioritized findings

* docs: move review TODO from repo to PR comment

---------

Co-authored-by: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com>
Co-authored-by: Leandro Damascena <lcdama@amazon.pt>

Author: scottschreckengaust

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

@@ -110,7 +110,7 @@
 
 **Error**: Cannot generate design artifacts
 - **Cause**: Missing unit information, unclear requirements
-- **Solution**: Return to Units Planning to clarify unit definition
+- **Solution**: Return to Units Generation to clarify unit definition
 - **Workaround**: Generate partial design, mark gaps
 
 ### NFR Implementation Errors

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

@@ -35,7 +35,7 @@
 - User Stories (CONDITIONAL)
 - Workflow Planning (ALWAYS)
 - Application Design (CONDITIONAL)
-- Design - Units Planning/Generation (CONDITIONAL)
+- Units Generation (CONDITIONAL)
 
 **Outputs**: Requirements, user stories, architectural decisions, unit definitions
 
@@ -79,7 +79,7 @@
 - **Reverse Engineering**: Analyzing existing codebase (brownfield projects only)
 - **User Stories**: Creating user stories and personas (includes Story Planning and Story Generation)
 - **Application Design**: Designing application components, methods, business rules, and services
-- **Design**: Designing system components (includes Units Planning, Units Generation, per-unit design)
+- **Units Generation**: Decomposing the system into units of work (includes internal planning and generation sub-steps, plus per-unit design)
 - **Functional Design**: Technology-agnostic business logic design (per-unit)
 - **NFR Requirements**: Determining NFRs and selecting tech stack (per-unit)
 - **NFR Design**: Incorporating NFR patterns and logical components (per-unit)
@@ -120,7 +120,7 @@ A reusable building block within a service or module. Components are classes, fu
 ### When to Use Each Term
 
 **Unit of Work**:
-- During Units Planning and Units Generation stages
+- During the Units Generation stage
 - When discussing system decomposition
 - In planning documents and discussions
 - Example: "How should we decompose this into units of work?"
@@ -149,11 +149,11 @@ A reusable building block within a service or module. Components are classes, fu
 - **Planning**: Creating a plan with questions and checkboxes for execution
 - **Generation**: Executing the plan to create artifacts
 
-Examples:
-- Story Planning → Story Generation
-- Units Planning → Units Generation
-- Unit Design Planning → Unit Design Generation
-- NFR Planning → NFR Generation
+Examples (these are internal sub-steps within a single stage, not separate stages):
+- Story Planning → Story Generation (within User Stories stage)
+- Units Planning → Units Generation (within Units Generation stage)
+- Unit Design Planning → Unit Design Generation (within per-unit design)
+- NFR Planning → NFR Generation (within NFR Requirements stage)
 - Code Generation Part 1 (Planning) → Code Generation Part 2 (Generation)
 
 ### Depth Levels

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

@@ -85,7 +85,7 @@ Users may request changes to the execution plan or stage 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 Generation. Confirm?"
+2. **Warn User**: "Restarting Application Design will require redoing: 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
@@ -154,8 +154,8 @@ Users may request changes to the execution plan or stage execution during the wo
 **Handling**:
 1. **Assess Current Progress**: Determine how far into workflow
 2. **Explain Impact**: 
-   - If before Units Planning: Minimal impact, just update decision
-   - If after Units Planning: Must redo Units Planning, Units Generation, all per-unit design
+   - If before Units Generation: Minimal impact, just update decision
+   - If after Units Generation: Must redo Units Generation, all per-unit design
    - If after Code Generation: Significant rework required
 3. **Recommend Approach**:
    - Early in workflow: Restart from Application Design stage

aidlc-rules/aws-aidlc-rule-details/inception/units-generation.md

@@ -97,9 +97,9 @@ If the analysis in step 7 reveals ANY ambiguous answers, you MUST:
 - Include complete approval prompt text
 
 ## Step 11: Update Progress
-- Mark Units Planning complete in aidlc-state.md
+- Mark Units Generation Part 1 (Planning) complete in aidlc-state.md
 - Update the "Current Status" section
-- Prepare for transition to Units Generation
+- Prepare for transition to Units Generation Part 2 (Generation)
 
 ---
 

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

@@ -128,7 +128,7 @@ Evaluate risk level:
 - No new components or methods
 - Pure implementation changes
 
-### 3.3 Design (Units Planning/Generation) - Execute IF:
+### 3.3 Units Generation - Execute IF:
 - New data models or schemas
 - API changes or new endpoints
 - Complex algorithms or business logic
@@ -261,8 +261,7 @@ flowchart TD
         US["User Stories<br/><b>STATUS</b>"]
         WP["Workflow Planning<br/><b>STATUS</b>"]
         AD["Application Design<br/><b>STATUS</b>"]
-        UP["Units Planning<br/><b>STATUS</b>"]
-        UG["Units Generation<br/><b>STATUS</b>"]
+        UG["Units Generation<br/>(Planning + Generation)<br/><b>STATUS</b>"]
     end
     
     subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
@@ -301,8 +300,6 @@ flowchart TD
 - [x] Execution Plan (IN PROGRESS)
 - [ ] Application Design - [EXECUTE/SKIP]
   - **Rationale**: [Why executing or skipping]
-- [ ] Units Planning - [EXECUTE/SKIP]
-  - **Rationale**: [Why executing or skipping]
 - [ ] Units Generation - [EXECUTE/SKIP]
   - **Rationale**: [Why executing or skipping]
 
@@ -367,7 +364,6 @@ Update `aidlc-docs/aidlc-state.md`:
 - [x] User Stories (if applicable)
 - [x] Workflow Planning
 - [ ] Application Design - [EXECUTE/SKIP]
-- [ ] Units Planning - [EXECUTE/SKIP]
 - [ ] Units Generation - [EXECUTE/SKIP]
 
 ### 🟢 CONSTRUCTION PHASE