workflow-state-tracking

What this skill does

# Workflow State Tracking

This skill provides real-time visibility into your CCPM workflow progress, prevents invalid state transitions, and guides you toward task completion through intelligent next action suggestions.

## State Machine Overview

CCPM uses a structured 8-state workflow that progresses from concept to completion. Understanding these states helps you know exactly where you are and what to do next.

### The 8 Workflow States

```
IDEA (💡)
  ↓
PLANNED (📋)
  ↓
IMPLEMENTING (🚀) ←→ BLOCKED (🚫)
  ↓
VERIFYING (🔍)
  ↓
VERIFIED (✅)
  ↓
COMPLETE (🎉)

CANCELLED (❌) - Terminal, can branch from any state
```

### State Definitions

| State | Phase | Description | Linear Status | Progress |
|-------|-------|-------------|---------------|----------|
| **IDEA** | Ideation | Initial concept, not yet planned | Backlog | 0% |
| **PLANNED** | Planning | Requirements gathered, plan created | Planned, Todo | 25% |
| **IMPLEMENTING** | Implementation | Active development in progress | In Progress, In Development | 50% |
| **BLOCKED** | Implementation | Cannot proceed due to blocker | Blocked | 50% |
| **VERIFYING** | Verification | Quality checks and review in progress | In Review, Testing | 75% |
| **VERIFIED** | Verification | Verified and ready to finalize | Verified, Approved | 90% |
| **COMPLETE** | Completion | Task finalized and closed | Done, Completed | 100% |
| **CANCELLED** | Cancelled | Task cancelled or abandoned | Cancelled, Archived | 0% |

### State Properties

- **Terminal States**: COMPLETE and CANCELLED (no transitions out)
- **Blocking States**: BLOCKED (prevents progression to VERIFYING)
- **Gating States**: VERIFIED (required before COMPLETE)
- **Reversible States**: IMPLEMENTING can return to PLANNED if re-planning needed

## State Detection

When you ask "Where am I?", this skill detects your current state by checking:

### 1. Linear Custom Fields
Most accurate: Reads CCPM custom fields directly from Linear issue
```
- ccpmPhase: Current state (IDEA, PLANNED, etc.)
- ccpmLastCommand: Last CCPM command executed
- ccpmLastUpdate: Timestamp of last update
- ccpmAutoTransitions: Whether state auto-updates
```

### 2. Linear Status Inference (Fallback)
If custom fields missing, infers from Linear status:
- "Backlog" → IDEA
- "Planned", "Todo", "Ready" → PLANNED
- "In Progress", "In Development" → IMPLEMENTING
- "Blocked" → BLOCKED
- "In Review", "Testing" → VERIFYING
- "Verified", "Approved" → VERIFIED
- "Done", "Completed" → COMPLETE
- "Cancelled", "Archived" → CANCELLED

### 3. Checklist Completion Analysis
Analyzes implementation checklist progress:
- 0-25% complete → Early IMPLEMENTING
- 50-75% complete → Mid IMPLEMENTING
- 80-99% complete → Near VERIFYING
- 100% complete → Ready to VERIFY

### 4. Git State Detection
Checks for uncommitted changes:
- Changes detected → Still IMPLEMENTING
- No changes → Ready for VERIFYING

## Valid Transitions

Each state has specific allowed transitions. Attempting an invalid transition will be prevented with helpful suggestions.

### Transition Matrix

```javascript
IDEA        → PLANNED, CANCELLED
PLANNED     → IMPLEMENTING, IDEA, CANCELLED
IMPLEMENTING → VERIFYING, PLANNED, BLOCKED
BLOCKED     → IMPLEMENTING, CANCELLED
VERIFYING   → VERIFIED, IMPLEMENTING
VERIFIED    → COMPLETE, IMPLEMENTING
COMPLETE    → (terminal - no transitions)
CANCELLED   → (terminal - no transitions)
```

### Confidence Levels

Each transition has a confidence score (0-100) indicating how certain the system is:
- **95%**: High confidence (plan ready to implement)
- **85%**: Good confidence (checks passing)
- **70%**: Medium confidence (re-planning during implementation)
- **50%**: Low confidence (requires explicit user confirmation)

## Invalid Transition Prevention

The skill prevents invalid workflows and provides helpful corrections:

### Common Invalid Transitions

