Claude-Code-Workflow/docs/skills/codex-workflow.md

Codex Skills - Workflow Category

One-Liner

Workflow Codex Skills is a collaborative analysis and parallel development workflow system — enabling efficient team collaboration through documented discussions, multi-perspective analysis, and collaborative planning.

Pain Points Solved

Pain Point	Current State	Codex Skills Solution
Discussion process lost	Only conclusions saved from discussions	Documented discussion timeline
Repeated exploration	Codebase re-explored for each analysis	Shared discovery board
Blind debugging	No hypothesis verification mechanism	Hypothesis-driven debugging
Fragmented collaboration	Roles work independently	Multi-perspective parallel analysis

Skills List

Skill	Function	Trigger
analyze-with-file	Collaborative analysis (4 perspectives)	/analyze-with-file TOPIC="..."
brainstorm-with-file	Brainstorming (4 perspectives)	/brainstorm-with-file TOPIC="..."
debug-with-file	Hypothesis-driven debugging	/debug-with-file BUG="..."
collaborative-plan-with-file	Collaborative planning	/collaborative-plan-with-file <task>
unified-execute-with-file	Universal execution engine	/unified-execute-with-file <session>
roadmap-with-file	Requirement roadmap	/roadmap-with-file <requirements>
review-cycle	Review cycle	/review-cycle <target>
workflow-test-fix-cycle	Test-fix workflow	/workflow-test-fix-cycle <tests>

Skills Details

analyze-with-file

One-Liner: Collaborative analysis — interactive analysis with documented discussions, inline exploration, and evolving understanding

Core Workflow:

Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute

Key Features:

• Documented discussion timeline: Capture understanding evolution across all phases
• Decision logging at every key point: Force recording of key findings, direction changes, trade-offs
• Multi-perspective analysis: Support up to 4 analysis perspectives (serial, inline)
• Interactive discussion: Multi-round Q&A, user feedback and direction adjustment
• Quick execute: Direct conversion of conclusions to executable tasks

Decision Recording Protocol:

Trigger	Content to Record	Target Section
Direction choice	Choice, reason, alternatives	#### Decision Log
Key findings	Finding, impact scope, confidence	#### Key Findings
Assumption change	Old assumption → New understanding, reason, impact	#### Corrected Assumptions
User feedback	User's raw input, adoption/adjustment reason	#### User Input

Analysis Perspectives (serial, inline):

Perspective	CLI Tool	Role	Focus Areas
Product	gemini	Product Manager	Market fit, user value, business viability
Technical	codex	Tech Lead	Feasibility, tech debt, performance, security
Quality	claude	QA Lead	Completeness, testability, consistency
Risk	gemini	Risk Analyst	Risk identification, dependencies, failure modes

Session Folder Structure:

{projectRoot}/.workflow/.analyze/ANL-{slug}-{date}/
├── discussion.md               # Discussion timeline + understanding evolution
├── explorations/               # Codebase exploration reports
│   ├── exploration-summary.md
│   ├── relevant-files.md
│   └── patterns.md
└── conclusion.md               # Final conclusion + Quick execute task

Execution Flow:

Phase 1: Topic Analysis
    ├─ Detect depth mode (quick/standard/deep)
    ├─ Session detection: {projectRoot}/.workflow/.analyze/ANL-{slug}-{date}/
    └─ Output: sessionId, depth, continueMode

Phase 2: Exploration
    ├─ Detect context: discovery-context.json, prep-package.json
    ├─ Codebase exploration: Glob + Read + Grep tools
    ├─ Write: explorations/exploration-summary.md
    └─ Output: explorationResults

Phase 3: Discussion (Multiple Rounds)
    ├─ Initialize: discussion.md (Section: Exploration Summary)
    ├─ Round 1: Generate initial analysis based on explorationResults
    ├─ Iterate: User feedback → Refine understanding → Update discussion.md
    └─ Per-round update: Decision Log, Key Findings, Current Understanding

Phase 4: Refinement
    ├─ Merge: explorations/ content merged into discussion.md
    ├─ Check: All key points recorded
    └─ Output: refinedDiscussion

Phase 5: Conclusion
    ├─ Generate: conclusion.md (Executive Summary, Findings, Recommendations)
    └─ Quick Execute (optional): Generate executable tasks

Phase 6: (Optional) Quick Execute
    ├─ Convert conclusions to: task JSON or plan file
    └─ Invoke: workflow-execute or direct execution

Depth Modes:

Mode	Exploration Scope	Analysis Rounds
quick	Basic search, 10 files	1 round
standard	Standard exploration, 30 files	2-3 rounds
deep	Deep exploration, 100+ files	3-5 rounds

---

brainstorm-with-file

One-Liner: Multi-perspective brainstorming — 4 perspectives (Product, Technical, Risk, User) parallel analysis

Key Features:

• 4-perspective parallel analysis: Product, Technical, Risk, User
• Consistency scoring and convergence determination
• Feasibility recommendations and action items

Perspectives:

Perspective	Focus Areas
Product	Market fit, user value, business viability
Technical	Feasibility, tech debt, performance, security
Risk	Risk identification, dependencies, failure modes
User	Usability, user experience, adoption barriers

Output Format:

## Consensus Determination
Status: <consensus_reached | consensus_blocked>
Average Rating: <N>/5
Convergence Points: <list>
Divergence Points: <list>

