check-plan

name	check-plan
description	Audit implementation progress against a plan, verify completed work, identify remaining tasks, and validate quality. Use when user asks to check plan status, verify implementation, see what's left to do, or validate plan completion.

Check Plan Implementation

Instructions

Perform comprehensive audit of implementation progress against a plan, verify quality of completed work, and generate actionable task list for remaining items.

Phase 1: Setup & Discovery

Step 1: Identify the Plan

• Ask user which plan to check (or identify from context)
• Read the plan file from .plans/
• Understand all plan items and requirements

Step 2: Get Git Context (if applicable)

# See what files changed
git status

# See detailed changes
git diff

# See commit history on this branch
git log --oneline -20

This helps understand scope of changes made.

Step 3: Identify All Affected Files

Create comprehensive list:

1. Files mentioned in the plan
2. Files shown in git status
3. Files that might be affected (use Glob/Grep)

Create todo list with one item per file to check.

Phase 2: Systematic File-by-File Audit

For EACH file in the todo list:

Step 1: Read the File

• Use Read tool to examine current state
• Check memory/context for any previous notes about this file

Step 2: Map to Plan Items

Identify which plan step(s) relate to this file:

• Which implementation steps mention this file?
• What changes were supposed to be made?
• What requirements from the plan apply here?

Step 3: Verify Implementation

Check if planned changes are present:

• ✅ DONE: Implementation matches plan requirements
• ⚠️ PARTIAL: Some work done, but incomplete
• ❌ NOT DONE: No implementation yet
• 🔍 NEEDS REVIEW: Implementation exists but may not match plan

For each file, assess:

• Are planned features implemented?
• Is code quality good?
• Are types used correctly (no any)?
• Does it follow CLAUDE.md guidelines?
• Is it complete or partial?

Step 4: Quality Verification

Check implementation quality:

• Correctness: Does it work as planned?
• Types: Proper typing, no any, using existing types?
• Naming: Follows conventions from plan?
• Architecture: Matches planned design?
• Completeness: All details from plan step implemented?

Step 5: Record Assessment

Store in memory:

File: path/to/file.ts
Plan Item: Step X - [description]
Status: [DONE|PARTIAL|NOT DONE|NEEDS REVIEW]
Notes: [What's good, what's missing, what needs fixing]
Quality Issues: [Any problems found]

Step 6: Update Todo

Mark file as checked in the todo list.

Phase 3: REMOVAL SPEC Verification

CRITICAL: Verify old code was actually removed.

Step 1: Read REMOVAL SPEC from Plan

Extract all items listed for removal:

• Code to be removed (with file/line numbers)
• Files to be deleted
• Deprecated functions to eliminate

Step 2: Verify Each Removal

For each item in REMOVAL SPEC:

1. For code to remove:

   # Check if old code still exists
   grep -n "old_function_name" path/to/file.ts
   

   • ✅ If not found: Code successfully removed
   • ❌ If found: Code still exists (NOT DONE)

2. For files to delete:

   # Check if file still exists
   ls path/to/old-file.ts
   

   • ✅ If not found: File successfully deleted
   • ❌ If found: File still exists (NOT DONE)

3. For deprecated imports/references:

   # Search entire codebase
   grep -r "old_symbol" src/
   

   • ✅ If not found: All references removed
   • ❌ If found: References still exist (NOT DONE)

Step 3: Record Removal Status

• List what was supposed to be removed
• List what actually was removed
• Flag any items not removed as HIGH PRIORITY tasks

Phase 3.5: Original Issue/Task Coverage Verification (MANDATORY)

CRITICAL: Verify that the implementation covers 100% of the ORIGINAL issue/task requirements, not just the plan steps.

Step 1: Locate Original Issue/Task

Find the source requirement:

• GitHub issue that triggered this plan: gh issue view <number>
• Original task description or ticket
• User request that initiated the work

Step 2: Extract ALL Original Requirements

From the original issue/task, extract:

• Every functional requirement
• Every acceptance criterion
• Every edge case mentioned
• Every error handling requirement
• Any implicit requirements

Step 3: Map Requirements to Implementation

#	Original Requirement	Plan Step	Implementation Status
1	[from issue]	Step X	✅/❌/⚠️
2	[from issue]	Step Y	✅/❌/⚠️
3	[from issue]	N/A (missing from plan!)	❌

