Create Implementation Plan

Instructions

Create a detailed, high-quality implementation plan as a ticket (tagged plan ) that adheres to strict quality standards and provides complete guidance for implementation.

Phase 1: Understanding & Validation

Step 0: Extract Original Issue/Task Requirements (MANDATORY)

CRITICAL: Before creating any plan, extract ALL requirements from the original issue/task.

GitHub:

gh issue view <number>

Forgejo:

tea issue view <number> # or Forgejo API

Local tk:

tk show <id>

Create exhaustive requirements list:

• Every functional requirement stated

• Every acceptance criterion listed

• Every edge case mentioned

• Every error handling requirement

• Any implicit requirements (derive from context)

Store this list - the plan MUST cover 100% of these requirements.

Step 1: Understand the Request

• Review the report or analysis that triggered this plan

• Map each requirement from Step 0 to plan items

• Identify the type of plan needed:

• Feature: New functionality

• Refactor: Code restructuring

• Fix: Bug fix or issue resolution

• Enhancement: Improvement to existing feature

Step 2: Audit the Codebase

CRITICAL: Never create a plan without thorough codebase understanding

For each item in the report, perform comprehensive analysis:

• Use the audit skill if needed for deep investigation

• Identify affected files - Which files will change?

• Find existing patterns - How is similar code structured?

• Check AGENTS.md files - What are the rules for this area?

• Analyze types - What existing types can be reused?

• Identify dependencies - What depends on what we're changing?

• Find naming patterns - How should new files be named?

DO NOT SKIP THIS STEP - Rushed plans lead to bad implementations

Step 3: AGENTS.md Compliance Check

Read ALL relevant AGENTS.md files in:

• Project root

• Affected directories

• Related modules

Extract requirements:

• Naming conventions

• Architecture patterns

• Type requirements

• File organization rules

• Code style standards

Phase 2: Plan Structure & Naming

Step 1: Choose Plan Title

Format: Plan: [descriptive title]

Rules:

• Be specific and descriptive

• Reflect actual work (not vague like "improvements")

• Examples:

• Plan: Implement user authentication ✅

• Plan: Refactor database layer ✅

• Plan: New features ❌ (too vague)

Step 2: Determine File Names for Implementation

CRITICAL RULES:

• ❌ NEVER create migration files like foo_v2.ts , foo-new.ts , foo-enhanced.ts

• ❌ NEVER use temporary naming like simple-.ts , temp-.ts

• ✅ ALWAYS use proper, final names from the start

• ✅ ALWAYS follow existing naming patterns in the directory

• ✅ ALWAYS check AGENTS.md for naming requirements

Process:

• Identify existing file naming patterns

• Check AGENTS.md for conventions

• Choose names that fit the pattern

• If unsure, analyze similar existing files

• Plan to replace existing files directly (not create duplicates)

Phase 3: Plan Content - Required Sections

Create plan document with ALL of the following sections:

1. Overview & Issue Coverage

[Plan Title]

Summary

[2-3 sentences explaining what and why]

Type

[Feature | Refactor | Fix | Enhancement]

Source Issue/Task

[Link to source issue/task — GitHub issue URL, Forgejo issue URL, or tk ticket ID]

Original Requirements (100% Coverage Required)

ALL requirements from source issue/task that this plan MUST address:

Coverage Check: X of X requirements mapped to plan steps (must be 100%)

Status

Open (ticket will be closed when plan is complete)

2. Context & Motivation

Context

[Why is this needed? What problem does it solve?]

Current State

[What exists now? What are the limitations?]

Desired State

[What will exist after? What improvements will we gain?]

3. AGENTS.md Compliance

AGENTS.md Requirements

Naming Conventions

• [List relevant naming rules from AGENTS.md]

Architecture Requirements

• [List relevant architectural rules]

Type Requirements

• [List type-related rules]

Other Guidelines

• [Any other relevant rules]

4. Existing Types Analysis

Existing Types

Types to Reuse

• TypeName from path/to/file.ts - [what it represents]
• [List ALL types that can be reused]

Types to Create

• NewTypeName - [what it will represent, why needed]
• [Only create if NO existing type works]

Type Guidelines

• ❌ NEVER use any
• ❌ NEVER use unknown (unless absolutely necessary with justification)
• ✅ ALWAYS prefer existing types
• ✅ ALWAYS use strict typing

5. Impact Analysis

Impact Analysis

Files to Modify

• path/to/file1.ts - [what changes, why]
• path/to/file2.ts - [what changes, why]

Files to Create

• path/to/newfile.ts - [purpose, why not existing file]

Files to Delete

• path/to/oldfile.ts - [why removing, what replaces it]

Dependencies Affected

• [List what depends on changed code]
• [How will dependencies be updated?]

Breaking Changes

• [List any breaking changes]
• [How will they be handled?]

6. Implementation Steps

Implementation Steps

Each step should be:

• Specific and actionable
• Single responsibility
• Ordered correctly (dependencies first)

Step 1: [Descriptive Title]

File: path/to/file.ts Action: [What to do] Why: [Why this step] Details:

• [Specific implementation detail]
• [Another detail]

Step 2: [Next Step]

[Same structure]

[Continue for all steps]

7. REMOVAL SPECIFICATION ⚠️

REMOVAL SPECIFICATION

CRITICAL: This section tracks OLD code that must be REMOVED.

Code to Remove

From path/to/file1.ts

• Lines X-Y: function oldFunction() {...}
  • Why removing: Replaced by newFunction
  • Replacement: Step 3 in implementation
  • Dependencies: Used by A, B, C (all updated in steps 5, 6, 7)

File to Delete: path/to/old-file.ts

• Why removing: Functionality moved to new-file.ts
• Replacement: Step 2 creates replacement
• Dependencies: Imported by X, Y, Z (all updated in steps 8, 9, 10)

Removal Checklist

• All deprecated functions removed
• All old files deleted
• All imports updated
• All references updated
• No dead code remains

VERIFICATION: At completion, grep for old symbols to ensure complete removal.

8. Anti-Patterns to Avoid

Anti-Patterns to Avoid

❌ NEVER include:

• Migration mechanisms (gradual rollout, feature flags for this)
• Fallback mechanisms (keeping old code "just in case")
• Risk mitigation (running old and new in parallel)
• Backward compatibility layers (unless external API)
• Temporary bridges between old and new

✅ ALWAYS instead:

• Replace completely and cleanly
• Make all necessary changes at once
• Remove old code immediately
• Trust the plan and execute fully

Why: Half-migrations leave bad code in the codebase forever.

9. Validation Criteria

Validation Criteria

Pre-Implementation Checklist

• All AGENTS.md files reviewed
• All existing types identified
• All affected files identified
• All naming follows patterns
• Impact fully analyzed

Post-Implementation Checklist

• All steps completed
• All old code removed (per REMOVAL SPEC)
• TypeScript compiles (tsc --noEmit)
• Linting passes (npm run lint)
• Tests pass (if applicable)
• No any or unknown types added
• AGENTS.md compliance verified
• Single responsibility maintained

Phase 4: Plan Creation & Validation

Step 1: Write the Plan

• Create as a ticket using todos_oneshot with tags plan

• Include ALL required sections above in the ticket description

• Be thorough - never skip items

Step 2: Validate Plan Completeness

Checklist:

• 100% of original issue/task requirements mapped to plan steps

• Overview section complete with requirements table

• Context & motivation clear

• AGENTS.md compliance documented

• Existing types analyzed

• Impact analysis thorough

• Implementation steps detailed and ordered

• Every requirement from issue appears in at least one step

• REMOVAL SPECIFICATION complete

• Anti-patterns section included

• Validation criteria defined

• No migration/fallback mechanisms

• No temporary file names

• No any or unknown types planned

Step 3: Review Against Guidelines

Double-check:

• ✅ Follows naming conventions from AGENTS.md

• ✅ Uses existing types where possible

• ✅ Single responsibility maintained

• ✅ Complete removal spec included

• ✅ No migration code planned

• ✅ All steps are specific and actionable

• ✅ No items skipped or rushed

Step 4: Final Audit Recommendation

Before finalizing, consider:

• Should specific areas be audited more deeply?

• Are there unknowns that need investigation?

• Is more context needed before implementation?

If yes, recommend using the audit skill for those areas.

Phase 5: Report to User

Provide summary:

Plan Created: [plan-name]

Location

Saved as ticket tagged plan

Summary

[Brief description of what the plan covers]

Key Points

• [Important aspect 1]
• [Important aspect 2]
• [Important aspect 3]

Files Affected

• X files to modify
• Y files to create
• Z files to delete

REMOVAL SPEC

• [Summary of what will be removed]

Ready to Implement

The plan is complete and ready for implementation. All required sections are included, AGENTS.md compliance is verified, and the removal specification is thorough. Use tk show <ticket-id> to review.

Next Steps

Review the plan ticket and begin implementation when ready.

Critical Principles

• 100% ISSUE COVERAGE - Plan MUST address every requirement from original issue

• NEVER RUSH - Thorough planning prevents bad implementations

• NEVER SKIP AUDIT - Always understand the codebase first

• NEVER CREATE MIGRATIONS - Replace completely, not gradually

• NEVER USE TEMPORARY NAMES - Use final, proper names from the start

• NEVER SKIP REMOVAL SPEC - Track what must be deleted

• NEVER SKIP REQUIREMENT - Every issue requirement MUST have a plan step

• ALWAYS USE EXISTING TYPES - Create new types only when necessary

• ALWAYS FOLLOW AGENTS.MD - Read and apply all guidelines

• ALWAYS BE SPECIFIC - Vague steps lead to bad implementations

• ALWAYS THINK HOLISTICALLY - Consider full impact of changes

• COMPLETENESS OVER SPEED - A complete plan prevents future problems

Templates

See templates/ directory for:

• feature-plan-template.md

• Template for new features

• refactor-plan-template.md

• Template for refactoring

• fix-plan-template.md

• Template for bug fixes