docs: add visual before/after comparison for output structure

- Clear side-by-side comparison of current vs proposed structure - Safety indicators (safe vs dangerous operations) - Command output examples showing the improvements - User experience improvements with concrete examples - Performance impact analysis - Timeline and decision framework - Complements OUTPUT_DIRECTORY_REORGANIZATION.md with visual summary
docs: comprehensive output directory reorganization recommendations
2026-02-10 02:24:35 +08:00 · 2025-11-20 09:20:43 +00:00 · 2025-11-20 09:19:20 +00:00 · 2025-11-20 09:06:21 +00:00
3 changed files with 1432 additions and 0 deletions
--- a/COMMAND_AMBIGUITY_ANALYSIS.md
+++ b/COMMAND_AMBIGUITY_ANALYSIS.md
@@ -0,0 +1,374 @@
+# Command Ambiguity Analysis
+
+## Executive Summary
+
+Analysis of 74 commands reveals **5 major ambiguity clusters** that could cause user confusion. The primary issues involve overlapping functionality in planning, execution, and analysis commands, with inconsistent parameter usage and unclear decision criteria.
+
+---
+
+## Critical Ambiguities (HIGH Priority)
+
+### 1. Planning Command Overload ⚠️ CRITICAL
+
+**Problem**: 5 different "plan" commands with overlapping but distinct purposes
+
+| Command | Purpose | Outputs | Mode |
+|---------|---------|---------|------|
+| `/workflow:plan` | 5-phase planning workflow | IMPL_PLAN.md + task JSONs | Autonomous |
+| `/workflow:lite-plan` | Lightweight interactive planning | In-memory plan | Interactive |
+| `/workflow:replan` | Modify existing plans | Updates existing artifacts | Interactive |
+| `/cli:mode:plan` | Architecture planning | .chat/plan-*.md | Read-only |
+| `/cli:discuss-plan` | Multi-round collaborative planning | .chat/discuss-plan-*.md | Multi-model discussion |
+
+**Ambiguities**:
+- ❌ **Intent confusion**: Users don't know which to use for "planning"
+- ❌ **Output confusion**: Some create tasks, some don't
+- ❌ **Workflow confusion**: Different levels of automation
+- ❌ **Scope confusion**: Project-level vs architecture-level vs modification planning
+
+**User Questions**:
+- "I want to plan my project - which command do I use?"
+- "What's the difference between `/workflow:plan` and `/workflow:lite-plan`?"
+- "When should I use `/cli:mode:plan` vs `/workflow:plan`?"
+
+**Recommendations**:
+1. ✅ Create decision tree documentation
+2. ✅ Rename commands to clarify scope:
+   - `/workflow:plan` → `/workflow:project-plan` (full workflow)
+   - `/workflow:lite-plan` → `/workflow:quick-plan` (fast planning)
+   - `/cli:mode:plan` → `/cli:architecture-plan` (read-only)
+3. ✅ Add command hints in descriptions about when to use each
+
+---
+
+### 2. Execution Command Confusion ⚠️ CRITICAL
+
+**Problem**: 5 different "execute" commands with different behaviors
+
+| Command | Input | Modifies Code | Auto-Approval | Context |
+|---------|-------|---------------|---------------|---------|
+| `/workflow:execute` | Session | Via agents | No | Full workflow |
+| `/workflow:lite-execute` | Plan/prompt/file | Via agent/codex | User choice | Lightweight |
+| `/cli:execute` | Description/task-id | YES | YOLO | Direct implementation |
+| `/cli:codex-execute` | Description | YES | YOLO | Multi-stage Codex |
+| `/task:execute` | task-id | Via agent | No | Single task |
+
+**Ambiguities**:
+- ❌ **Safety confusion**: Some have YOLO auto-approval, others don't
+- ❌ **Input confusion**: Different input formats
+- ❌ **Scope confusion**: Workflow vs task vs direct execution
+- ❌ **Tool confusion**: Agent vs CLI tool execution
+
+**Critical Risk**:
+- Users may accidentally use `/cli:execute` (YOLO) when they meant `/workflow:execute` (controlled)
+- This could result in unwanted code modifications
+
+**User Questions**:
+- "I have a workflow session - do I use `/workflow:execute` or `/task:execute`?"
+- "What's the difference between `/cli:execute` and `/workflow:lite-execute`?"
+- "Which execute command is safest for production code?"
+
+**Recommendations**:
+1. 🚨 Add safety warnings to YOLO commands
+2. ✅ Clear documentation on execution modes:
+   - **Workflow execution**: `/workflow:execute` (controlled, session-based)
+   - **Quick execution**: `/workflow:lite-execute` (flexible input)
+   - **Direct implementation**: `/cli:execute` (⚠️ YOLO auto-approval)
+3. ✅ Consider renaming:
+   - `/cli:execute` → `/cli:implement-auto` (emphasizes auto-approval)
+   - `/cli:codex-execute` → `/cli:codex-multi-stage`
+
+---
+
+### 3. Analysis Command Overlap ⚠️ MEDIUM
+
+**Problem**: Multiple analysis commands with unclear distinctions
+
+| Command | Tool | Purpose | Output |
+|---------|------|---------|--------|
+| `/cli:analyze` | Gemini/Qwen/Codex | General codebase analysis | .chat/analyze-*.md |
+| `/cli:mode:code-analysis` | Gemini/Qwen/Codex | Execution path tracing | .chat/code-analysis-*.md |
+| `/cli:mode:bug-diagnosis` | Gemini/Qwen/Codex | Bug root cause analysis | .chat/bug-diagnosis-*.md |
+| `/cli:chat` | Gemini/Qwen/Codex | Q&A interaction | .chat/chat-*.md |
+
+**Ambiguities**:
+- ❌ **Use case overlap**: When to use general analysis vs specialized modes
+- ❌ **Template confusion**: Different templates but similar outputs
+- ❌ **Mode naming**: "mode" prefix adds extra layer of confusion
+
+**User Questions**:
+- "Should I use `/cli:analyze` or `/cli:mode:code-analysis` to understand this code?"
+- "What's special about the 'mode' commands?"
+
+**Recommendations**:
+1. ✅ Consolidate or clarify:
+   - Keep `/cli:analyze` for general use
+   - Document `/cli:mode:*` as specialized templates
+2. ✅ Add use case examples in descriptions
+3. ✅ Consider flattening:
+   - `/cli:mode:code-analysis` → `/cli:trace-execution`
+   - `/cli:mode:bug-diagnosis` → `/cli:diagnose-bug`
+
+---
+
+## Medium Priority Ambiguities
+
+### 4. Task vs Workflow Command Overlap
+
+**Problem**: Parallel command hierarchies
+
+**Workflow Commands**:
+- `/workflow:plan` - Create workflow with tasks
+- `/workflow:execute` - Execute all tasks
+- `/workflow:replan` - Modify workflow
+
+**Task Commands**:
+- `/task:create` - Create individual task
+- `/task:execute` - Execute single task
+- `/task:replan` - Modify task
+
+**Ambiguities**:
+- ❌ **Scope confusion**: When to use workflow vs task commands
+- ❌ **Execution confusion**: `/task:execute` vs `/workflow:execute`
+
+**Recommendations**:
+1. ✅ Document relationship clearly:
+   - Workflow commands: Multi-task orchestration
+   - Task commands: Single-task operations
+2. ✅ Add cross-references in documentation
+
+---
+
+### 5. Tool Selection Confusion (`--tool` flag)
+
+**Problem**: Many commands accept `--tool codex|gemini|qwen` without clear criteria
+
+**Commands with --tool**:
+- `/cli:execute --tool`
+- `/cli:analyze --tool`
+- `/cli:mode:plan --tool`
+- `/memory:update-full --tool`
+- And more...
+
+**Ambiguities**:
+- ❌ **Selection criteria**: No clear guidance on when to use which tool
+- ❌ **Default inconsistency**: Different defaults across commands
+- ❌ **Capability confusion**: What each tool is best for
+
+**Recommendations**:
+1. ✅ Create tool selection guide:
+   - **Gemini**: Best for analysis, planning (default for most)
+   - **Qwen**: Fallback when Gemini unavailable
+   - **Codex**: Best for complex implementation, multi-stage execution
+2. ✅ Add tool selection hints to command descriptions
+3. ✅ Document tool capabilities clearly
+
+---
+
+### 6. Enhancement Flag Inconsistency
+
+**Problem**: Different enhancement flags with different meanings
+
+| Command | Flag | Meaning |
+|---------|------|---------|
+| `/cli:execute` | `--enhance` | Enhance prompt via `/enhance-prompt` |
+| `/cli:analyze` | `--enhance` | Enhance prompt via `/enhance-prompt` |
+| `/workflow:lite-plan` | `-e` or `--explore` | Force code exploration |
+| `/memory:skill-memory` | `--regenerate` | Regenerate existing files |
+
+**Ambiguities**:
+- ❌ **Flag meaning**: `-e` means different things
+- ❌ **Inconsistent naming**: `--enhance` vs `--explore` vs `--regenerate`
+
+**Recommendations**:
+1. ✅ Standardize flags:
+   - Use `--enhance` consistently for prompt enhancement
+   - Use `--explore` specifically for codebase exploration
+   - Use `--regenerate` for file regeneration
+2. ✅ Avoid short flags (`-e`) that could be ambiguous
+
+---
+
+## Low Priority Observations
+
+### 7. Session Management Commands (Well-Designed ✅)
+
+**Commands**:
+- `/workflow:session:start`
+- `/workflow:session:resume`
+- `/workflow:session:complete`
+- `/workflow:session:list`
+
+**Analysis**: These are **well-designed** with clear, distinct purposes. No ambiguity found.
+
+---
+
+### 8. Memory Commands (Acceptable)
+
+Memory commands follow consistent patterns but could benefit from better organization:
+- `/memory:load`
+- `/memory:docs`
+- `/memory:skill-memory`
+- `/memory:code-map-memory`
+- `/memory:update-full`
+- `/memory:update-related`
+
+**Minor Issue**: Many memory commands, but purposes are relatively clear.
+
+---
+
+## Parameter Ambiguity Analysis
+
+### Common Parameter Patterns
+
+| Parameter | Commands Using It | Ambiguity Level |
+|-----------|-------------------|-----------------|
+| `--tool` | 10+ commands | HIGH - Inconsistent defaults |
+| `--enhance` | 5+ commands | MEDIUM - Similar but not identical |
+| `--session` | 8+ commands | LOW - Consistent meaning |
+| `--cli-execute` | 3+ commands | LOW - Clear meaning |
+| `-e` / `--explore` | 2+ commands | HIGH - Different meanings |
+
+---
+
+## Output Ambiguity Analysis
+
+### Output Location Confusion
+
+Multiple commands output to similar locations:
+
+**`.chat/` outputs** (read-only analysis):
+- `/cli:analyze` → `.chat/analyze-*.md`
+- `/cli:mode:plan` → `.chat/plan-*.md`
+- `/cli:discuss-plan` → `.chat/discuss-plan-*.md`
+- `/cli:execute` → `.chat/execute-*.md` (❌ Misleading - actually modifies code!)
+
+**Ambiguity**:
+- Users might think all `.chat/` outputs are read-only
+- `/cli:execute` outputs to `.chat/` but modifies code (YOLO)
+
+**Recommendation**:
+- ✅ Separate execution logs from analysis logs
+- ✅ Use different directory for code-modifying operations
+
+---
+
+## Decision Tree Recommendations
+
+### When to Use Planning Commands
+
+```
+START: I need to plan something
+│
+├─ Is this a new full project workflow?
+│  └─ YES → /workflow:plan (5-phase, creates tasks)
+│
+├─ Do I need quick planning without full workflow?
+│  └─ YES → /workflow:lite-plan (fast, interactive)
+│
+├─ Do I need architecture-level planning only?
+│  └─ YES → /cli:mode:plan (read-only, no tasks)
+│
+├─ Do I need multi-perspective discussion?
+│  └─ YES → /cli:discuss-plan (Gemini + Codex + Claude)
+│
+└─ Am I modifying an existing plan?
+   └─ YES → /workflow:replan (modify artifacts)
+```
+
+### When to Use Execution Commands
+
+```
+START: I need to execute/implement something
+│
+├─ Do I have an active workflow session with tasks?
+│  └─ YES → /workflow:execute (execute all tasks)
+│
+├─ Do I have a single task ID to execute?
+│  └─ YES → /task:execute IMPL-N (single task)
+│
+├─ Do I have a plan or description to execute quickly?
+│  └─ YES → /workflow:lite-execute (flexible input)
+│
+├─ Do I want direct, autonomous implementation (⚠️ YOLO)?
+│  ├─ Single-stage → /cli:execute (auto-approval)
+│  └─ Multi-stage → /cli:codex-execute (complex tasks)
+│
+└─ ⚠️ WARNING: CLI execute commands modify code without confirmation
+```
+
+### When to Use Analysis Commands
+
+```
+START: I need to analyze code
+│
+├─ General codebase understanding?
+│  └─ /cli:analyze (broad analysis)
+│
+├─ Specific execution path tracing?
+│  └─ /cli:mode:code-analysis (detailed flow)
+│
+├─ Bug diagnosis?
+│  └─ /cli:mode:bug-diagnosis (root cause)
+│
+└─ Quick Q&A?
+   └─ /cli:chat (interactive)
+```
+
+---
+
+## Summary of Findings
+
+### Ambiguity Count by Severity
+
+| Severity | Count | Commands Affected |
+|----------|-------|-------------------|
+| 🚨 CRITICAL | 2 | Planning (5 cmds), Execution (5 cmds) |
+| ⚠️ HIGH | 2 | Tool selection, Enhancement flags |
+| ℹ️ MEDIUM | 3 | Analysis, Task/Workflow overlap, Output locations |
+| ✅ LOW | Multiple | Most other commands acceptable |
+
+### Key Recommendations Priority
+
+1. **🚨 URGENT**: Add safety warnings to YOLO execution commands
+2. **🚨 URGENT**: Create decision trees for planning and execution commands
+3. **⚠️ HIGH**: Standardize tool selection criteria documentation
+4. **⚠️ HIGH**: Clarify enhancement flag meanings
+5. **ℹ️ MEDIUM**: Reorganize output directories by operation type
+6. **ℹ️ MEDIUM**: Consider renaming most ambiguous commands
+
+---
+
+## Recommended Actions
+
+### Immediate (Week 1)
+1. ✅ Add decision trees to documentation
+2. ✅ Add ⚠️ WARNING labels to YOLO commands
+3. ✅ Create "Which command should I use?" guide
+
+### Short-term (Month 1)
+1. ✅ Standardize flag meanings across commands
+2. ✅ Add tool selection guide
+3. ✅ Clarify command descriptions
+
+### Long-term (Future)
+1. 🤔 Consider command consolidation or renaming
+2. 🤔 Reorganize output directory structure
+3. 🤔 Add interactive command selector tool
+
+---
+
+## Conclusion
+
+The command system is **powerful but complex**. The main ambiguities stem from:
+- Multiple commands with similar names serving different purposes
+- Inconsistent parameter usage
+- Unclear decision criteria for command selection
+
+**Overall Assessment**: The codebase has a well-structured command system, but would benefit significantly from:
+1. Better documentation (decision trees, use case examples)
+2. Clearer naming conventions
+3. Consistent parameter patterns
+4. Safety warnings for destructive operations
+
+**Risk Level**: MEDIUM - Experienced users can navigate, but new users will struggle. The YOLO execution commands pose the highest risk of accidental misuse.
--- a/OUTPUT_DIRECTORY_REORGANIZATION.md
+++ b/OUTPUT_DIRECTORY_REORGANIZATION.md
@@ -0,0 +1,654 @@
+# Output Directory Reorganization Recommendations
+
+## Executive Summary
+
+Current output directory structure mixes different operation types (read-only analysis, code modifications, planning artifacts) in the same directories, leading to confusion and poor organization. This document proposes a **semantic directory structure** that separates outputs by purpose and operation type.
+
+**Impact**: Affects 30+ commands, requires phased migration
+**Priority**: MEDIUM (improves clarity, not critical functionality)
+**Effort**: 2-4 weeks for full implementation
+
+---
+
+## Current Structure Analysis
+
+### Active Session Structure
+
+```
+.workflow/active/WFS-{session-id}/
+├── workflow-session.json          # Session metadata
+├── IMPL_PLAN.md                   # Planning document
+├── TODO_LIST.md                   # Progress tracking
+│
+├── .chat/                         # ⚠️ MIXED PURPOSE
+│   ├── analyze-*.md               # Read-only analysis
+│   ├── plan-*.md                  # Read-only planning
+│   ├── discuss-plan-*.md          # Read-only discussion
+│   ├── execute-*.md               # ⚠️ Code-modifying execution
+│   └── chat-*.md                  # Q&A interactions
+│
+├── .summaries/                    # Task completion summaries
+│   ├── IMPL-*-summary.md
+│   └── TEST-FIX-*-summary.md
+│
+├── .task/                         # Task definitions
+│   ├── IMPL-001.json
+│   └── IMPL-001.1.json
+│
+└── .process/                      # ⚠️ MIXED PURPOSE
+    ├── context-package.json       # Planning context
+    ├── test-context-package.json  # Test context
+    ├── phase2-analysis.json       # Temporary analysis
+    ├── CONFLICT_RESOLUTION.md     # Planning artifact
+    ├── ACTION_PLAN_VERIFICATION.md # Verification report
+    └── backup/                    # Backup storage
+        └── replan-{timestamp}/
+```
+
+### Scratchpad Structure (No Session)
+
+```
+.workflow/.scratchpad/
+├── analyze-*.md
+├── execute-*.md
+├── chat-*.md
+└── plan-*.md
+```
+
+---
+
+## Problems Identified
+
+### 1. **Semantic Confusion** 🚨 CRITICAL
+
+**Problem**: `.chat/` directory contains both:
+- ✅ Read-only operations (analyze, chat, plan)
+- ⚠️ Code-modifying operations (execute)
+
+**Impact**: Users assume `.chat/` is safe (read-only), but some files represent dangerous operations
+
+**Example**:
+```bash
+# These both output to .chat/ but have VERY different impacts:
+/cli:analyze "review auth code"        # Read-only → .chat/analyze-*.md
+/cli:execute "implement auth feature"  # ⚠️ MODIFIES CODE → .chat/execute-*.md
+```
+
+### 2. **Purpose Overload**
+
+**Problem**: `.process/` used for multiple unrelated purposes:
+- Planning artifacts (context-package.json)
+- Temporary analysis (phase2-analysis.json)
+- Verification reports (ACTION_PLAN_VERIFICATION.md)
+- Backup storage (backup/)
+
+**Impact**: Difficult to understand what's in `.process/`
+
+### 3. **Inconsistent Organization**
+
+**Problem**: Different commands use different naming patterns:
+- Some use timestamps: `analyze-{timestamp}.md`
+- Some use topics: `plan-{topic}.md`
+- Some use task IDs: `IMPL-001-summary.md`
+
+**Impact**: Hard to find specific outputs
+
+### 4. **No Operation Type Distinction**
+
+**Problem**: Can't distinguish operation type from directory structure:
+- Analysis outputs mixed with execution logs
+- Planning discussions mixed with implementation records
+- No clear audit trail
+
+**Impact**: Poor traceability, difficult debugging
+
+---
+
+## Proposed New Structure
+
+### Design Principles
+
+1. **Semantic Organization**: Directories reflect operation type and safety level
+2. **Clear Hierarchy**: Separate by purpose → type → chronology
+3. **Safety Indicators**: Code-modifying operations clearly separated
+4. **Consistent Naming**: Standard patterns across all commands
+5. **Backward Compatible**: Old structure accessible during migration
+
+---
+
+## Recommended Structure v2.0
+
+```
+.workflow/active/WFS-{session-id}/
+│
+├── ## Core Artifacts (Root Level)
+├── workflow-session.json
+├── IMPL_PLAN.md
+├── TODO_LIST.md
+│
+├── ## Task Definitions
+├── tasks/                         # (renamed from .task/)
+│   ├── IMPL-001.json
+│   └── IMPL-001.1.json
+│
+├── ## 🟢 READ-ONLY Operations (Safe)
+├── analysis/                      # (split from .chat/)
+│   ├── code/
+│   │   ├── 2024-01-15T10-30-auth-patterns.md
+│   │   └── 2024-01-15T11-45-api-structure.md
+│   ├── architecture/
+│   │   └── 2024-01-14T09-00-caching-layer.md
+│   └── bugs/
+│       └── 2024-01-16T14-20-login-bug-diagnosis.md
+│
+├── planning/                      # (split from .chat/)
+│   ├── discussions/
+│   │   └── 2024-01-13T15-00-auth-strategy-3rounds.md
+│   ├── architecture/
+│   │   └── 2024-01-13T16-30-database-design.md
+│   └── revisions/
+│       └── 2024-01-17T10-00-replan-add-2fa.md
+│
+├── interactions/                  # (split from .chat/)
+│   ├── 2024-01-15T10-00-question-about-jwt.md
+│   └── 2024-01-15T14-30-how-to-test-auth.md
+│
+├── ## ⚠️ CODE-MODIFYING Operations (Dangerous)
+├── executions/                    # (split from .chat/)
+│   ├── implementations/
+│   │   ├── 2024-01-15T11-00-impl-jwt-auth.md
+│   │   ├── 2024-01-15T12-30-impl-user-api.md
+│   │   └── metadata.json          # Execution metadata
+│   ├── test-fixes/
+│   │   └── 2024-01-16T09-00-fix-auth-tests.md
+│   └── refactors/
+│       └── 2024-01-16T15-00-refactor-middleware.md
+│
+├── ## Completion Records
+├── summaries/                     # (kept same)
+│   ├── implementations/
+│   │   ├── IMPL-001-jwt-authentication.md
+│   │   └── IMPL-002-user-endpoints.md
+│   ├── tests/
+│   │   └── TEST-FIX-001-auth-validation.md
+│   └── index.json                 # Quick lookup
+│
+├── ## Planning Context & Artifacts
+├── context/                       # (split from .process/)
+│   ├── project/
+│   │   ├── context-package.json
+│   │   └── test-context-package.json
+│   ├── brainstorm/
+│   │   ├── guidance-specification.md
+│   │   ├── synthesis-output.md
+│   │   └── roles/
+│   │       ├── api-designer-analysis.md
+│   │       └── system-architect-analysis.md
+│   └── conflicts/
+│       └── 2024-01-14T10-00-resolution.md
+│
+├── ## Verification & Quality
+├── quality/                       # (split from .process/)
+│   ├── verifications/
+│   │   └── 2024-01-15T09-00-action-plan-verify.md
+│   ├── reviews/
+│   │   ├── 2024-01-17T11-00-security-review.md
+│   │   └── 2024-01-17T12-00-architecture-review.md
+│   └── tdd-compliance/
+│       └── 2024-01-16T16-00-cycle-analysis.md
+│
+├── ## History & Backups
+├── history/                       # (renamed from .process/backup/)
+│   ├── replans/
+│   │   └── 2024-01-17T10-00-add-2fa/
+│   │       ├── MANIFEST.md
+│   │       ├── IMPL_PLAN.md
+│   │       └── tasks/
+│   └── snapshots/
+│       └── 2024-01-15T00-00-milestone-1/
+│
+└── ## Temporary Working Data
+    └── temp/                      # (for transient analysis)
+        └── phase2-analysis.json
+```
+
+### Scratchpad Structure v2.0
+
+```
+.workflow/.scratchpad/
+├── analysis/
+├── planning/
+├── interactions/
+└── executions/          # ⚠️ Code-modifying
+```
+
+---
+
+## Directory Purpose Reference
+
+| Directory | Purpose | Safety | Retention |
+|-----------|---------|--------|-----------|
+| `analysis/` | Code understanding, bug diagnosis | 🟢 Read-only | Keep indefinitely |
+| `planning/` | Architecture plans, discussions | 🟢 Read-only | Keep indefinitely |
+| `interactions/` | Q&A, chat sessions | 🟢 Read-only | Keep 30 days |
+| `executions/` | Implementation logs | ⚠️ Modifies code | Keep indefinitely |
+| `summaries/` | Task completion records | 🟢 Reference | Keep indefinitely |
+| `context/` | Planning context, brainstorm | 🟢 Reference | Keep indefinitely |
+| `quality/` | Reviews, verifications | 🟢 Reference | Keep indefinitely |
+| `history/` | Backups, snapshots | 🟢 Archive | Keep indefinitely |
+| `temp/` | Transient analysis data | 🟢 Temporary | Clean on completion |
+
+---
+
+## Naming Convention Standards
+
+### Timestamp-based Files
+
+**Format**: `YYYY-MM-DDTHH-MM-{description}.md`
+
+**Examples**:
+- `2024-01-15T10-30-auth-patterns.md`
+- `2024-01-15T11-45-jwt-implementation.md`
+
+**Benefits**:
+- Chronological sorting
+- Unique identifiers
+- Easy to find by date
+
+### Task-based Files
+
+**Format**: `{TASK-ID}-{description}.md`
+
+**Examples**:
+- `IMPL-001-jwt-authentication.md`
+- `TEST-FIX-002-login-validation.md`
+
+**Benefits**:
+- Clear task association
+- Easy to find by task ID
+
+### Metadata Files
+
+**Format**: `{type}.json` or `{type}-metadata.json`
+
+**Examples**:
+- `context-package.json`
+- `execution-metadata.json`
+- `index.json`
+
+---
+
+## Command Output Mapping
+
+### Analysis Commands → `analysis/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/cli:analyze` | `.chat/analyze-*.md` | `analysis/code/{timestamp}-{topic}.md` |
+| `/cli:mode:code-analysis` | `.chat/code-analysis-*.md` | `analysis/code/{timestamp}-{topic}.md` |
+| `/cli:mode:bug-diagnosis` | `.chat/bug-diagnosis-*.md` | `analysis/bugs/{timestamp}-{topic}.md` |
+
+### Planning Commands → `planning/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/cli:mode:plan` | `.chat/plan-*.md` | `planning/architecture/{timestamp}-{topic}.md` |
+| `/cli:discuss-plan` | `.chat/discuss-plan-*.md` | `planning/discussions/{timestamp}-{topic}.md` |
+| `/workflow:replan` | (modifies artifacts) | `planning/revisions/{timestamp}-{reason}.md` |
+
+### Execution Commands → `executions/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/cli:execute` | `.chat/execute-*.md` | `executions/implementations/{timestamp}-{description}.md` |
+| `/cli:codex-execute` | `.chat/codex-*.md` | `executions/implementations/{timestamp}-{description}.md` |
+| `/workflow:execute` | (multiple) | `executions/implementations/{timestamp}-{task-id}.md` |
+| `/workflow:test-cycle-execute` | (various) | `executions/test-fixes/{timestamp}-cycle-{n}.md` |
+
+### Quality Commands → `quality/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/workflow:action-plan-verify` | `.process/ACTION_PLAN_VERIFICATION.md` | `quality/verifications/{timestamp}-action-plan.md` |
+| `/workflow:review` | (inline) | `quality/reviews/{timestamp}-{type}.md` |
+| `/workflow:tdd-verify` | (inline) | `quality/tdd-compliance/{timestamp}-verify.md` |
+
+### Context Commands → `context/`
+
+| Data Type | Old Location | New Location |
+|-----------|-------------|--------------|
+| Context packages | `.process/context-package.json` | `context/project/context-package.json` |
+| Brainstorm artifacts | `.process/` | `context/brainstorm/` |
+| Conflict resolution | `.process/CONFLICT_RESOLUTION.md` | `context/conflicts/{timestamp}-resolution.md` |
+
+---
+
+## Migration Strategy
+
+### Phase 1: Dual Write (Week 1-2)
+
+**Goal**: Write to both old and new locations
+
+**Implementation**:
+```bash
+# Example for /cli:analyze
+old_path=".workflow/active/$session/.chat/analyze-$timestamp.md"
+new_path=".workflow/active/$session/analysis/code/$timestamp-$topic.md"
+
+# Write to both locations
+Write($old_path, content)
+Write($new_path, content)
+
+# Add migration notice to old location
+echo "⚠️ This file has moved to: $new_path" >> $old_path
+```
+
+**Changes**:
+- Update all commands to write to new structure
+- Keep writing to old structure for compatibility
+- Add deprecation notices
+
+**Commands to Update**: 30+ commands
+
+### Phase 2: Dual Read (Week 3)
+
+**Goal**: Read from new location, fallback to old
+
+**Implementation**:
+```bash
+# Example read logic
+if [ -f "$new_path" ]; then
+  content=$(cat "$new_path")
+elif [ -f "$old_path" ]; then
+  content=$(cat "$old_path")
+  # Migrate on read
+  mkdir -p "$(dirname "$new_path")"
+  cp "$old_path" "$new_path"
+  echo "✓ Migrated: $old_path → $new_path"
+fi
+```
+
+**Changes**:
+- Update read logic in all commands
+- Automatic migration on read
+- Log migrations for verification
+
+### Phase 3: Legacy Deprecation (Week 4)
+
+**Goal**: Stop writing to old locations
+
+**Implementation**:
+```bash
+# Stop dual write, only write to new structure
+new_path=".workflow/active/$session/analysis/code/$timestamp-$topic.md"
+Write($new_path, content)
+
+# No longer write to old_path
+```
+
+**Changes**:
+- Remove old write logic
+- Keep read fallback for 1 release cycle
+- Update documentation
+
+### Phase 4: Full Migration (Future Release)
+
+**Goal**: Remove old structure entirely
+
+**Implementation**:
+```bash
+# One-time migration script
+/workflow:migrate-outputs --session all --dry-run
+/workflow:migrate-outputs --session all --execute
+```
+
+**Migration Script**:
+```bash
+#!/bin/bash
+# migrate-outputs.sh
+
+session_dir="$1"
+
+# Migrate .chat/ files
+for file in "$session_dir/.chat"/*; do
+  case "$file" in
+    *analyze*)
+      mv "$file" "$session_dir/analysis/code/"
+      ;;
+    *execute*)
+      mv "$file" "$session_dir/executions/implementations/"
+      ;;
+    *plan*)
+      mv "$file" "$session_dir/planning/architecture/"
+      ;;
+    *chat*)
+      mv "$file" "$session_dir/interactions/"
+      ;;
+  esac
+done
+
+# Migrate .process/ files
+mv "$session_dir/.process/context-package.json" "$session_dir/context/project/"
+mv "$session_dir/.process/backup" "$session_dir/history/"
+
+# Remove old directories
+rmdir "$session_dir/.chat" "$session_dir/.process" 2>/dev/null
+
+echo "✓ Migration complete: $session_dir"
+```
+
+---
+
+## Implementation Checklist
+
+### Week 1-2: Dual Write Setup
+
+**Core Commands** (Priority 1):
+- [ ] `/cli:analyze` → `analysis/code/`
+- [ ] `/cli:execute` → `executions/implementations/`
+- [ ] `/cli:mode:plan` → `planning/architecture/`
+- [ ] `/workflow:execute` → `executions/implementations/`
+- [ ] `/workflow:action-plan-verify` → `quality/verifications/`
+
+**Planning Commands** (Priority 2):
+- [ ] `/cli:discuss-plan` → `planning/discussions/`
+- [ ] `/workflow:replan` → `planning/revisions/`
+- [ ] `/workflow:plan` → (updates `context/project/`)
+
+**Context Commands** (Priority 3):
+- [ ] `/workflow:tools:context-gather` → `context/project/`
+- [ ] `/workflow:brainstorm:*` → `context/brainstorm/`
+- [ ] `/workflow:tools:conflict-resolution` → `context/conflicts/`
+
+### Week 3: Dual Read + Auto-Migration
+
+**Read Logic Updates**:
+- [ ] Update all Read() calls with fallback logic
+- [ ] Add migration-on-read for all file types
+- [ ] Log all automatic migrations
+
+**Testing**:
+- [ ] Test with existing sessions
+- [ ] Test with new sessions
+- [ ] Verify backward compatibility
+
+### Week 4: Documentation + Deprecation
+
+**Documentation Updates**:
+- [ ] Update command documentation with new paths
+- [ ] Add migration guide for users
+- [ ] Document new directory structure
+- [ ] Add "Directory Purpose Reference" to docs
+
+**Deprecation Notices**:
+- [ ] Add notices to old command outputs
+- [ ] Update error messages with new paths
+- [ ] Create migration FAQ
+
+---
+
+## Benefits Analysis
+
+### Immediate Benefits
+
+**1. Safety Clarity** 🟢
+- Clear separation: Read-only vs Code-modifying operations
+- Users can quickly identify dangerous operations
+- Reduces accidental code modifications
+
+**2. Better Organization** 📁
+- Semantic structure reflects operation purpose
+- Easy to find specific outputs
+- Clear audit trail
+
+**3. Improved Traceability** 🔍
+- Execution logs separated by type
+- Planning discussions organized chronologically
+- Quality checks easily accessible
+
+### Long-term Benefits
+
+**4. Scalability** 📈
+- Structure scales to 100+ sessions
+- Easy to add new operation types
+- Consistent organization patterns
+
+**5. Automation Potential** 🤖
+- Programmatic analysis of outputs
+- Automated cleanup of old files
+- Better CI/CD integration
+
+**6. User Experience** 👥
+- Intuitive directory structure
+- Self-documenting organization
+- Easier onboarding for new users
+
+---
+
+## Risk Assessment
+
+### Migration Risks
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| **Breaking Changes** | HIGH | Phased migration with dual write/read |
+| **Data Loss** | MEDIUM | Automatic migration on read, keep backups |
+| **User Confusion** | MEDIUM | Clear documentation, migration guide |
+| **Command Failures** | LOW | Fallback to old locations during transition |
+| **Performance Impact** | LOW | Dual write adds minimal overhead |
+
+### Rollback Strategy
+
+If migration causes issues:
+
+**Phase 1 Rollback** (Dual Write):
+- Stop writing to new locations
+- Continue using old structure
+- No data loss
+
+**Phase 2 Rollback** (Dual Read):
+- Disable migration-on-read
+- Continue reading from old locations
+- New files still in new structure (OK)
+
+**Phase 3+ Rollback**:
+- Run reverse migration script
+- Copy new structure files back to old locations
+- May require manual intervention
+
+---
+
+## Alternative Approaches Considered
+
+### Alternative 1: Flat Structure with Prefixes
+
+```
+.workflow/active/WFS-{session}/
+├── ANALYSIS_2024-01-15_auth-patterns.md
+├── EXEC_2024-01-15_jwt-impl.md
+└── PLAN_2024-01-14_architecture.md
+```
+
+**Rejected**: Too many files in one directory, poor organization
+
+### Alternative 2: Single "logs/" Directory
+
+```
+.workflow/active/WFS-{session}/
+└── logs/
+    ├── 2024-01-15T10-30-analyze-auth.md
+    └── 2024-01-15T11-00-execute-jwt.md
+```
+
+**Rejected**: Doesn't solve semantic confusion
+
+### Alternative 3: Minimal Change (Status Quo++)
+
+```
+.workflow/active/WFS-{session}/
+├── .chat/          # Rename to .interactions/
+├── .exec/          # NEW: Split executions out
+├── .summaries/
+└── .process/
+```
+
+**Partially Adopted**: Considered as "lite" version if full migration too complex
+
+---
+
+## Recommended Timeline
+
+### Immediate (This Sprint)
+1. ✅ Document current structure
+2. ✅ Create proposed structure v2.0
+3. ✅ Get stakeholder approval
+
+### Short-term (Next 2 Sprints - 4 weeks)
+1. 📝 Implement Phase 1: Dual Write
+2. 🔍 Implement Phase 2: Dual Read
+3. 📢 Implement Phase 3: Deprecation
+
+### Long-term (Future Release)
+1. 🗑️ Implement Phase 4: Full Migration
+2. 🧹 Remove old structure code
+3. 📚 Update all documentation
+
+---
+
+## Success Metrics
+
+### Quantitative
+- ✅ 100% of commands updated to new structure
+- ✅ 0 data loss during migration
+- ✅ <5% increase in execution time (dual write overhead)
+- ✅ 90% of sessions migrated within 1 month
+
+### Qualitative
+- ✅ User feedback: "Easier to find outputs"
+- ✅ User feedback: "Clearer which operations are safe"
+- ✅ Developer feedback: "Easier to maintain"
+
+---
+
+## Conclusion
+
+The proposed directory reorganization addresses critical semantic confusion in the current structure by:
+
+1. **Separating read-only from code-modifying operations** (safety)
+2. **Organizing by purpose** (usability)
+3. **Using consistent naming** (maintainability)
+4. **Providing clear migration path** (feasibility)
+
+**Recommendation**: Proceed with phased migration starting with dual-write implementation.
+
+**Next Steps**:
+1. Review and approve proposed structure
+2. Identify pilot commands for Phase 1
+3. Create detailed implementation tasks
+4. Begin dual-write implementation
+
+**Questions for Discussion**:
+1. Should we use "lite" version (minimal changes) or full v2.0?
+2. What's the acceptable timeline for full migration?
+3. Are there any other directory purposes we should consider?
+4. Should we add more automation (e.g., auto-cleanup old files)?
--- a/OUTPUT_STRUCTURE_COMPARISON.md
+++ b/OUTPUT_STRUCTURE_COMPARISON.md
@@ -0,0 +1,404 @@
+# Output Structure: Before vs After
+
+## Quick Visual Comparison
+
+### Current Structure (v1.0) - ⚠️ Problematic
+
+```
+.workflow/active/WFS-session/
+├── .chat/                    ⚠️ MIXED: Safe + Dangerous operations
+│   ├── analyze-*.md          ✅ Read-only
+│   ├── plan-*.md             ✅ Read-only
+│   ├── chat-*.md             ✅ Read-only
+│   └── execute-*.md          ⚠️ MODIFIES CODE!
+│
+├── .summaries/               ✅ OK
+├── .task/                    ✅ OK
+└── .process/                 ⚠️ MIXED: Multiple purposes
+    ├── context-package.json  (planning context)
+    ├── phase2-analysis.json  (temp data)
+    ├── CONFLICT_RESOLUTION.md (planning artifact)
+    └── backup/               (history)
+```
+
+**Problems**:
+- ❌ `.chat/` mixes safe (read-only) and dangerous (code-modifying) operations
+- ❌ `.process/` serves too many purposes
+- ❌ No clear organization by operation type
+- ❌ Hard to find specific outputs
+
+---
+
+### Proposed Structure (v2.0) - ✅ Clear & Semantic
+
+```
+.workflow/active/WFS-session/
+│
+├── 🟢 SAFE: Read-only Operations
+│   ├── analysis/             Split from .chat/
+│   │   ├── code/            Code understanding
+│   │   ├── architecture/    Architecture analysis
+│   │   └── bugs/            Bug diagnosis
+│   │
+│   ├── planning/            Split from .chat/
+│   │   ├── discussions/     Multi-round planning
+│   │   ├── architecture/    Architecture plans
+│   │   └── revisions/       Replan history
+│   │
+│   └── interactions/        Split from .chat/
+│       └── *-chat.md        Q&A sessions
+│
+├── ⚠️ DANGEROUS: Code-modifying Operations
+│   └── executions/          Split from .chat/
+│       ├── implementations/ Code implementations
+│       ├── test-fixes/      Test fixes
+│       └── refactors/       Refactoring
+│
+├── 📊 RECORDS: Completion & Quality
+│   ├── summaries/           Keep same (task completions)
+│   │
+│   └── quality/             Split from .process/
+│       ├── verifications/   Plan verifications
+│       ├── reviews/         Code reviews
+│       └── tdd-compliance/  TDD checks
+│
+├── 📦 CONTEXT: Planning Artifacts
+│   └── context/             Split from .process/
+│       ├── project/         Context packages
+│       ├── brainstorm/      Brainstorm artifacts
+│       └── conflicts/       Conflict resolutions
+│
+├── 📜 HISTORY: Backups & Archives
+│   └── history/             Rename from .process/backup/
+│       ├── replans/         Replan backups
+│       └── snapshots/       Session snapshots
+│
+└── 📋 TASKS: Definitions
+    └── tasks/               Rename from .task/
+```
+
+**Benefits**:
+- ✅ Clear separation: Safe vs Dangerous operations
+- ✅ Semantic organization by purpose
+- ✅ Easy to find outputs by type
+- ✅ Self-documenting structure
+
+---
+
+## Key Changes Summary
+
+### 1. Split `.chat/` by Safety Level
+
+| Current | New | Safety |
+|---------|-----|--------|
+| `.chat/analyze-*.md` | `analysis/code/` | 🟢 Safe |
+| `.chat/plan-*.md` | `planning/architecture/` | 🟢 Safe |
+| `.chat/chat-*.md` | `interactions/` | 🟢 Safe |
+| `.chat/execute-*.md` | `executions/implementations/` | ⚠️ Dangerous |
+
+### 2. Split `.process/` by Purpose
+
+| Current | New | Purpose |
+|---------|-----|---------|
+| `.process/context-package.json` | `context/project/` | Planning context |
+| `.process/CONFLICT_RESOLUTION.md` | `context/conflicts/` | Planning artifact |
+| `.process/ACTION_PLAN_VERIFICATION.md` | `quality/verifications/` | Quality check |
+| `.process/backup/` | `history/replans/` | Backups |
+| `.process/phase2-analysis.json` | `temp/` | Temporary data |
+
+### 3. Rename for Clarity
+
+| Current | New | Reason |
+|---------|-----|--------|
+| `.task/` | `tasks/` | Remove dot prefix (not hidden) |
+| `.summaries/` | `summaries/` | Keep same (already clear) |
+
+---
+
+## Command Output Changes (Examples)
+
+### Analysis Commands
+
+```bash
+# Current (v1.0)
+/cli:analyze "review auth code"
+→ .chat/analyze-2024-01-15.md               ⚠️ Mixed with dangerous ops
+
+# Proposed (v2.0)
+/cli:analyze "review auth code"
+→ analysis/code/2024-01-15T10-30-auth.md    ✅ Clearly safe
+```
+
+### Execution Commands
+
+```bash
+# Current (v1.0)
+/cli:execute "implement auth"
+→ .chat/execute-2024-01-15.md               ⚠️ Looks safe, but dangerous!
+
+# Proposed (v2.0)
+/cli:execute "implement auth"
+→ executions/implementations/2024-01-15T11-00-auth.md    ⚠️ Clearly dangerous
+```
+
+### Planning Commands
+
+```bash
+# Current (v1.0)
+/cli:discuss-plan "design caching"
+→ .chat/discuss-plan-2024-01-15.md          ⚠️ Mixed with dangerous ops
+
+# Proposed (v2.0)
+/cli:discuss-plan "design caching"
+→ planning/discussions/2024-01-15T15-00-caching-3rounds.md    ✅ Clearly safe
+```
+
+---
+
+## Migration Impact
+
+### Affected Commands: ~30
+
+**Analysis Commands** (6):
+- `/cli:analyze`
+- `/cli:mode:code-analysis`
+- `/cli:mode:bug-diagnosis`
+- `/cli:chat`
+- `/memory:code-map-memory`
+- `/workflow:review`
+
+**Planning Commands** (5):
+- `/cli:mode:plan`
+- `/cli:discuss-plan`
+- `/workflow:plan`
+- `/workflow:replan`
+- `/workflow:brainstorm:*`
+
+**Execution Commands** (8):
+- `/cli:execute`
+- `/cli:codex-execute`
+- `/workflow:execute`
+- `/workflow:lite-execute`
+- `/task:execute`
+- `/workflow:test-cycle-execute`
+- `/workflow:test-fix-gen`
+- `/workflow:test-gen`
+
+**Quality Commands** (4):
+- `/workflow:action-plan-verify`
+- `/workflow:review`
+- `/workflow:tdd-verify`
+- `/workflow:tdd-coverage-analysis`
+
+**Context Commands** (7):
+- `/workflow:tools:context-gather`
+- `/workflow:tools:conflict-resolution`
+- `/workflow:brainstorm:artifacts`
+- `/memory:skill-memory`
+- `/memory:docs`
+- `/memory:load`
+- `/memory:tech-research`
+
+---
+
+## Safety Indicators
+
+### Directory Color Coding
+
+- 🟢 **Green** (Safe): Read-only operations, no code changes
+  - `analysis/`
+  - `planning/`
+  - `interactions/`
+  - `summaries/`
+  - `quality/`
+  - `context/`
+  - `history/`
+
+- ⚠️ **Yellow** (Dangerous): Code-modifying operations
+  - `executions/`
+
+### File Naming Patterns
+
+**Safe Operations** (🟢):
+```
+analysis/code/2024-01-15T10-30-auth-patterns.md
+planning/discussions/2024-01-15T15-00-caching-3rounds.md
+interactions/2024-01-15T14-00-jwt-question.md
+```
+
+**Dangerous Operations** (⚠️):
+```
+executions/implementations/2024-01-15T11-00-impl-auth.md
+executions/test-fixes/2024-01-16T09-00-fix-login-tests.md
+executions/refactors/2024-01-16T15-00-refactor-middleware.md
+```
+
+---
+
+## User Experience Improvements
+
+### Before (v1.0) - Confusing ❌
+
+**User wants to review analysis logs**:
+```bash
+$ ls .workflow/active/WFS-auth/.chat/
+analyze-2024-01-15.md
+execute-2024-01-15.md    # ⚠️ Wait, which one is safe?
+plan-2024-01-14.md
+execute-2024-01-16.md    # ⚠️ More dangerous files mixed in!
+chat-2024-01-15.md
+```
+
+User thinks: "They're all in `.chat/`, so they're all logs... right?" 😰
+
+### After (v2.0) - Clear ✅
+
+**User wants to review analysis logs**:
+```bash
+$ ls .workflow/active/WFS-auth/
+analysis/      # ✅ Safe - code understanding
+planning/      # ✅ Safe - planning discussions
+interactions/  # ✅ Safe - Q&A logs
+executions/    # ⚠️ DANGER - code modifications
+```
+
+User thinks: "Oh, `executions/` is separate. I know that modifies code!" 😊
+
+---
+
+## Performance Impact
+
+### Storage
+
+**Overhead**: Negligible
+- Deeper directory nesting adds ~10 bytes per file
+- For 1000 files: ~10 KB additional metadata
+
+### Access Speed
+
+**Overhead**: Negligible
+- Modern filesystems handle nested directories efficiently
+- Typical lookup: O(log n) regardless of depth
+
+### Migration Cost
+
+**Phase 1 (Dual Write)**: ~5-10% overhead
+- Writing to both old and new locations
+- Temporary during migration period
+
+**Phase 2+ (New Structure Only)**: No overhead
+- Single write location
+- Actually slightly faster (better organization)
+
+---
+
+## Rollback Plan
+
+If migration causes issues:
+
+### Easy Rollback (Phase 1-2)
+
+```bash
+# Stop using new structure
+git revert <migration-commit>
+# Continue with old structure
+# No data loss (dual write preserved both)
+```
+
+### Manual Rollback (Phase 3+)
+
+```bash
+# Copy files back to old locations
+cp -r analysis/code/* .chat/
+cp -r executions/implementations/* .chat/
+cp -r context/project/* .process/
+# etc.
+```
+
+---
+
+## Timeline Summary
+
+| Phase | Duration | Status | Risk |
+|-------|----------|--------|------|
+| **Phase 1**: Dual Write | 2 weeks | 📋 Planned | LOW |
+| **Phase 2**: Dual Read | 1 week | 📋 Planned | LOW |
+| **Phase 3**: Deprecation | 1 week | 📋 Planned | MEDIUM |
+| **Phase 4**: Full Migration | Future | 🤔 Optional | MEDIUM |
+
+**Total**: 4 weeks for Phases 1-3
+**Effort**: ~20-30 hours development time
+
+---
+
+## Decision: Which Approach?
+
+### Option A: Full v2.0 Migration (Recommended) ✅
+
+**Pros**:
+- ✅ Clear semantic separation
+- ✅ Future-proof organization
+- ✅ Best user experience
+- ✅ Solves all identified problems
+
+**Cons**:
+- ❌ 4-week migration period
+- ❌ Affects 30+ commands
+- ❌ Requires documentation updates
+
+**Recommendation**: **YES** - Worth the investment
+
+### Option B: Minimal Changes (Quick Fix)
+
+**Change**:
+```
+.chat/ → Split into .analysis/ and .executions/
+.process/ → Keep as-is with better docs
+```
+
+**Pros**:
+- ✅ Quick implementation (1 week)
+- ✅ Solves main safety confusion
+
+**Cons**:
+- ❌ Partial solution
+- ❌ Still some confusion
+- ❌ May need full migration later anyway
+
+**Recommendation**: Only if time-constrained
+
+### Option C: Status Quo (No Change)
+
+**Pros**:
+- ✅ No development effort
+
+**Cons**:
+- ❌ Problems remain
+- ❌ User confusion continues
+- ❌ Safety risks
+
+**Recommendation**: **NO** - Not recommended
+
+---
+
+## Conclusion
+
+**Recommended Action**: Proceed with **Option A (Full v2.0 Migration)**
+
+**Key Benefits**:
+1. 🟢 Clear safety separation (read-only vs code-modifying)
+2. 📁 Semantic organization by purpose
+3. 🔍 Easy to find specific outputs
+4. 📈 Scales for future growth
+5. 👥 Better user experience
+
+**Next Steps**:
+1. ✅ Review and approve this proposal
+2. 📋 Create detailed implementation tasks
+3. 🚀 Begin Phase 1: Dual Write implementation
+4. 📚 Update documentation in parallel
+
+**Questions?**
+- See detailed analysis in: `OUTPUT_DIRECTORY_REORGANIZATION.md`
+- Implementation guide: Migration Strategy section
+- Risk assessment: Risk Assessment section