ccpm-code-review

What this skill does

# CCPM Code Review

Structured code review workflow integrated with CCPM's Linear-based project management system. Enforces "no completion claims without verification evidence" principle.

## When to Use

This skill auto-activates when:

- User says **"done"**, **"complete"**, **"finished"**, **"ready to merge"**
- Running **`/ccpm:verify`** command (natural workflow - recommended)
- Running **`/ccpm:done`** command (includes pre-flight verification)
- Running **`/ccpm:verify`** command (advanced)
- Before updating Linear task status to "Done"
- Before syncing Jira status
- Before creating GitHub/BitBucket PR
- Before sending Slack completion notifications

## CCPM Verification Workflow

CCPM provides a streamlined 3-step verification process:

### Step 1: Quality Checks (Automated)
Run linting, tests, and build checks to ensure technical correctness:

```bash
/ccpm:verify [issue-id]  # Auto-detects issue from git branch
```

**What it checks:**
- ✅ Linting passes (no style errors)
- ✅ Tests pass (all unit and integration tests)
- ✅ Build succeeds (no compilation errors)
- ✅ Checklist complete (100% of implementation items)

**If checks fail:** Command automatically suggests `/ccpm:verify` to debug systematically.

### Step 2: Agent Code Review
After quality checks pass, agent review analyzes:

- ✅ Code quality and best practices
- ✅ Security vulnerabilities
- ✅ Performance implications
- ✅ Requirement fulfillment
- ✅ Regression risks

### Step 3: Final Confirmation
Four verification gates must pass:

1. **Tests Pass** ✅ - Zero failures
2. **Build Succeeds** ✅ - Exit status 0
3. **Checklist Complete** ✅ - 100% checked
4. **No Blockers** ✅ - No unresolved blockers in Linear

**Only after all gates pass** can task proceed to finalization with `/ccpm:done`.

## Core Principles

### 1. Technical Correctness Over Social Comfort

**Forbidden performative agreement:**
- ❌ "Great point!"
- ❌ "You're absolutely right!"
- ❌ "That makes total sense!"

**Required rigorous verification:**
- ✅ "Let me verify that assumption"
- ✅ "I'll test this approach first"
- ✅ "Here's the evidence: [test output]"

### 2. No Implementation Before Verification

When receiving feedback:
1. **First**: Verify the feedback is technically correct
2. **Then**: Implement the change
3. **Never**: Blindly implement without understanding

### 3. NO COMPLETION CLAIMS WITHOUT EVIDENCE

**Required evidence before any "done" claim:**
- ✅ Tests: All passing (screenshot or CI link)
- ✅ Build: Exit status 0 (no errors)
- ✅ Linear checklist: 100% complete
- ✅ No unresolved blockers in Linear comments

## Integration with CCPM Commands

### With `/ccpm:verify` (Natural Workflow - Recommended)

**This skill enforces verification during the streamlined verify command:**

```bash
# User runs natural verification command
/ccpm:verify

# Or with explicit issue ID
/ccpm:verify AUTH-123
```

**Flow:**
```
User: "I'm done, let me verify"

Claude: [ccpm-code-review activates]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Smart Verify Command
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Issue: AUTH-123 - Add user authentication
📊 Status: In Progress
📋 Checklist: 100% (5/5 items)

Verification Flow:
──────────────────
1. Quality Checks (linting, tests, build)
2. Final Verification (code review, security)

═══════════════════════════════════════
Step 1/2: Running Quality Checks
═══════════════════════════════════════

🔍 Running linting...
✅ All files pass linting

🧪 Running tests...
✅ All tests passed (28/28)

🏗️  Running build...
✅ Build successful

📊 Quality Check Results:
  ✅ Linting
  ✅ Tests
  ✅ Build

═══════════════════════════════════════
Step 2/2: Running Final Verification
═══════════════════════════════════════

[Code reviewer agent analyzes changes...]

✅ All requirements met
✅ Code quality standards met
✅ Security best practices followed
✅ Performance acceptable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ All Verification Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All verifications passed! Ready to finalize.

💡 What's Next?
⭐ Recommended: /ccpm:done AUTH-123
```