```
❌ IDEA → IMPLEMENTING (skip planning)
   Suggestion: Run /ccpm:plan first

❌ IDEA → VERIFYING (skip planning + implementation)
   Suggestion: Follow workflow: IDEA → PLANNED → IMPLEMENTING → VERIFYING

❌ PLANNED → VERIFYING (skip implementation)
   Suggestion: Run /ccpm:work to start implementation

❌ IMPLEMENTING → COMPLETE (skip verification)
   Suggestion: Run /ccpm:verify first

❌ VERIFYING → COMPLETE (skip verified state)
   Suggestion: Fix issues and re-verify, then transition to VERIFIED

❌ COMPLETE → IMPLEMENTING (reopen completed task)
   Suggestion: Create new issue for follow-up work
```

### Pre-Condition Checks

Before allowing transitions, the skill validates pre-conditions:

**Transition to PLANNED requires**:
- ✓ Implementation checklist exists in issue description
- ✓ Basic requirements documented

**Transition to IMPLEMENTING requires**:
- ✓ Plan exists (checklist section)
- ✓ Linear status allows (not in terminal state)

**Transition to VERIFYING requires**:
- ✓ Checklist 100% complete (or bypassed)
- ✓ No uncommitted git changes
- ✓ Code review initiated

**Transition to VERIFIED requires**:
- ✓ All quality checks passing
- ✓ Code review approved
- ✓ No security issues

**Transition to COMPLETE requires**:
- ✓ In VERIFIED state
- ✓ PR merged
- ✓ All checks passed

## State Visualization

### Progress Indicator

Visual representation of task completion:
```
IDEA:         [░░░░░░░░░░] 0%
PLANNED:      [██░░░░░░░░] 25%
IMPLEMENTING: [████████░░] 50%
VERIFYING:    [██████████░] 75%
VERIFIED:     [███████████░] 90%
COMPLETE:     [████████████] 100%
```

### Current State Display

When checking status, you see:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 Workflow State
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🚀 Phase: IMPLEMENTING
📋 Status: In Progress
⚙️  Last Command: /ccpm:work
🕐 Last Update: Nov 21, 2025 2:30 PM

📍 Next Actions:
  • Transition to VERIFYING
  • Transition to PLANNED (re-plan)
  • Transition to BLOCKED (if blocker found)

💡 Suggested: /ccpm:sync
   Save progress to Linear
   Confidence: 70%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### State Flow Diagram

```
START
  ↓
💡 IDEA (Plan your task)
  └─→ /ccpm:plan
      ↓
📋 PLANNED (Ready to start)
  ├─→ /ccpm:work
  │   ↓
🚀 IMPLEMENTING (In progress)
  │   ├─→ /ccpm:sync (save progress)
  │   ├─→ /ccpm:commit (commit changes)
  │   ├─→ /ccpm:verify (check completion)
  │   │   ↓
  │   └─→ 🚫 BLOCKED (if blocker found)
  │       └─→ /ccpm:verify
  │           ↓ (issue resolved)
  │           └─→ 🚀 IMPLEMENTING
  │
  └─→ /ccpm:verify (when checklist complete)
      ↓
🔍 VERIFYING (Quality checks)
  ├─→ /ccpm:verify (continue checks)
  │   ↓ (all checks pass)
  │   ↓
✅ VERIFIED (Ready to finalize)
  └─→ /ccpm:done (create PR + complete)
      ↓
🎉 COMPLETE (Done!)
```

## Next Action Suggestions

Based on your current state, the skill suggests the best command to execute:

### IDEA State
```
Current: 💡 IDEA
Question: What should I do next?

Suggested: /ccpm:plan "Task title" <project>
Description: Create implementation plan
Confidence: 90%
Reasoning: Task needs planning before implementation
```

### PLANNED State
```
Current: 📋 PLANNED
Question: What should I do next?

Suggested: /ccpm:work
Description: Start implementation
Confidence: 90%
Reasoning: Plan is ready, begin development
```

### IMPLEMENTING State (Early)
```
Current: 🚀 IMPLEMENTING (25% complete)
Question: What should I do next?

Suggested: /ccpm:sync
Description: Save progress to Linear
Confidence: 70%
Reasoning: Document what you've done so far
```

### IMPLEMENTING State (Complete)
```
Current: 🚀 IMPLEMENTING (100% complete)
Question: What should I do next?

Suggested: /ccpm:verify
Description: Run quality checks
Confidence: 85%
Reasoning: Checklist complete, verify before completion
```

### BLOCKED State
```
Current: 🚫 BLOCKED
Question: What should I do next?

Suggested: /ccpm:verify
Description: Diagnose and fix blocker
Confidence: 80%
Reasoning: Address blocking issue to continue
```

### VERIFYING State
```
Current: 🔍 VERIFYING
Question: What should I do next?

Suggested: /ccpm:verify
Description: Continu