## Feasibility Recommendation
Recommendation: <proceed | proceed-with-caution | revise | reject>
Reasoning: <reasoning>
Action Items: <action items>

---

debug-with-file

One-Liner: Hypothesis-driven debugging — documented exploration, understanding evolution, analysis-assisted correction

Core Workflow:

Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify

Key Enhancements:

• understanding.md: Timeline of exploration and learning
• Analysis-assisted correction: Verify and correct assumptions
• Consolidation: Simplify proven-misunderstood concepts to avoid confusion
• Learning preservation: Retain insights from failed attempts

Session Folder Structure:

{projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
├── debug.log           # NDJSON log (execution evidence)
├── understanding.md    # Exploration timeline + consolidated understanding
└── hypotheses.json     # Hypothesis history (with determination)

Modes:

Mode	Trigger Condition	Behavior
Explore	No session or no understanding.md	Locate error source, record initial understanding, generate hypotheses, add logs
Continue	Session exists but no debug.log content	Wait for user reproduction
Analyze	debug.log has content	Parse logs, evaluate hypotheses, update understanding

Hypothesis Generation: Generate targeted hypotheses based on error patterns:

Error Pattern	Hypothesis Type
not found / missing / undefined	data_mismatch
0 / empty / zero / registered	logic_error
timeout / connection / sync	integration_issue
type / format / parse	type_mismatch

NDJSON Log Format:

{"sid":"DBG-xxx-2025-01-21","hid":"H1","loc":"file.py:func:42","msg":"Check dict keys","data":{"keys":["a","b"],"target":"c","found":false},"ts":1734567890123}

Understanding Document Template:

# Understanding Document

**Session ID**: DBG-xxx-2025-01-21
**Bug Description**: [original description]
**Started**: 2025-01-21T10:00:00+08:00

---

## Exploration Timeline

### Iteration 1 - Initial Exploration (2025-01-21 10:00)

#### Current Understanding
...

#### Evidence from Code Search
...

#### Hypotheses Generated
...

---

## Current Consolidated Understanding

### What We Know
- [valid understanding points]

### What Was Disproven
- ~~[disproven assumptions]~~

### Current Investigation Focus
[current focus]

---

collaborative-plan-with-file

One-Liner: Collaborative planning — multi-agent collaborative planning (alternative to team-planex)

Features:

• Multi-agent collaborative planning
• planner and executor work in parallel
• Intermediate artifact files pass solution

Wave Pipeline (per-issue beat):

Issue 1:  planner plans solution → write intermediate artifact → conflict check → create EXEC-* → issue_ready
                ↓ (executor starts immediately)
Issue 2:  planner plans solution → write intermediate artifact → conflict check → create EXEC-* → issue_ready
                ↓ (executor consumes in parallel)
Issue N:  ...
Final:    planner sends all_planned → executor completes remaining EXEC-* → finish

---

unified-execute-with-file

One-Liner: Universal execution engine — alternative to workflow-execute

Features:

• Universal execution engine
• Support multiple task types
• Automatic session recovery

Session Discovery:

1. Count active sessions in .workflow/active/
2. Decision:
   • count=0 → Error: No active session
   • count=1 → Auto-select session
   • count>1 → AskUserQuestion (max 4 options)

---

roadmap-with-file

One-Liner: Requirement roadmap planning

Features:

• Requirement to roadmap planning
• Priority sorting
• Milestone definition

Output Structure:

.workflow/.roadmap/{session-id}/
├── roadmap.md                 # Roadmap document
├── milestones.md              # Milestone definitions
└── priorities.json            # Priority sorting

---

review-cycle

One-Liner: Review cycle (Codex version)

Features:

• Code review
• Fix loop
• Verify fix effectiveness

Loop Flow:

Review code → Find issues → [Has issues] → Fix code → Verify → [Still has issues] → Fix code
                          ↑______________|

---

workflow-test-fix-cycle

One-Liner: Test-fix workflow

Features:

• Diagnose test failure causes
• Fix code or tests
• Verify fixes
• Loop until passing

Flow:

Diagnose failure → Identify root cause → [Code issue] → Fix code → Verify
                          ↑___________|

Related Commands

• Codex Skills - Lifecycle
• Codex Skills - Specialized
• Claude Skills - Workflow

Best Practices

1. Choose the right workflow:

   • Collaborative analysis → analyze-with-file
   • Brainstorming → brainstorm-with-file
   • Debugging → debug-with-file
   • Planning → collaborative-plan-with-file

2. Documented discussions: Utilize documented discussion timeline to capture understanding evolution

3. Decision logging: Record decisions at key points to preserve decision history

4. Hypothesis-driven debugging: Use hypothesis-driven debugging to systematically solve problems

5. Multi-perspective analysis: Leverage multi-perspective parallel analysis for comprehensive understanding

Usage Examples

# Collaborative analysis
/analyze-with-file TOPIC="How to optimize database queries?"

# Deep analysis
/analyze-with-file TOPIC="Architecture for microservices" --depth=deep

# Brainstorming
/brainstorm-with-file TOPIC="Design payment system"

# Debugging
/debug-with-file BUG="System crashes intermittently"

# Collaborative planning
/collaborative-plan-with-file "Add user notifications"

# Test-fix
/workflow-test-fix-cycle "Unit tests failing"