Step 4: Identify Coverage Gaps

Two types of gaps:

1. Plan gaps: Requirements from issue that weren't captured in plan
2. Implementation gaps: Plan steps that weren't fully implemented

Both count toward incomplete coverage.

Step 5: Coverage Assessment

Issue Coverage = (Implemented Original Requirements / Total Original Requirements) × 100%

Anything less than 100% = PLAN NOT COMPLETE

Phase 4: Gap Analysis

Step 1: Identify Scope Creep

Files changed that are NOT in the plan:

• Why were they changed?
• Were changes necessary?
• Should plan be updated to reflect them?

Step 2: Identify Missing Work

Plan items without corresponding implementation:

• Which steps haven't been started?
• Which steps are partially complete?
• What's blocking completion?

Step 3: Identify Issue Coverage Gaps (HIGH PRIORITY)

Requirements from original issue not in implementation:

• Which issue requirements are missing?
• Were they missed in planning or implementation?
• These are HIGHER PRIORITY than plan step completion

Phase 5: Build Progress Report

Step 1: Calculate Completion Percentage

Total Plan Steps: X
Completed Steps: Y
Partial Steps: Z
Not Started: W

Completion: (Y / X) * 100%
Weighted Completion: ((Y + 0.5*Z) / X) * 100%

Step 2: Generate Structured Report

Create report at .plans/[plan-name].progress.md:

# Plan Progress Report: [Plan Name]
**Date**: [timestamp]
**Plan File**: [path]
**Status**: [In Progress | Ready for Review | Completed]

---

## Summary
- **Overall Completion**: X%
- **Steps Complete**: Y / Total
- **Steps Partial**: Z
- **Steps Not Started**: W
- **Critical Issues**: N

---

## Progress by Plan Step

### ✅ Step 1: [Description]
**Status**: DONE
**Files**: [list]
**Notes**: [Any relevant notes]

