Claude-Code-Workflow/COMMAND_AMBIGUITY_ANALYSIS.md

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.