plcode-darwin-x64 2.1.0

package/.plcode/context/core/context-system/guides/workflows.md

@@ -0,0 +1,598 @@
+# Context Operation Workflows
+
+**Purpose**: Detailed interactive workflows for all context operations
+
+**Last Updated**: 2026-01-06
+
+---
+
+## Extract Workflow (Interactive)
+
+### Stage 1: Read Source
+
+```
+/context extract from https://react.dev/hooks
+  ↓
+Agent: "Reading source (8,500 lines)...
+Analyzing content for extractable items..."
+```
+
+### Stage 2: Analyze & Categorize
+
+```
+Agent: "Analysis complete.
+
+Found 12 core concepts:
+  - useState (state management)
+  - useEffect (side effects)
+  - useContext (context consumption)
+  ... (9 more)
+
+Found 8 common errors:
+  - Hooks called conditionally
+  - Hooks in loops
+  - Hooks outside components
+  ... (5 more)
+
+Found 3 workflows:
+  - Setting up custom hooks
+  - Debugging hook issues
+  - Testing components with hooks"
+```
+
+### Stage 3: Select Category (APPROVAL REQUIRED)
+
+```
+Agent: "Which category should this go in?
+  [1] development/
+  [2] core/
+  [3] Create new category: ___
+
+Select items to extract:
+  Concepts:
+    ✓ [A] useState
+    ✓ [B] useEffect
+    ✓ [C] useContext
+    ... [D-L] (9 more)
+
+  Errors:
+    ✓ [M] Hooks called conditionally
+    ✓ [N] Hooks in loops
+    ... [O-T] (6 more)
+
+  Guides:
+    ✓ [U] Setting up custom hooks
+    ✓ [V] Debugging hook issues
+    ✓ [W] Testing components
+
+Type items (A B M or 'all') + category (1/2/3):"
+
+User: "all 1"
+```
+
+### Stage 4: Preview (APPROVAL REQUIRED)
+
+```
+Agent: "Would create in development/:
+
+  concepts/use-state.md (45 lines)
+  concepts/use-effect.md (52 lines)
+  concepts/use-context.md (38 lines)
+  ... (9 more concept files)
+
+  errors/react-hooks-errors.md (124 lines)
+    - 8 errors grouped in one file
+
+  guides/custom-hooks.md (87 lines)
+  guides/debugging-hooks.md (65 lines)
+  guides/testing-hooks.md (72 lines)
+
+Total: 15 files, ~850 lines
+
+Preview specific file? (type filename or 'skip')
+Approve? (yes/no/preview):"
+
+User: "preview use-state.md"
+
+Agent: [Shows first 30 lines of use-state.md]
+
+User: "yes"
+```
+
+### Stage 5-7: Create, Update, Report
+
+```
+Agent: "Creating files...
+✅ Extracted 20 items into development/
+📄 Created 15 files
+📊 Updated development/README.md
+
+Files created:
+  - development/concepts/ (12 files)
+  - development/errors/react-hooks-errors.md
+  - development/guides/ (3 files)"
+```
+
+---
+
+## Organize Workflow (Interactive)
+
+### Stage 1-2: Scan & Categorize
+
+```
+/context organize development/
+  ↓
+Agent: "Scanning development/ (23 files, flat structure)...
+
+Categorizing by function..."
+```
+
+### Stage 3: Resolve Conflicts (APPROVAL REQUIRED)
+
+```
+Agent: "Categorization plan:
+
+Clear categorization (18 files):
+  concepts/ (8 files):
+    ✓ authentication.md → concepts/authentication.md
+    ✓ state-management.md → concepts/state-management.md
+    ✓ caching.md → concepts/caching.md
+    ... (5 more)
+
+  examples/ (5 files):
+    ✓ jwt-example.md → examples/jwt-example.md
+    ✓ hooks-example.md → examples/hooks-example.md
+    ... (3 more)
+
+  guides/ (5 files):
+    ✓ setting-up-auth.md → guides/setting-up-auth.md
+    ... (4 more)
+
+Ambiguous files (5 - need your input):
+
+  [?] api-design.md (contains concepts AND step-by-step guide)
+      Content: Explains REST principles (concept) + how to design endpoints (guide)
+      → [A] Split into:
+            concepts/api-design.md (REST principles)
+            guides/api-design-guide.md (how to design)
+      → [B] Keep as concepts/api-design.md (primary: concepts)
+      → [C] Keep as guides/api-design.md (primary: guide)
+
+  [?] error-handling.md (contains guide AND error examples)
+      Content: How to handle errors (guide) + common error patterns (errors)
+      → [D] Split into:
+            guides/error-handling.md (how to handle)
+            errors/common-errors.md (error patterns)
+      → [E] Keep as guides/error-handling.md
+      → [F] Keep as errors/error-handling.md
+
+  [?] testing-patterns.md (contains concepts AND examples)
+      → [G] Split into concepts/ + examples/
+      → [H] Keep as concepts/testing-patterns.md
+      → [I] Keep as examples/testing-patterns.md
+
+Conflicts (2):
+
+  [!] authentication.md → concepts/auth.md
+      Target concepts/auth.md already exists (120 lines)
+      → [J] Merge authentication.md into existing auth.md
+      → [K] Rename to concepts/authentication-v2.md
+      → [L] Skip (keep flat)
+
+  [!] jwt-example.md → examples/jwt.md
+      Target examples/jwt.md already exists (65 lines)
+      → [M] Merge jwt-example.md into existing jwt.md
+      → [N] Rename to examples/jwt-example-v2.md
+      → [O] Skip (keep flat)
+
+Select resolutions (A D G J M or 'auto' for AI suggestions):"
+
+User: "A D G J M"
+```
+
+### Stage 4: Preview (APPROVAL REQUIRED)
+
+```
+Agent: "Preview of changes:
+
+CREATE directories:
+  development/concepts/
+  development/examples/
+  development/guides/
+  development/lookup/
+  development/errors/
+
+MOVE files (18):
+  authentication.md → concepts/authentication.md
+  state-management.md → concepts/state-management.md
+  ... (16 more)
+
+SPLIT files (3):
+  api-design.md →
+    concepts/api-design.md (concepts section)
+    guides/api-design-guide.md (guide section)
+
+  error-handling.md →
+    guides/error-handling.md (guide section)
+    errors/common-errors.md (error examples)
+
+  testing-patterns.md →
+    concepts/testing-patterns.md (concepts)
+    examples/testing-examples.md (examples)
+
+MERGE files (2):
+  authentication.md → concepts/auth.md (merge content)
+  jwt-example.md → examples/jwt.md (merge content)
+
+UPDATE:
+  development/README.md (create navigation tables)
+  Fix 47 internal references
+
+Dry-run? (yes/no/show-diff):"
+
+User: "dry-run"
+
+Agent: [Simulates changes without executing, shows what would happen]
+
+User: "yes"
+```
+
+### Stage 5-8: Backup, Execute, Update, Report
+
+```
+Agent: "Creating backup...
+💾 Backup: .tmp/backup/organize-development-2026-01-06-143022/
+
+Executing changes...
+✅ Organized 23 files into function folders
+📁 Created 5 new folders
+🔀 Split 3 ambiguous files
+🔗 Fixed 47 references
+📊 Updated development/README.md
+
+Rollback available at: .tmp/backup/organize-development-2026-01-06-143022/"
+```
+
+---
+
+## Update Workflow (Interactive)
+
+### Stage 1: Identify Changes (APPROVAL REQUIRED)
+
+```
+/context update for Next.js 15
+  ↓
+Agent: "What changed in Next.js 15?
+  [A] API changes
+  [B] Deprecations
+  [C] New features
+  [D] Breaking changes
+  [E] Other (describe)
+
+Select all that apply (A B C D or describe):"
+
+User: "A C D"
+
+Agent: "Please describe the changes:
+  API changes: ___
+  New features: ___
+  Breaking changes: ___"
+
+User: "API changes: App router is now default
+New features: New metadata API, Server Actions stable
+Breaking changes: Pages router requires explicit opt-in"
+```
+
+### Stage 2: Find Affected Files
+
+```
+Agent: "Searching for files referencing Next.js...
+
+Found 5 files with 17 references:
+  📄 concepts/routing.md (3 references, 145 lines)
+  📄 examples/app-router-example.md (7 references, 78 lines)
+  📄 guides/setting-up-nextjs.md (2 references, 132 lines)
+  📄 errors/nextjs-errors.md (1 reference, 98 lines)
+  📄 lookup/nextjs-commands.md (4 references, 54 lines)
+
+Total impact: 17 references across 5 files"
+```
+
+### Stage 3: Preview Changes (APPROVAL REQUIRED)
+
+```
+Agent: "Proposed updates:
+
+━━━ concepts/routing.md ━━━
+
+Line 15:
+  - App router is optional (use pages/ or app/ directory)
+  + App router is now default in Next.js 15 (pages/ still supported with opt-in)
+
+Line 42:
+  + ## Metadata API (New in v15)
+  +
+  + Next.js 15 introduces new metadata API for SEO optimization.
+  + Replaces Head component with metadata exports.
+
+Line 87:
+  - **Reference**: https://nextjs.org/docs/app
+  + **Reference**: https://nextjs.org/docs/15/app
+
+━━━ examples/app-router-example.md ━━━
+
+Line 8:
+  - // Optional: use app router
+  + // Default in Next.js 15+
+
+Line 23:
+  + // New: Metadata API
+  + export const metadata = {
+  +   title: 'My App',
+  +   description: 'App description'
+  + }
+
+━━━ guides/setting-up-nextjs.md ━━━
+
+Line 45:
+  - 3. Choose router: pages/ or app/
+  + 3. App router is default (use --pages flag for pages router)
+
+━━━ errors/nextjs-errors.md ━━━
+
+Line 67:
+  + ## Migration: Next.js 14 → 15
+  +
+  + **Breaking Changes**:
+  + - App router is now default
+  + - Pages router requires explicit opt-in
+  +
+  + **Migration Steps**:
+  + 1. Update to Next.js 15: `npm install next@15`
+  + 2. For pages router: Add `pages: true` to next.config.js
+  + 3. Update metadata: Replace Head with metadata exports
+  +
+  + **Reference**: https://nextjs.org/docs/15/upgrade-guide
+
+━━━ lookup/nextjs-commands.md ━━━
+
+Line 12:
+  - npx create-next-app@latest
+  + npx create-next-app@latest  # App router default
+  + npx create-next-app@latest --pages  # Pages router
+
+Preview next file? (yes/no/show-all)
+Approve changes? (yes/no/edit):"
+
+User: "edit"
+
+Agent: "Line-by-line approval mode.
+
+concepts/routing.md - Line 15 change?
+  - App router is optional (use pages/ or app/ directory)
+  + App router is now default in Next.js 15 (pages/ still supported with opt-in)
+
+Approve? (yes/no/modify):"
+
+User: "yes"
+
+[... continues for each change ...]
+```
+
+### Stage 4-8: Backup, Update, Add Migration, Validate, Report
+
+```
+Agent: "Creating backup...
+💾 Backup: .tmp/backup/update-nextjs-2026-01-06-143530/
+
+Updating files...
+✅ Updated 5 files
+📝 Modified 17 references
+🔄 Added migration notes to errors/nextjs-errors.md
+🔗 Validated all references (0 broken links)
+
+Summary of changes:
+  - concepts/routing.md: 3 updates (145 → 162 lines)
+  - examples/app-router-example.md: 4 updates (78 → 89 lines)
+  - guides/setting-up-nextjs.md: 1 update (132 → 133 lines)
+  - errors/nextjs-errors.md: Added migration section (98 → 125 lines)
+  - lookup/nextjs-commands.md: 2 updates (54 → 56 lines)
+
+All files still under 200 line limit ✓
+
+Rollback available at: .tmp/backup/update-nextjs-2026-01-06-143530/"
+```
+
+---
+
+## Error Workflow (Interactive)
+
+### Stage 1: Search Existing
+
+```
+/context error for "Cannot read property 'map' of undefined"
+  ↓
+Agent: "Searching existing errors for similar issues...
+
+Found 1 similar error:
+  📄 development/errors/react-errors.md (Line 45)
+     ## Error: Cannot read property 'X' of undefined
+     Covers: General undefined property access in React
+     Frequency: common
+
+Found 2 related errors:
+  📄 development/errors/react-errors.md
+     ## Error: Cannot read property 'length' of undefined
+     ## Error: Undefined is not an object"
+```
+
+### Stage 2: Check Duplication (APPROVAL REQUIRED)
+
+```
+Agent: "Options:
+  [A] Add as new error to react-errors.md
+      (Specific case: 'map' on undefined array)
+
+  [B] Update existing 'Cannot read property X' error
+      (Add 'map' as common example)
+
+  [C] Skip (already covered sufficiently)
+
+Which framework/category?
+  [1] React (react-errors.md)
+  [2] JavaScript (js-errors.md)
+  [3] General (common-errors.md)
+  [4] Create new: ___
+
+Select option + category (e.g., 'B 1'):"
+
+User: "B 1"
+```
+
+### Stage 3: Preview (APPROVAL REQUIRED)
+
+```
+Agent: "Would update development/errors/react-errors.md:
+
+Current (Line 45):
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## Error: Cannot read property 'X' of undefined
+
+**Symptom**:
+```
+
+TypeError: Cannot read property 'X' of undefined
+
+````
+
+**Cause**: Attempting to access property on undefined/null object.
+
+**Solution**:
+1. Add null check before accessing property
+2. Use optional chaining (?.)
+3. Provide default value
+
+**Code**:
+```jsx
+// ❌ Before
+const value = obj.property
+
+// ✅ After
+const value = obj?.property ?? 'default'
+````
+
+**Prevention**: Always validate data exists before accessing
+**Frequency**: common
+**Reference**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cant_access_property
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Proposed update:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Error: Cannot read property 'X' of undefined
+
+**Symptom**:
+
+```
+TypeError: Cannot read property 'X' of undefined
+TypeError: Cannot read property 'map' of undefined  ← NEW
+TypeError: Cannot read property 'length' of undefined  ← NEW
+```
+
+**Cause**: Attempting to access property on undefined/null object.
+Common with array methods (map, filter) when data hasn't loaded. ← NEW
+
+**Solution**:
+
+1. Add null check before accessing property
+2. Use optional chaining (?.)
+3. Provide default value (especially for arrays) ← UPDATED
+
+**Code**:
+
+```jsx
+// ❌ Before
+const value = obj.property
+const items = data.map(item => item.name)  ← NEW
+
+// ✅ After
+const value = obj?.property ?? 'default'
+const items = (data || []).map(item => item.name)  ← NEW
+// Or with optional chaining:
+const items = data?.map(item => item.name) ?? []  ← NEW
+```
+
+**Prevention**: Always validate data exists before accessing.
+For arrays, provide empty array default. ← UPDATED
+
+**Frequency**: common
+**Reference**: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cant_access_property
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File size: 98 lines → 105 lines (under 150 limit ✓)
+
+Approve? (yes/no/edit):"
+
+User: "yes"
+
+```
+
+### Stage 4-6: Add, Update, Report
+```
+
+Agent: "Updating development/errors/react-errors.md...
+
+✅ Updated error in development/errors/react-errors.md
+🔗 Cross-referenced with 2 related errors
+📊 File size: 105 lines (under 150 limit)
+
+Changes:
+
+- Added 'map' and 'length' to symptom examples
+- Updated cause to mention array methods
+- Added array-specific code examples
+- Updated prevention guidance"
+
+```
+
+---
+
+## Common Patterns
+
+### Approval Gates
+All operations with `enforce="@critical_rules.approval_gate"` MUST:
+1. Show clear preview of what will happen
+2. Wait for explicit user input
+3. Provide options (yes/no/edit/preview/dry-run)
+4. Never proceed without confirmation
+
+### Conflict Resolution
+When conflicts detected:
+1. Present all options clearly
+2. Use letter-based selection (A/B/C)
+3. Show impact of each option
+4. Allow user to choose resolution
+
+### Previews
+All previews should show:
+1. What will be created/modified/deleted
+2. File sizes (before → after)
+3. Line-by-line diffs for updates
+4. Validation status (under limits, no broken links)
+
+### Backups
+Operations that modify files MUST:
+1. Create backup before changes
+2. Store in `.tmp/backup/{operation}-{topic}-{timestamp}/`
+3. Report backup location
+4. Keep backups for rollback
+
+---
+
+## Related
+
+- context.md - Main command interface
+- harvest.md - Harvest workflow details
+- mvi-principle.md - What to extract
+- compact.md - How to minimize
+```