### ⚠️ Step 2: [Description]
**Status**: PARTIAL (60% complete)
**Files**: [list]
**Completed**:
- [What's done]
**Remaining**:
- [What's not done]
**Issues**: [Any problems]

### ❌ Step 3: [Description]
**Status**: NOT DONE
**Blocking**: [What's blocking this]

---

## REMOVAL SPEC Status

### ✅ Completed Removals
- `old_function` from `file.ts` - Successfully removed
- `old-file.ts` - Successfully deleted

### ❌ Pending Removals (HIGH PRIORITY)
- `legacy_code` from `file.ts:lines 50-100` - **STILL EXISTS**
- `deprecated-helper.ts` - **FILE STILL EXISTS**

**Critical**: Old code must be removed before plan can be marked complete.

---

## Quality Assessment

### Passed
- ✅ TypeScript types used correctly
- ✅ CLAUDE.md naming conventions followed
- ✅ Architecture matches plan

### Issues Found
- ⚠️ `any` type used in `file.ts:42` (should use existing type)
- ⚠️ Missing error handling in step 5 implementation

---

## Files Changed

### Planned Changes (from plan)
- ✅ `path/to/file1.ts` - DONE
- ⚠️ `path/to/file2.ts` - PARTIAL
- ❌ `path/to/file3.ts` - NOT DONE

### Unplanned Changes (scope creep)
- `path/to/unexpected.ts` - Why: [reason]

---

## Remaining Work

### High Priority
1. **Remove old code** (REMOVAL SPEC items)
   - [ ] Remove `legacy_code` from `file.ts`
   - [ ] Delete `deprecated-helper.ts`

2. **Complete Step 3**
   - [ ] Implement [specific requirement]
   - [ ] Add proper types

### Medium Priority
3. **Fix quality issues**
   - [ ] Replace `any` in `file.ts:42`
   - [ ] Add error handling in step 5

### Low Priority
4. **Polish**
   - [ ] [Minor improvements]

---

## Validation Status

### Pre-Validation
- [ ] All plan steps completed
- [ ] All REMOVAL SPEC items removed
- [ ] TypeScript compiles
- [ ] Linting passes
- [ ] No `any` types added

**Ready for Final Validation**: NO (pending items remain)

---

## Next Steps

1. Complete REMOVAL SPEC items (remove old code)
2. Finish Step 3 implementation
3. Fix quality issues
4. Run validation checks
5. Update plan status when 100% complete

Phase 6: Validation Checks

Step 1: Run TypeScript Check

# Run type checking
npm run typecheck
# or
tsc --noEmit

Record results:

• ✅ Passes: Good to go
• ❌ Errors: List errors, add to remaining work

Step 2: Run Linting

# Run linter
npm run lint
# or
eslint .

Record results:

• ✅ Passes: Good to go
• ⚠️ Warnings: List warnings
• ❌ Errors: List errors, add to remaining work

Step 3: Run Build (if applicable)

npm run build

Ensure build succeeds.

Phase 7: Generate Task List

Create actionable todo list for remaining work:

# Remaining Tasks for [Plan Name]

## Critical (Must Do)
- [ ] Remove `legacy_code` from `file.ts:50-100` (REMOVAL SPEC)
- [ ] Delete `deprecated-helper.ts` (REMOVAL SPEC)
- [ ] Complete Step 3: [description]

## Important (Should Do)
- [ ] Fix TypeScript error in `file.ts:42`
- [ ] Add error handling in step 5

## Polish (Nice to Have)
- [ ] [Minor improvement]

## Validation
- [ ] TypeScript passes (`npm run typecheck`)
- [ ] Linting passes (`npm run lint`)
- [ ] Build succeeds (`npm run build`)
- [ ] All REMOVAL SPEC items removed

**When all tasks complete**: Update plan file from `.todo.md` to `.done.md`

Phase 8: Report to User

Provide concise summary:

# Plan Check Complete: [Plan Name]

## Overall Status
**X% Complete** (Y of Z steps done)

## Completed ✅
- Step 1: [description]
- Step 2: [description]

## In Progress ⚠️
- Step 3: [description] (60% done)

## Not Started ❌
- Step 4: [description]

## Critical Issues 🚨
- **REMOVAL SPEC not complete**: Old code still exists
  - `legacy_code` in `file.ts` must be removed
  - `deprecated-helper.ts` must be deleted

## Quality Issues
- `any` type used in `file.ts:42`
- Missing error handling in step 5

## Validation
- ❌ TypeScript: 3 errors
- ✅ Linting: Passed
- Build: Not tested

## Next Steps
1. Remove old code (REMOVAL SPEC)
2. Complete Step 3
3. Fix quality issues
4. Run final validation

**Detailed Report**: `.plans/[plan-name].progress.md`
**Task List**: See remaining work section above

Critical Principles

• NEVER SKIP FILES - Check every file in the comprehensive list
• DO NOT EDIT FILES - This is read-only audit, not implementation
• VERIFY REMOVAL SPEC - Critical that old code is actually removed
• BE THOROUGH - Think critically about each file's implementation
• USE MEMORY - Store context as you review files
• RUN VALIDATION - Always run typecheck and lint
• BE HONEST - Mark things as incomplete if they are
• PROVIDE ACTIONS - Don't just identify issues, provide todo list
• CHECK QUALITY - Implementation exists doesn't mean it's good
• 100% STANDARD - Plan isn't done until 100% complete and validated

Completion Criteria

A plan can be marked as .done.md ONLY when:

1. ✅ 100% of ORIGINAL ISSUE/TASK requirements implemented (not just plan steps!)
2. ✅ All plan steps implemented (100% completion)
3. ✅ All REMOVAL SPEC items removed (old code gone)
4. ✅ TypeScript passes (tsc --noEmit succeeds)
5. ✅ Linting passes (no errors)
6. ✅ Build succeeds (if applicable)
7. ✅ No any types added (strict typing maintained)
8. ✅ CLAUDE.md compliance (all guidelines followed)
9. ✅ Quality verified (implementations match plan specs)

CRITICAL: Criterion #1 is the MOST IMPORTANT. A plan that completes all its steps but doesn't fulfill the original issue requirements is STILL INCOMPLETE.

Anything less = plan stays as .todo.md

Supporting Tools

• Grep: Search for old code to verify removal
• Glob: Find all relevant files
• Bash: Run git, typecheck, lint, build
• Read: Examine file contents
• TodoWrite: Track file review progress
• Memory/Pinboard: Store context across files