Initial commit
This commit is contained in:
Zhongwei Li
441
commands/utils:update-checklist.md
Normal file
441
commands/utils:update-checklist.md
Normal file
@@ -0,0 +1,441 @@
|
||||
---
|
||||
description: Update Implementation Checklist items in Linear issue description
|
||||
allowed-tools: [LinearMCP, AskUserQuestion, Bash]
|
||||
argument-hint: <linear-issue-id>
|
||||
---
|
||||
|
||||
# Update Checklist: $1
|
||||
|
||||
Updating Implementation Checklist directly in the Linear issue description.
|
||||
|
||||
## 🚨 CRITICAL: Safety Rules
|
||||
|
||||
**READ FIRST**: ``$CCPM_COMMANDS_DIR/SAFETY_RULES.md``
|
||||
|
||||
**NEVER** submit, post, or update anything to Jira, Confluence, BitBucket, or Slack without explicit user confirmation.
|
||||
|
||||
- ✅ **Linear** operations are permitted (our internal tracking)
|
||||
- ⛔ **External PM systems** require user confirmation for write operations
|
||||
|
||||
## Checklist Update Workflow
|
||||
|
||||
### Step 1: Fetch Linear Issue
|
||||
|
||||
Use **Linear MCP** to get issue: $1
|
||||
|
||||
Extract:
|
||||
- Full description (markdown)
|
||||
- Current status
|
||||
- Title
|
||||
|
||||
### Step 2: Parse Checklist from Description
|
||||
|
||||
Look for the Implementation Checklist section in the description using these markers:
|
||||
|
||||
**Pattern 1: Marker Comments (Preferred)**
|
||||
```markdown
|
||||
<!-- ccpm-checklist-start -->
|
||||
- [ ] Task 1: Description
|
||||
- [x] Task 2: Description (completed)
|
||||
- [ ] Task 3: Description
|
||||
<!-- ccpm-checklist-end -->
|
||||
```
|
||||
|
||||
**Pattern 2: Header-Based (Fallback)**
|
||||
```markdown
|
||||
## ✅ Implementation Checklist
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
...
|
||||
(until next ## header or end of content)
|
||||
```
|
||||
|
||||
**Parsing Logic:**
|
||||
1. Search for `<!-- ccpm-checklist-start -->` marker
|
||||
2. If found, extract all lines between start and end markers
|
||||
3. If not found, look for "## ✅ Implementation Checklist" or similar headers
|
||||
4. Extract all checklist items (lines starting with `- [ ]` or `- [x]`)
|
||||
5. Parse each item to extract:
|
||||
- Index (0-based position)
|
||||
- Status (checked or unchecked)
|
||||
- Content (the text after the checkbox)
|
||||
|
||||
**Edge Cases:**
|
||||
- No checklist found → Display warning, offer to skip
|
||||
- Corrupted format → Attempt recovery, show warning
|
||||
- Multiple checklists → Use marker comments to identify the right one
|
||||
- Empty checklist → Display error
|
||||
|
||||
### Step 3: Display Current Checklist
|
||||
|
||||
Show current state with indices:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📋 Current Implementation Checklist ($1)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Progress: X% (Y/Z completed)
|
||||
|
||||
0. [ ] Task 1: Description
|
||||
1. [x] Task 2: Description ✅
|
||||
2. [ ] Task 3: Description
|
||||
3. [ ] Task 4: Description
|
||||
4. [x] Task 5: Description ✅
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
### Step 4: Choose Update Mode
|
||||
|
||||
First, ask user if they want to mark items complete or rollback (uncheck) items:
|
||||
|
||||
Use **AskUserQuestion**:
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "What would you like to do with the checklist?",
|
||||
header: "Action",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Mark items complete",
|
||||
description: "Check off completed tasks (default)"
|
||||
},
|
||||
{
|
||||
label: "Rollback items",
|
||||
description: "Uncheck incorrectly marked items"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Interactive Selection
|
||||
|
||||
**If "Mark items complete" selected:**
|
||||
|
||||
Use **AskUserQuestion** with multi-select to let user choose which items to check:
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Which checklist items did you complete? (Select all that apply)",
|
||||
header: "Completed",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{
|
||||
label: "0: Task 1: Description",
|
||||
description: "Mark this task as complete"
|
||||
},
|
||||
{
|
||||
label: "2: Task 3: Description",
|
||||
description: "Mark this task as complete"
|
||||
},
|
||||
{
|
||||
label: "3: Task 4: Description",
|
||||
description: "Mark this task as complete"
|
||||
}
|
||||
// Only show UNCHECKED items
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**If "Rollback items" selected:**
|
||||
|
||||
Use **AskUserQuestion** with multi-select to let user choose which items to uncheck:
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Which items were incorrectly marked complete? (Select all to rollback)",
|
||||
header: "Rollback",
|
||||
multiSelect: true,
|
||||
options: [
|
||||
{
|
||||
label: "1: Task 2: Description",
|
||||
description: "Uncheck this item (mark incomplete)"
|
||||
},
|
||||
{
|
||||
label: "4: Task 5: Description",
|
||||
description: "Uncheck this item (mark incomplete)"
|
||||
}
|
||||
// Only show CHECKED items
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Parse user selections:**
|
||||
- Extract indices from selected options (first number before ":")
|
||||
- Store as array of indices
|
||||
- Store mode: "complete" or "rollback"
|
||||
|
||||
### Step 6: Update Checklist via Linear Operations Subagent
|
||||
|
||||
**Use the Task tool to update the checklist:**
|
||||
|
||||
Invoke the `ccpm:linear-operations` subagent:
|
||||
- **Tool**: Task
|
||||
- **Subagent**: ccpm:linear-operations
|
||||
- **Prompt**:
|
||||
```
|
||||
operation: update_checklist_items
|
||||
params:
|
||||
issue_id: "{issue ID from step 1}"
|
||||
indices: [{selected indices from step 5}]
|
||||
mark_complete: {true if mode is "complete", false if mode is "rollback"}
|
||||
add_comment: true # Document the change with a comment
|
||||
update_timestamp: true
|
||||
context:
|
||||
command: "utils:update-checklist"
|
||||
purpose: "Manual checklist update by user"
|
||||
```
|
||||
|
||||
**This operation will:**
|
||||
1. Use shared checklist helpers (`_shared-checklist-helpers.md`) for parsing
|
||||
2. Update the specified checkbox states (✓ or uncheck)
|
||||
3. Recalculate progress percentage automatically
|
||||
4. Update the progress line with current timestamp
|
||||
5. Add a comment documenting the changes
|
||||
6. Return structured result with before/after progress
|
||||
|
||||
**Example response:**
|
||||
```yaml
|
||||
success: true
|
||||
data:
|
||||
checklist_summary:
|
||||
items_updated: 2
|
||||
previous_progress: 20
|
||||
new_progress: 60
|
||||
completed: 3
|
||||
total: 5
|
||||
changed_items:
|
||||
- index: 1
|
||||
content: "Task 2: Description"
|
||||
previous_state: unchecked
|
||||
new_state: checked
|
||||
metadata:
|
||||
duration_ms: 320
|
||||
used_shared_helpers: true
|
||||
```
|
||||
|
||||
### Step 7: Display Confirmation
|
||||
|
||||
Show success message with details
|
||||
|
||||
**Timestamp**: [current date/time]
|
||||
```
|
||||
|
||||
**If mode is "rollback":**
|
||||
```markdown
|
||||
## 🔄 Checklist Rollback
|
||||
|
||||
**Progress**: X% → Y% (-Z%)
|
||||
|
||||
**Unmarked Items** (marked incomplete):
|
||||
- ⏪ Task 2: Description
|
||||
- ⏪ Task 3: Description
|
||||
|
||||
**Reason**: Incorrectly marked complete, rolling back for accuracy
|
||||
|
||||
**Timestamp**: [current date/time]
|
||||
```
|
||||
|
||||
3. **Track version history** in comment:
|
||||
- Include previous state
|
||||
- Include new state
|
||||
- Record who made the change and why
|
||||
|
||||
### Step 8: Display Confirmation
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
✅ Checklist Updated Successfully!
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
📋 Issue: $1
|
||||
🔗 Linear: [issue URL]
|
||||
|
||||
📊 Progress: X% → Y% (+Z%)
|
||||
|
||||
✅ Marked Complete (N items):
|
||||
• Task 2: Description
|
||||
• Task 3: Description
|
||||
|
||||
📝 Updated in Linear:
|
||||
✅ Issue description updated
|
||||
✅ Progress comment added
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🎯 Next Actions
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
1. ⭐ Continue Implementation
|
||||
/ccpm:implementation:next $1
|
||||
|
||||
2. Sync Progress
|
||||
/ccpm:implementation:sync $1
|
||||
|
||||
3. Run Quality Checks
|
||||
/ccpm:verification:check $1
|
||||
|
||||
4. View Updated Status
|
||||
/ccpm:utils:status $1
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
```
|
||||
|
||||
## Helper Functions (Inline Logic)
|
||||
|
||||
### Parse Checklist
|
||||
|
||||
**Pseudocode:**
|
||||
```
|
||||
1. Get description text
|
||||
2. Find start marker: <!-- ccpm-checklist-start -->
|
||||
3. Find end marker: <!-- ccpm-checklist-end -->
|
||||
4. If markers found:
|
||||
- Extract lines between markers
|
||||
5. Else:
|
||||
- Find "## ✅ Implementation Checklist" or "## Implementation Checklist"
|
||||
- Extract lines until next ## header
|
||||
6. Filter lines that match: /^- \[([ x])\] (.+)$/
|
||||
7. Parse each line:
|
||||
- Extract checkbox state: [ ] or [x]
|
||||
- Extract content after checkbox
|
||||
- Store index, state, content
|
||||
8. Return array of checklist items
|
||||
```
|
||||
|
||||
### Calculate Completion
|
||||
|
||||
**Pseudocode:**
|
||||
```
|
||||
1. Count total items
|
||||
2. Count checked items (- [x])
|
||||
3. Calculate percentage: (checked / total) * 100
|
||||
4. Round to nearest integer
|
||||
5. Return percentage and counts
|
||||
```
|
||||
|
||||
### Update Checklist Items
|
||||
|
||||
**Pseudocode:**
|
||||
```
|
||||
1. Get current description
|
||||
2. Parse checklist (get start/end positions)
|
||||
3. For each index in indices_to_complete:
|
||||
- Find line in checklist section
|
||||
- Replace "- [ ]" with "- [x]"
|
||||
4. Calculate new completion %
|
||||
5. Find or create progress line
|
||||
6. Update progress line with new %
|
||||
7. Add/update timestamp
|
||||
8. Return modified description
|
||||
```
|
||||
|
||||
## Rollback Capability (Built-in)
|
||||
|
||||
The rollback feature is now fully integrated into the main workflow (Step 4):
|
||||
|
||||
**Features:**
|
||||
- ✅ Two-mode operation: Complete or Rollback
|
||||
- ✅ Rollback shows only checked items
|
||||
- ✅ Complete shows only unchecked items
|
||||
- ✅ Version history tracked in comments
|
||||
- ✅ Clear reasoning documented
|
||||
|
||||
**Use Cases:**
|
||||
- Accidentally marked wrong item complete
|
||||
- Item thought complete but needs more work
|
||||
- Task requirements changed, no longer complete
|
||||
- Quality issues discovered after marking complete
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Mark Multiple Items Complete
|
||||
|
||||
```bash
|
||||
/ccpm:utils:update-checklist PSN-26
|
||||
```
|
||||
|
||||
**Interactive Flow:**
|
||||
```
|
||||
Current Progress: 20% (1/5 completed)
|
||||
|
||||
Which items did you complete?
|
||||
[x] 0: Create checklist parser functions
|
||||
[ ] 2: Modify /ccpm:implementation:sync
|
||||
[ ] 3: Modify /ccpm:implementation:update
|
||||
|
||||
→ User selects items 0 and 2
|
||||
|
||||
✅ Updated! Progress: 20% → 60% (+40%)
|
||||
```
|
||||
|
||||
### Example 2: No Changes Needed
|
||||
|
||||
```bash
|
||||
/ccpm:utils:update-checklist PSN-26
|
||||
```
|
||||
|
||||
**Interactive Flow:**
|
||||
```
|
||||
Current Progress: 100% (5/5 completed)
|
||||
|
||||
All items complete! ✅
|
||||
|
||||
No changes needed.
|
||||
```
|
||||
|
||||
### Example 3: Rollback Mistake
|
||||
|
||||
```bash
|
||||
/ccpm:utils:update-checklist PSN-26
|
||||
```
|
||||
|
||||
**Interactive Flow:**
|
||||
```
|
||||
What would you like to do?
|
||||
( ) Mark items complete
|
||||
(●) Rollback items
|
||||
|
||||
Which items were incorrectly marked complete?
|
||||
[x] 3: Modify /ccpm:implementation:update
|
||||
[x] 4: Modify /ccpm:verification:check
|
||||
|
||||
→ User selects items 3 and 4
|
||||
|
||||
✅ Rolled back! Progress: 80% → 40% (-40%)
|
||||
|
||||
Comment added:
|
||||
"🔄 Checklist Rollback
|
||||
Unmarked: Task 3, Task 4
|
||||
Reason: Incorrectly marked complete, rolling back for accuracy"
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **Idempotent**: Running multiple times is safe
|
||||
- **Atomic**: Either all updates succeed or none
|
||||
- **Tracked**: Every change creates a comment for history
|
||||
- **Visible**: Progress visible in description, not just comments
|
||||
- **Flexible**: Works with or without marker comments
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
This command provides the core checklist update logic that other commands can reference:
|
||||
|
||||
- `/ccpm:implementation:sync` - Auto-suggest completed items based on git diff
|
||||
- `/ccpm:implementation:update` - Update specific item by index
|
||||
- `/ccpm:verification:check` - Check completion % before verification
|
||||
- `/ccpm:complete:finalize` - Require 100% before finalization
|
||||
Reference in New Issue
Block a user