**If verification fails:**
```
❌ Quality Checks Failed

📊 Quality Check Results:
  ✅ Linting
  ❌ Tests (3 failures)
  ✅ Build

To debug and fix issues:
  /ccpm:verify AUTH-123

Then run verification again:
  /ccpm:verify AUTH-123
```

### With `/ccpm:done` (Pre-Flight Verification)

**This skill ensures quality before finalization:**

```bash
# User attempts to finalize task
/ccpm:done

# Or with explicit issue ID
/ccpm:done AUTH-123
```

**Pre-flight checks enforced by ccpm-code-review:**

```
User: "/ccpm:done AUTH-123"

Claude: [ccpm-code-review activates for pre-flight]

✅ All pre-flight checks passed!

Checking completion readiness:

□ Tests passing?
  → ✅ All 52 tests passed

□ Build successful?
  → ✅ Build completed (exit 0)

□ Linear checklist complete?
  → ✅ 7/7 items checked

□ No blockers?
  → ✅ No blockers found

VERIFICATION COMPLETE ✅

📝 Creating GitHub Pull Request...
✅ Pull Request created

[Prompts for Jira/Slack updates with confirmation]

✅ Linear issue updated to Done

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Task Finalized: AUTH-123
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**If pre-flight fails:**
```
⛔ Cannot Finalize: Checklist Incomplete

Progress: 80% (4/5 completed)

❌ Remaining Items:
  - [ ] Write integration tests

🔧 Actions Required:
1. Complete remaining checklist items
2. Update checklist: /ccpm:sync AUTH-123
3. Then run: /ccpm:done AUTH-123
```

### Advanced: With `/ccpm:verify`

**For manual verification step (advanced users):**

```
Claude runs /ccpm:verify AUTH-123

[ccpm-code-review activates during verification]

Checking verification evidence:

□ Tests passing?
  → ✅ All 47 tests passed

□ Build successful?
  → ✅ Build completed with exit code 0

□ Linear checklist complete?
  → ❌ 3 of 5 items checked

□ No blockers?
  → ⚠️ 1 blocker found: "Redis connection failing in staging"

VERIFICATION FAILED:
- Linear checklist incomplete (3/5)
- Blocker unresolved: Redis connection issue

Cannot proceed with completion until:
1. Complete remaining checklist items
2. Resolve Redis blocker or document as out-of-scope

Would you like to:
A. Update checklist now
B. Investigate Redis blocker
C. Update task scope to exclude Redis
```

## Receiving Feedback Protocol

### When PR Reviewer Comments

**Scenario**: Reviewer says "Add error handling to login function"

**❌ Wrong approach** (performative):
```
"Great point! I'll add error handling right away."
[Immediately adds try-catch without understanding]
```

**✅ Correct approach** (verification-first):
```
Claude: [ccpm-code-review activates]

Let me verify this feedback:

1. Checking current error handling...
   ```typescript
   // login.ts
   async function login(email, password) {
     const user = await db.findUser(email);  // ← No error handling
     return generateToken(user);             // ← No error handling
   }
   ```

2. Potential issues:
   - Database query could fail (network, timeout)
   - user might be null (not found)
   - generateToken could throw (invalid data)

3. Verification: Feedback is VALID
   - Missing error handling confirmed
   - Could cause uncaught exceptions

4. Implementation approach:
   ```typescript
   async function login(email, password) {
     try {
       const user = await db.findUser(email);
       if (!user) {
         throw new UnauthorizedError('Invalid credentials');
       }
       return generateToken(user);
     } catch (error) {
       if (error instanceof DatabaseError) {
         logger.error('Database error during login', error);
         throw new ServiceUnavailableError();
       }
       throw error;
     }
   }
   ```

5. Testing the fix:
   - Add test: login with network error → returns 503
   - Add test: login with invalid user → returns 401
   - Verify existing tests still pass

6. Update Linear:
   - Add comment: "PR feedback: Added error handling"
   - Link to new commi