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 ticket using tk show <ticket-id> (search with tk list --tag plan )

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

• Files mentioned in the plan

• Files shown in git status

• 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 AGENTS.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:

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)

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)

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:

• Plan gaps: Requirements from issue that weren't captured in plan

• 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

Add a progress note to the plan ticket using tk add-note <ticket-id> "<progress>" , or create a separate progress report:

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
• ✅ AGENTS.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: Close the plan ticket with tk close <ticket-id>

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: Added as note to plan ticket 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:

• ✅ 100% of ORIGINAL ISSUE/TASK requirements implemented (not just plan steps!)

• ✅ All plan steps implemented (100% completion)

• ✅ All REMOVAL SPEC items removed (old code gone)

• ✅ TypeScript passes (tsc --noEmit succeeds)

• ✅ Linting passes (no errors)

• ✅ Build succeeds (if applicable)

• ✅ No any types added (strict typing maintained)

• ✅ AGENTS.md compliance (all guidelines followed)

• ✅ 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 ticket stays open

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

After completing the plan check, follow handbook 15.04 to create tk tickets for all surfaced issues.