groundswell 0.0.2 → 0.0.3

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M3T2S1/PRP.md

@@ -1,719 +0,0 @@
-# Product Requirement Prompt (PRP): P1.M3.T2.S1 - Analyze Tree Debugger onTreeChanged Implementation
-
-**PRP ID**: P1M3T2S1
-**Task ID**: P1.M3.T2.S1
-**Story Points**: 1
-**Status**: Researching
-**Created**: 2025-01-12
-
----
-
-## Goal
-
-**Feature Goal**: Conduct a comprehensive analysis of the WorkflowTreeDebugger's `onTreeChanged()` implementation to understand the current full-rebuild behavior and identify opportunities for incremental updates.
-
-**Deliverable**: Analysis document stored at `plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md` containing:
-- Current rebuild logic documentation with line number references
-- Tree change event type analysis (childAttached, childDetached, treeUpdated)
-- Performance impact assessment for current O(n) rebuild behavior
-- Identified opportunities for incremental O(1)/O(k) updates
-- Recommendations for P1.M3.T2.S2 implementation
-
-**Success Definition**:
-- [ ] Analysis document exists at specified path
-- [ ] Current implementation behavior fully documented with code references
-- [ ] All tree change trigger events identified and documented
-- [ ] Performance bottleneck clearly explained with complexity analysis
-- [ ] Incremental update opportunities identified with specific recommendations
-- [ ] Research findings stored in research/ subdirectory for P1.M3.T2.S2 reference
-
----
-
-## User Persona (if applicable)
-
-**Target User**: Implementation AI agent for P1.M3.T2.S2 and P1.M3.T2.S3
-
-**Use Case**: The analysis document serves as the foundation for implementing incremental node map updates (P1.M3.T2.S2) and creating benchmark tests (P1.M3.T2.S3).
-
-**User Journey**:
-1. Read analysis document to understand current behavior
-2. Use identified opportunities to implement incremental updates
-3. Reference performance analysis for benchmark test design
-4. Validate implementation against recommendations
-
-**Pain Points Addressed**:
-- Eliminates need for P1.M3.T2.S2 agent to rediscover current implementation
-- Provides concrete recommendations backed by research
-- Accelerates implementation by providing clear guidance
-
----
-
-## Why
-
-- **Performance Optimization**: Current O(n) full rebuild on every tree change is inefficient for large workflow trees (1000+ nodes)
-- **Foundation for Implementation**: Analysis enables P1.M3.T2.S2 to implement incremental updates without additional research overhead
-- **Informed Benchmark Design**: Performance assessment informs P1.M3.T2.S3 benchmark test design
-- **Documentation**: Creates permanent record of optimization rationale for future maintainers
-
-**Business Value**:
-- Reduces node map update overhead from O(n) to O(1) for single-node operations
-- Enables 100-1000× performance improvement for large trees with frequent structural changes
-- Prevents garbage collection pressure from Map.clear() and full rebuild
-- Maintains correctness while improving performance
-
----
-
-## What
-
-**User-Visible Behavior**: No behavior change - this is a research and analysis task only.
-
-**Technical Requirements**:
-- Read and analyze `src/debugger/tree-debugger.ts` implementation
-- Read and analyze `src/core/workflow.ts` emitEvent and observer notification logic
-- Document all tree change events that trigger `onTreeChanged()`
-- Map current rebuild logic with specific line number references
-- Calculate time complexity of current operations
-- Research incremental update patterns
-- Document specific opportunities for optimization
-
-### Success Criteria
-
-- [ ] Analysis document contains complete current implementation documentation
-- [ ] All three tree change events (childAttached, childDetached, treeUpdated) documented
-- [ ] Performance impact quantified with complexity analysis
-- [ ] At least 3 specific incremental update opportunities identified
-- [ ] Recommendations include code pattern examples
-- [ ] External research cited with specific URLs
-
----
-
-## All Needed Context
-
-### Context Completeness Check
-
-**"No Prior Knowledge" Test**: If someone knew nothing about this codebase, would they have everything needed to conduct this analysis successfully?
-
-**Answer**: YES - This PRP provides:
-- Exact file paths and line numbers for all relevant code
-- Complete WorkflowNode and WorkflowEvent type definitions
-- Observer pattern documentation
-- Testing framework patterns
-- External research with specific URLs
-- Output template for analysis document
-
-### Documentation & References
-
-```yaml
-# MUST READ - Code Files (read in order)
-
-- file: src/debugger/tree-debugger.ts
-  why: Core implementation to analyze - contains onTreeChanged(), buildNodeMap(), onEvent(), nodeMap
-  lines: "53-84" # buildNodeMap() and onTreeChanged() implementation
-  pattern: Recursive tree traversal using for-of loop over node.children
-  gotcha: "onEvent() at line 66-74 already handles childAttached incrementally - onTreeChanged() redundant"
-
-- file: src/core/workflow.ts
-  why: Understanding when onTreeChanged is called via emitEvent()
-  lines: "360-379" # emitEvent() method showing observer notification logic
-  pattern: "obs.onTreeChanged(this.getRoot().node) called for childAttached, childDetached, treeUpdated events"
-  gotcha: "onTreeChanged called AFTER onEvent - causing redundant work for childAttached"
-
-- file: src/types/workflow.ts
-  why: WorkflowNode structure definition - needed to understand tree hierarchy
-  lines: "16-37" # Complete WorkflowNode interface
-  pattern: "id, name, parent, children[], status, logs[], events[], stateSnapshot"
-  gotcha: "parent is WorkflowNode | null - null for root nodes"
-
-- file: src/types/events.ts
-  why: WorkflowEvent discriminated union - all tree change event types
-  lines: "8-18" # Core workflow events including childAttached, childDetached, treeUpdated
-  pattern: "type: 'childAttached' | 'childDetached' | 'treeUpdated' are tree structure change events"
-  gotcha: "childDetached only provides childId string, not full child node"
-
-- file: src/types/observer.ts
-  why: WorkflowObserver interface defining onTreeChanged signature
-  lines: "9-18" # Complete WorkflowObserver interface
-  pattern: "onTreeChanged(root: WorkflowNode): void - receives root node after any tree change"
-  gotcha: "Called for ALL tree events including state changes (via treeUpdated)"
-
-# EXTERNAL RESEARCH - Read for best practices and patterns
-
-- url: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#instance-methods
-  why: Map.set(), Map.get(), Map.delete() are O(1) - validates incremental approach feasibility
-  critical: "Map operations have O(1) average case complexity - incremental updates faster than O(n) rebuild"
-
-- url: https://react.dev/learn/understanding-reacts-render-phase#rendering-and-committing
-  why: React reconciliation algorithm - tree diffing strategy reference
-  critical: "React only updates changed subtrees - same principle applies to node map updates"
-
-- url: https://v8.dev/blog/elements-kinds#hidden-classes
-  why: V8 Map optimization and garbage collection behavior
-  critical: "Map.clear() triggers full GC - incremental updates spread GC cost over time"
-
-- url: https://stackoverflow.com/questions/38476433/what-is-the-time-complexity-of-map-set-in-javascript#answer-38476768
-  why: Confirmed O(1) complexity for Map operations
-  critical: "Map.set() and Map.delete() are O(1) on average in modern JavaScript engines"
-
-# INTERNAL RESEARCH - Generated research package
-
-- docfile: plan/001_d3bb02af4886/docs/research/incremental-tree-map-updates/QUICK_REFERENCE.md
-  why: Code examples and implementation patterns for incremental updates
-  section: "Code Examples - Incremental Update Pattern"
-
-- docfile: plan/001_d3bb02af4886/docs/research/incremental-tree-map-updates/RESEARCH_REPORT.md
-  why: Comprehensive analysis of current implementation and recommended patterns
-  section: "Current Implementation Analysis" and "Recommended Implementation"
-
-- docfile: plan/001_d3bb02af4886/bugfix/architecture/codebase_structure.md
-  why: Overall codebase architecture and dual tree structure
-  section: "7. Observer Pattern Implementation" and "8. Additional Architecture Patterns"
-
-# TEST PATTERNS - For validation approach
-
-- file: src/__tests__/unit/tree-debugger.test.ts
-  why: Existing test patterns for tree-debugger functionality
-  pattern: "WorkflowTreeDebugger instantiation, getNode() lookup, tree string rendering"
-  gotcha: "Tests verify nodeMap behavior - useful for validating incremental correctness"
-
-- file: src/__tests__/integration/tree-mirroring.test.ts
-  why: Observer propagation and treeUpdated event testing
-  pattern: "treeUpdated events trigger onTreeChanged callback"
-  gotcha: "Test at lines 115-150 verifies onTreeChanged is called with correct root"
-```
-
-### Current Codebase Tree (relevant portions)
-
-```
-src/
-├── debugger/
-│   └── tree-debugger.ts          # PRIMARY ANALYSIS TARGET
-│       ├── WorkflowTreeDebugger class
-│       ├── buildNodeMap()         # Line 53-58 - O(n) recursive rebuild
-│       ├── onEvent()              # Line 66-74 - handles childAttached incrementally
-│       ├── onTreeChanged()        # Line 80-84 - O(n) full rebuild (OPTIMIZE TARGET)
-│       └── nodeMap: Map           # Line 33 - node lookup map
-├── core/
-│   └── workflow.ts                # Event emission logic
-│       ├── emitEvent()            # Line 363-379 - triggers onTreeChanged
-│       ├── attachChild()          # Line 266-305 - childAttached trigger
-│       └── detachChild()          # Line 329-358 - childDetached trigger
-├── types/
-│   ├── workflow.ts                # WorkflowNode interface
-│   ├── events.ts                  # WorkflowEvent discriminated union
-│   └── observer.ts                # WorkflowObserver interface
-└── __tests__/
-    ├── unit/
-    │   └── tree-debugger.test.ts  # Existing test patterns
-    └── integration/
-        └── tree-mirroring.test.ts # Observer propagation tests
-```
-
-### Known Gotchas of Our Codebase & Library Quirks
-
-```typescript
-// CRITICAL: onEvent() and onTreeChanged() are BOTH called for tree changes
-// From src/core/workflow.ts:372-374
-if (event.type === 'treeUpdated' || event.type === 'childAttached' || event.type === 'childDetached') {
-  obs.onTreeChanged(this.getRoot().node);  // ❌ This triggers full rebuild
-}
-
-// CRITICAL: onEvent() already handles childAttached incrementally
-// From src/debugger/tree-debugger.ts:66-70
-onEvent(event: WorkflowEvent): void {
-  if (event.type === 'childAttached') {
-    this.buildNodeMap(event.child);  // ✅ Already incremental!
-  }
-  // Then onTreeChanged() is called, causing REDUNDANT full rebuild
-}
-
-// CRITICAL: childDetached only provides childId, not full node
-// From src/types/events.ts:11
-{ type: 'childDetached'; parentId: string; childId: string }
-// Must use stored node reference to collect descendants for removal
-
-// CRITICAL: buildNodeMap() is recursive - may hit call stack limits on deep trees
-// From src/debugger/tree-debugger.ts:53-58
-private buildNodeMap(node: WorkflowNode): void {
-  this.nodeMap.set(node.id, node);
-  for (const child of node.children) {
-    this.buildNodeMap(child);  // Recursive call
-  }
-}
-
-// CRITICAL: treeUpdated is called for non-structural changes
-// From src/core/workflow.ts:414
-this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
-// Called by setStatus() - NO tree structure change, just status update
-// Current implementation rebuilds entire map for status changes!
-```
-
----
-
-## Implementation Blueprint
-
-### Data Models and Structure
-
-**No data model changes** - This is a research task only.
-
-**Data structures to analyze**:
-
-```typescript
-// From src/types/workflow.ts:20-37
-interface WorkflowNode {
-  id: string;                  // Unique identifier
-  name: string;                // Human-readable name
-  parent: WorkflowNode | null; // Parent reference (null for root)
-  children: WorkflowNode[];    // Child nodes (tree structure)
-  status: WorkflowStatus;      // Current execution state
-  logs: LogEntry[];            // Log entries
-  events: WorkflowEvent[];     // Emitted events
-  stateSnapshot: SerializedWorkflowState | null; // State snapshot
-}
-
-// Tree structure maintained by debugger:
-// - this.root: WorkflowNode (root node reference)
-// - this.nodeMap: Map<string, WorkflowNode> (id -> node lookup)
-```
-
-### Implementation Tasks (ordered by dependencies)
-
-```yaml
-Task 1: READ and document current implementation
-  - READ: src/debugger/tree-debugger.ts lines 53-84 (buildNodeMap, onTreeChanged)
-  - READ: src/debugger/tree-debugger.ts lines 66-74 (onEvent childAttached handling)
-  - DOCUMENT: Current rebuild logic in analysis.md
-  - IDENTIFY: Time complexity of buildNodeMap() - O(n) where n = total nodes
-  - IDENTIFY: Redundant work - childAttached handled in both onEvent() AND onTreeChanged()
-  - OUTPUT: Section "Current Implementation" in analysis.md
-
-Task 2: ANALYZE tree change event types
-  - READ: src/types/events.ts lines 8-18 (core workflow events)
-  - READ: src/core/workflow.ts lines 360-379 (emitEvent observer notification)
-  - IDENTIFY: Three events trigger onTreeChanged:
-    1. childAttached - new subtree added
-    2. childDetached - subtree removed (only childId provided)
-    3. treeUpdated - root reference or status change
-  - DOCUMENT: For each event:
-    - When it occurs
-    - What data it provides
-    - Current onTreeChanged behavior
-    - Optimal incremental behavior
-  - OUTPUT: Section "Tree Change Event Analysis" in analysis.md
-
-Task 3: CALCULATE performance impact
-  - CALCULATE: Current complexity per event type
-    - childAttached: O(n) - rebuilds entire map
-    - childDetached: O(n) - rebuilds entire map
-    - treeUpdated: O(n) - rebuilds entire map
-  - CALCULATE: Potential incremental complexity
-    - childAttached: O(k) where k = nodes in new subtree (already implemented in onEvent)
-    - childDetached: O(k) where k = nodes in removed subtree
-    - treeUpdated: O(1) - just update root reference
-  - CALCULATE: Speedup potential
-    - Single node attach to 1000-node tree: 1000× faster (O(1000) → O(1))
-    - Single node detach from 1000-node tree: 100× faster (O(1000) → O(10))
-    - Root status update: 1000× faster (O(1000) → O(1))
-  - OUTPUT: Section "Performance Impact Analysis" in analysis.md
-
-Task 4: IDENTIFY incremental update opportunities
-  - RESEARCH: Read plan/001_d3bb02af4886/docs/research/incremental-tree-map-updates/
-  - IDENTIFY: Opportunity 1 - Remove redundant childAttached rebuild
-    - onEvent() already adds new subtree
-    - onTreeChanged() rebuild is redundant work
-  - IDENTIFY: Opportunity 2 - Implement childDetached subtree removal
-    - Use stored node reference to collect descendants
-    - Remove collected node IDs from map
-  - IDENTIFY: Opportunity 3 - Replace treeUpdated full rebuild
-    - Just update this.root reference
-    - Node references in map unchanged
-  - IDENTIFY: Opportunity 4 - Eliminate onTreeChanged rebuild entirely
-    - All tree changes can be handled incrementally in onEvent()
-  - OUTPUT: Section "Incremental Update Opportunities" in analysis.md
-
-Task 5: CREATE implementation recommendations
-  - DOCUMENT: Specific code changes for P1.M3.T2.S2
-    - Add handleChildDetached() method with BFS subtree collection
-    - Modify onEvent() to handle childDetached
-    - Remove full rebuild from onTreeChanged()
-  - DOCUMENT: Code pattern examples (from research package)
-    - BFS-based subtree removal
-    - Incremental update pattern
-  - DOCUMENT: Gotchas to avoid
-    - Must remove entire subtree, not just detached node
-    - Must handle case where node already removed from map
-    - Recursive removal may hit stack limits - use iterative BFS
-  - OUTPUT: Section "Implementation Recommendations" in analysis.md
-
-Task 6: STORE research for P1.M3.T2.S2 and P1.M3.T2.S3
-  - CREATE: plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/research/ directory
-  - COPY: External research URLs with annotations
-  - STORE: Code pattern examples for incremental updates
-  - STORE: Performance benchmark template for P1.M3.T2.S3
-  - OUTPUT: research/README.md with links to all resources
-```
-
-### Implementation Patterns & Key Details
-
-```typescript
-// Current Implementation (to analyze and document)
-
-// From src/debugger/tree-debugger.ts:53-58
-private buildNodeMap(node: WorkflowNode): void {
-  // PATTERN: Recursive DFS traversal
-  this.nodeMap.set(node.id, node);
-  for (const child of node.children) {
-    this.buildNodeMap(child);  // RECURSIVE - may hit stack limits
-  }
-  // COMPLEXITY: O(n) where n = total nodes in tree
-  // SIDE EFFECT: Replaces entire map content
-}
-
-// From src/debugger/tree-debugger.ts:66-74
-onEvent(event: WorkflowEvent): void {
-  // PATTERN: Event-type dispatch
-  if (event.type === 'childAttached') {
-    this.buildNodeMap(event.child);  // ✅ Already adds new subtree
-  }
-  // GOTCHA: No handling for childDetached - leaks orphaned nodes
-
-  this.events.next(event);
-  // GOTCHA: After onEvent returns, emitEvent() calls onTreeChanged()
-}
-
-// From src/debugger/tree-debugger.ts:80-84
-onTreeChanged(root: WorkflowNode): void {
-  // PATTERN: Complete map invalidation
-  this.root = root;
-  this.nodeMap.clear();        // ❌ Clears entire map
-  this.buildNodeMap(root);     // ❌ O(n) rebuild from scratch
-  // PROBLEM: Redundant work for childAttached (already handled in onEvent)
-  // PROBLEM: Unnecessary for treeUpdated (node references unchanged)
-}
-
-// Recommended Incremental Pattern (for recommendations section)
-
-onEvent(event: WorkflowEvent): void {
-  switch (event.type) {
-    case 'childAttached':
-      // ✅ Keep existing logic - already optimal
-      this.buildNodeMap(event.child);
-      break;
-
-    case 'childDetached':
-      // ✅ NEW: Incremental subtree removal
-      this.removeSubtree(event.childId);
-      break;
-
-    case 'treeUpdated':
-      // ✅ NEW: Just update root reference
-      this.root = event.root;
-      break;
-  }
-  this.events.next(event);
-}
-
-// BFS-based subtree removal (recommended over recursive)
-private removeSubtree(nodeId: string): void {
-  const node = this.nodeMap.get(nodeId);
-  if (!node) return;
-
-  // Collect all descendants using BFS (avoid stack overflow)
-  const toRemove: string[] = [];
-  const queue = [node];
-
-  while (queue.length > 0) {
-    const current = queue.shift()!;
-    toRemove.push(current.id);
-    queue.push(...current.children);
-  }
-
-  // Remove all collected nodes
-  for (const id of toRemove) {
-    this.nodeMap.delete(id);
-  }
-  // COMPLEXITY: O(k) where k = nodes in removed subtree
-}
-
-onTreeChanged(root: WorkflowNode): void {
-  // ✅ No longer needed - all updates handled in onEvent()
-  this.root = root;
-}
-```
-
-### Integration Points
-
-```yaml
-WORKFLOW EMIT EVENT:
-  - file: src/core/workflow.ts:363-379
-  - pattern: "emitEvent() calls obs.onEvent() then obs.onTreeChanged()"
-  - gotcha: "Both observers called for same event - causes redundant work"
-
-EVENT TYPES:
-  - file: src/types/events.ts:10-18
-  - pattern: "Discriminated union with type field"
-  - gotcha: "childDetached only provides childId, not full node"
-
-OBSERVER PATTERN:
-  - file: src/core/workflow.ts:124-139
-  - pattern: "getRootObservers() traverses parent chain"
-  - gotcha: "Uses visited Set for cycle detection"
-```
-
----
-
-## Validation Loop
-
-### Level 1: Completeness Check (Immediate Feedback)
-
-```bash
-# Verify analysis document exists
-test -f plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Analysis document exists: $?"
-
-# Verify document contains all required sections
-grep -q "Current Implementation" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Current Implementation section exists: $?"
-
-grep -q "Tree Change Event Analysis" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Event Analysis section exists: $?"
-
-grep -q "Performance Impact Analysis" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Performance Analysis section exists: $?"
-
-grep -q "Incremental Update Opportunities" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Opportunities section exists: $?"
-
-grep -q "Implementation Recommendations" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Recommendations section exists: $?"
-
-# Expected: All checks return 0 (true)
-```
-
-### Level 2: Content Quality Validation
-
-```bash
-# Verify line number references are accurate
-grep -n "onTreeChanged" src/debugger/tree-debugger.ts
-# Expected: Line 80 shows onTreeChanged method
-
-grep -n "buildNodeMap" src/debugger/tree-debugger.ts
-# Expected: Line 53 shows buildNodeMap method
-
-grep -n "childAttached\|childDetached\|treeUpdated" src/types/events.ts
-# Expected: Lines 10-18 show event definitions
-
-# Verify analysis document contains code references
-grep -q "src/debugger/tree-debugger.ts:80-84" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Line number references present: $?"
-
-# Verify complexity analysis present
-grep -q "O(n)\|O(1)\|O(k)" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Complexity analysis present: $?"
-
-# Verify external research cited
-grep -q "https://" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "External references cited: $?"
-```
-
-### Level 3: Research Artifact Validation
-
-```bash
-# Verify research directory exists
-test -d plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/research
-echo "Research directory exists: $?"
-
-# Verify research README exists
-test -f plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/research/README.md
-echo "Research README exists: $?"
-
-# Verify README contains link to main research package
-grep -q "incremental-tree-map-updates" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/research/README.md
-echo "Research package linked: $?"
-```
-
-### Level 4: Readiness for P1.M3.T2.S2 Validation
-
-```bash
-# Verify recommendations are actionable
-grep -q "addSubtree\|removeSubtree\|handleChildDetached" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Actionable method names present: $?"
-
-# Verify code examples provided
-grep -q "```typescript" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Code examples present: $?"
-
-# Verify gotchas documented
-grep -q "GOTCHA\|gotcha\|WARNING" plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/P1M3T2S1/analysis.md
-echo "Gotchas documented: $?"
-```
-
----
-
-## Final Validation Checklist
-
-### Technical Validation
-
-- [ ] Analysis document exists at correct path
-- [ ] All required sections completed (Current Implementation, Event Analysis, Performance, Opportunities, Recommendations)
-- [ ] Line number references accurate and verifiable
-- [ ] Complexity analysis includes O(n), O(1), O(k) notations
-- [ ] External research URLs cited with annotations
-- [ ] Code pattern examples included for each recommendation
-
-### Content Quality Validation
-
-- [ ] Current implementation behavior fully documented
-- [ ] All three tree change events (childAttached, childDetached, treeUpdated) analyzed
-- [ ] Performance impact quantified with specific complexity values
-- [ ] Redundant work identified (onEvent + onTreeChanged for childAttached)
-- [ ] At least 3 specific optimization opportunities identified
-- [ ] Implementation recommendations include specific method names and patterns
-
-### Research Artifact Validation
-
-- [ ] research/ directory created
-- [ ] research/README.md exists with links to external resources
-- [ ] Code pattern examples stored for P1.M3.T2.S2 reference
-- [ ] Benchmark template provided for P1.M3.T2.S3
-
-### P1.M3.T2.S2 Readiness Validation
-
-- [ ] Recommendations enable implementation without additional research
-- [ ] Specific method signatures provided (removeSubtree, handleChildDetached)
-- [ ] Code examples follow existing codebase patterns
-- [ ] Gotchas and anti-patterns documented to avoid
-- [ ] Performance expectations quantified for validation
-
----
-
-## Anti-Patterns to Avoid
-
-- ❌ Don't implement code changes - this is a research task only
-- ❌ Don't skip external research - use provided URLs for validation
-- ❌ Don't omit line number references - P1.M3.T2.S2 needs exact locations
-- ❌ Don't ignore the redundancy between onEvent() and onTreeChanged()
-- ❌ Don't forget that childDetached only provides childId, not full node
-- ❌ Don't recommend recursive subtree removal - use iterative BFS to avoid stack limits
-- ❌ Don't omit complexity analysis - quantitative comparison essential
-- ❌ Don't forget to document the treeUpdated case - root reference changes only
-
----
-
-## Output Template
-
-The analysis document should follow this structure:
-
-```markdown
-# Tree Debugger onTreeChanged Implementation Analysis
-
-## Current Implementation
-
-### buildNodeMap() - Line 53-58
-[Code snippet and analysis]
-
-### onEvent() - Line 66-74
-[Code snippet and analysis]
-
-### onTreeChanged() - Line 80-84
-[Code snippet and analysis]
-
-## Tree Change Event Analysis
-
-### childAttached Event
-- When: Called by attachChild() after child added to workflow.children and node.children
-- Data: { type: 'childAttached', parentId: string, child: WorkflowNode }
-- Current behavior: Added in onEvent(), then entire map rebuilt in onTreeChanged()
-- Optimal behavior: Just add in onEvent(), skip onTreeChanged() rebuild
-
-### childDetached Event
-[Similar analysis]
-
-### treeUpdated Event
-[Similar analysis]
-
-## Performance Impact Analysis
-
-### Current Complexity
-- childAttached: O(n)
-- childDetached: O(n)
-- treeUpdated: O(n)
-
-### Incremental Complexity
-- childAttached: O(k) already implemented
-- childDetached: O(k) - needs implementation
-- treeUpdated: O(1) - needs implementation
-
-### Speedup Potential
-[Table with specific speedup calculations]
-
-## Incremental Update Opportunities
-
-### Opportunity 1: Eliminate Redundant childAttached Rebuild
-[Description and recommendation]
-
-### Opportunity 2: Implement childDetached Subtree Removal
-[Description with code pattern]
-
-### Opportunity 3: Replace treeUpdated Full Rebuild
-[Description with code pattern]
-
-### Opportunity 4: Remove onTreeChanged Rebuild Entirely
-[Description with code pattern]
-
-## Implementation Recommendations
-
-### For P1.M3.T2.S2: Add removeSubtree() Method
-[Specific implementation guidance]
-
-### For P1.M3.T2.S2: Modify onEvent() to Handle childDetached
-[Specific implementation guidance]
-
-### For P1.M3.T2.S2: Simplify onTreeChanged()
-[Specific implementation guidance]
-
-### Gotchas to Avoid
-[List of potential issues]
-
-## References
-
-### External Research
-[Links to MDN, React docs, V8 blog, StackOverflow]
-
-### Internal Research
-[Links to research package files]
-
-### Code Files Referenced
-[Links to specific files with line numbers]
-```
-
----
-
-## Appendix: Research Summary
-
-### Research Package Location
-
-`plan/001_d3bb02af4886/docs/research/incremental-tree-map-updates/`
-
-### Key Files
-
-- `QUICK_REFERENCE.md` - Code examples and patterns
-- `RESEARCH_REPORT.md` - Comprehensive analysis
-- `SUMMARY.md` - Executive summary
-- `PRP_TEMPLATE.md` - Implementation PRP template
-
-### Expected P1.M3.T2.S2 Output
-
-After this analysis, P1.M3.T2.S2 should implement:
-
-1. `removeSubtree(nodeId: string)` - BFS-based subtree removal
-2. Modified `onEvent()` - Handle childDetached
-3. Simplified `onTreeChanged()` - Remove full rebuild
-
-Expected performance improvement: **100-1000× faster** for large trees.
-
----
-
-**PRP Version**: 1.0
-**Last Updated**: 2025-01-12
-**Next PRP**: P1.M3.T2.S2 (Implementation)
-**Dependencies**: None (research task)