gh-duongdev-ccpm/commands/utils:update-checklist.md

description, allowed-tools, argument-hint

description	allowed-tools	argument-hint
Update Implementation Checklist items in Linear issue description	LinearMCP AskUserQuestion Bash	<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)

<!-- ccpm-checklist-start -->
- [ ] Task 1: Description
- [x] Task 2: Description (completed)
- [ ] Task 3: Description
<!-- ccpm-checklist-end -->

Pattern 2: Header-Based (Fallback)

## ✅ 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:

{
  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:

{
  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:

{
  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:

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

/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

/ccpm:utils:update-checklist PSN-26

Interactive Flow:

Current Progress: 100% (5/5 completed)

All items complete! ✅

No changes needed.

Example 3: Rollback Mistake

/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