Skip to content

Commit d027308

Browse files
authored
feat: Add Step 0 Workflow Preparation to prevent step skipping (#1608)
Adds Step 0: Workflow Preparation (MANDATORY) to prevent agents from skipping mandatory workflow steps. Key changes: - Step 0 with root cause analysis and TodoWrite requirement - Prerequisite check at Step 1 for redundant verification - Updated workflow to 22 steps (0-21) Closes #1607 🤖 Generated with [Claude Code](https://claude.com/claude-code)
1 parent 4d5bbeb commit d027308

File tree

1 file changed

+56
-14
lines changed

1 file changed

+56
-14
lines changed

.claude/workflow/DEFAULT_WORKFLOW.md

Lines changed: 56 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
name: DEFAULT_WORKFLOW
3-
version: 1.0.0
4-
description: Standard 21-step workflow for feature development, bug fixes, and refactoring
5-
steps: 21
3+
version: 1.1.0
4+
description: Standard 22-step workflow (Steps 0-21) for feature development, bug fixes, and refactoring
5+
steps: 22
66
phases:
77
- requirements-clarification
88
- design
@@ -81,28 +81,33 @@ When creating todos during workflow execution, reference the workflow steps dire
8181
- **Be Specific**: Include the specific agent or action for each step
8282
- Example: `Step 5: Implement the Solution - Use builder agent from specifications`
8383

84-
- **Track Progress**: Users can see exactly which step is active (e.g., "Step 5 of 15")
84+
- **Track Progress**: Users can see exactly which step is active (e.g., "Step 5 of 22")
8585

8686
**Example Todo Structure (Single Workflow):**
8787

8888
```
89-
Step 1: Rewrite and Clarify Requirements - Use prompt-writer agent to clarify task
90-
Step 2: Create GitHub Issue - Define requirements and constraints using gh issue create
91-
Step 3: Setup Worktree and Branch - Create feat/issue-XXX branch in worktrees/
92-
Step 4: Research and Design - Use architect agent for solution design
93-
Step 5: Implement the Solution - Use builder agent to implement from specifications
89+
Step 0: Workflow Preparation - Read workflow, create todos for ALL steps (0-21)
90+
Step 1: Prepare the Workspace - Check git status and fetch
91+
Step 2: Rewrite and Clarify Requirements - Use prompt-writer agent to clarify task
92+
Step 3: Create GitHub Issue - Define requirements and constraints using gh issue create
93+
Step 4: Setup Worktree and Branch - Create feat/issue-XXX branch in worktrees/
94+
Step 5: Research and Design - Use architect agent for solution design
9495
...
96+
Step 16: Review the PR - MANDATORY code review
97+
Step 17: Implement Review Feedback - MANDATORY
98+
...
99+
Step 21: Ensure PR is Mergeable - TASK COMPLETION POINT
95100
```
96101

97102
**Example Todo Structure (Multiple Parallel Workflows):**
98103

99104
```
100-
[PR1090 TASK] Step 1: Rewrite and Clarify Requirements - Use prompt-writer agent
101-
[PR1090 TASK] Step 2: Create GitHub Issue - Define requirements using gh issue create
102-
[PR1090 TASK] Step 4: Research and Design - Use architect agent for solution design
103-
[FEATURE-X] Step 1: Rewrite and Clarify Requirements - Use prompt-writer agent
105+
[PR1090 TASK] Step 0: Workflow Preparation - Create todos for ALL steps (0-21)
106+
[PR1090 TASK] Step 1: Prepare the Workspace - Check git status
107+
[PR1090 TASK] Step 2: Rewrite and Clarify Requirements - Use prompt-writer agent
108+
[FEATURE-X] Step 0: Workflow Preparation - Create todos for ALL steps (0-21)
104109
[FEATURE-X] Step 3: Setup Worktree and Branch - Create feat/issue-XXX branch
105-
[BUGFIX-Y] Step 5: Implement the Solution - Use builder agent from specifications
110+
[BUGFIX-Y] Step 16: Review the PR - MANDATORY code review
106111
...
107112
```
108113

@@ -114,8 +119,45 @@ This step-based structure helps users understand:
114119

115120
## The Workflow
116121

122+
### Step 0: Workflow Preparation (MANDATORY - DO NOT SKIP)
123+
124+
**CRITICAL: This step MUST be completed before ANY implementation work begins.**
125+
126+
**Why This Step Exists:**
127+
128+
Agents that skip workflow steps (especially mandatory review steps 10, 16-17) create quality issues and erode user trust. This step ensures agents track ALL steps from the start, preventing "completion bias" where agents feel done after implementation but before review.
129+
130+
**Root Cause Prevention:**
131+
132+
- **Completion Bias**: Agents often consider "PR created" as task completion
133+
- **Context Decay**: After heavy implementation, agents lose sight of remaining steps
134+
- **Autonomy Misapplication**: Being autonomous means making implementation decisions independently, NOT skipping mandatory process steps
135+
136+
**Checklist:**
137+
138+
- [ ] **Read this entire workflow file** - Understand all 22 steps (0-21) before starting
139+
- [ ] **Create TodoWrite entries for ALL steps (0-21)** using format: `Step N: [Step Name] - [Specific Action]`
140+
- [ ] **Mark each step complete ONLY when truly done** - No premature completion
141+
- [ ] **Task is NOT complete until Step 21 is marked complete**
142+
143+
**Self-Verification:** Before proceeding to Step 1, confirm you have 22 todo items visible (Steps 0-21).
144+
145+
**Anti-Pattern Prevention:**
146+
147+
- ❌ DO NOT skip to implementation after reading requirements
148+
- ❌ DO NOT consider "PR created" as completion (Step 21 is the completion point)
149+
- ❌ DO NOT omit Steps 10, 16-17 (mandatory review steps)
150+
- ❌ DO NOT declare task complete with pending steps
151+
- ✅ DO create all step todos BEFORE starting any implementation
152+
- ✅ DO mark steps complete sequentially as you finish them
153+
- ✅ DO track every mandatory step in TodoWrite
154+
155+
**Reference Issue:** This step was added after Issue #1607 identified workflow step skipping as a recurring problem.
156+
117157
### Step 1: Prepare the Workspace
118158

159+
**Prerequisite Check:** Verify Step 0 is complete - you should have 22 todos visible (Steps 0-21) before proceeding.
160+
119161
- [ ] start with a clean local environment and make sure it is up to date (no unstashed changes, git fetch)
120162

121163
### Step 2: Rewrite and Clarify Requirements

0 commit comments

Comments
 (0)