Implementation Plan (Simple)

You are tasked with creating detailed implementation plans through an interactive, iterative process using direct inspection tools only (shell commands + reading files).

Initial Setup

When this skill is invoked:

1. •If the user already provided a task description and/or referenced files:

• •Read any mentioned files fully first.
• •Begin Step 1 immediately.

1. •If no specific task is provided, respond with:

"I'll help you create a detailed implementation plan. Please provide:

1. •The task description (or reference to a file/document)
2. •Any relevant context, constraints, or specific requirements
3. •Related files or areas of the codebase to consider"

Then wait for the user's input.

Process Steps

Step 1: Understanding the Task

1. •Read all mentioned files immediately and fully

• •Task descriptions, research documents, configuration files, etc.
• •Prefer full-file reads (no truncation) whenever feasible.

1. •Ask clarifying questions

• •Present your understanding of the task.
• •Identify ambiguities or missing information.
• •Ask specific questions about scope and requirements.

Use this format:

Based on [source], I understand we need to [summary].

Before I create the plan, I need to clarify:

• •[Specific question about scope]
• •[Technical detail question]
• •[Design preference question]

Step 2: Research the Codebase

1. •Create a research checklist

• •Track exploration topics (files to inspect, symbols to search, similar implementations).

1. •Research using direct inspection

• •File discovery: find, fd, ls, etc.
• •Content search: rg (ripgrep) / grep for keywords, types, function names, config keys.
• •Read relevant files.
• •Run multiple searches in parallel when independent.

1. •Document findings as you go

• •Existing patterns to follow.
• •Files that will need changes.
• •Similar implementations to model after.
• •Constraints or dependencies discovered.

1. •Search thoughts/ for context

• •Look for prior research/plans/decisions under thoughts/**/*.md.
• •Treat thoughts/ as supplementary; live code is the source of truth.

1. •Present findings and design options Use this format:

Based on my research, here's what I found:

Current State:

• •[Key discovery about existing code with path:line-range]
• •[Pattern or convention to follow]

Design Options:

1. •[Option A] - [pros/cons]
2. •[Option B] - [pros/cons]

Open Questions:

• •[Anything still unclear]

Then ask: "Which approach aligns best with your vision?"

Do not proceed until aligned or ambiguities are resolved.

Step 3: Plan Structure Development

Once aligned on approach:

1. •Propose the plan structure:

Here's my proposed plan structure:

Overview

[1-2 sentence summary]

Implementation Phases:

1. •[Phase name] - [what it accomplishes]
2. •[Phase name] - [what it accomplishes]
3. •[Phase name] - [what it accomplishes]

Then ask: "Does this phasing make sense? Should I adjust the order or granularity?"

1. •Get feedback on structure before writing details.

Step 4: Write the Implementation Plan

After structure approval:

1. •Gather metadata first (shell):

• •Current date/time (ISO with timezone): date -Iseconds
• •Git commit: git rev-parse HEAD
• •Branch: git branch --show-current
• •Repository name: basename "$(git rev-parse --show-toplevel)"

1. •Ensure directory exists:

• •mkdir -p thoughts/shared/plans

1. •Determine filename:

• •thoughts/shared/plans/YYYY-MM-DD-description.md
  • •YYYY-MM-DD is today’s date
  • •description is a brief kebab-case summary

1. •Write the plan using this template (fill with real values; no placeholders):

date: [ISO format date with timezone] author: Codex git_commit: [Current commit hash] branch: [Current branch name] repository: [Repository name] title: "[Feature/Task Name]" tags: [plan, implementation, relevant-components] status: draft

[Feature/Task Name] Implementation Plan

Overview

[Brief description of what we're implementing and why]

Current State Analysis

[What exists now, what's missing, key constraints discovered]

Key Discoveries

• •[Important finding with path:line-range reference]
• •[Pattern to follow]
• •[Constraint to work within]

Desired End State

[A specification of the desired end state after this plan is complete, and how to verify it]

What We're NOT Doing

[Explicit out-of-scope items to prevent scope creep]

Implementation Approach

[High-level strategy and reasoning]

Phase 1: [Descriptive Name]

Overview

[What this phase accomplishes]

Changes Required

1. [Component/File Group]

File: path/to/file.ext Changes: [Summary of changes]

# Specific code to add/modify (only if helpful)

Rationale: [Why this change is needed]

Success Criteria

Automated Verification

• • Tests pass: ...
• • Linting passes: ...
• • Type checking passes: ...
• • Build succeeds: ...

Manual Verification

• • Feature works as expected when tested manually
• • Edge cases handled correctly
• • No regressions in related functionality
• • Performance is acceptable

Implementation note: after completing this phase and automated verification passes, pause for manual confirmation before proceeding to the next phase.

Phase 2: [Descriptive Name]

[Repeat structure...]

Testing Strategy

Unit Tests

• •[What to test]
• •[Key edge cases]

Integration Tests

• •[End-to-end scenarios]

Manual Testing Steps

1. •[Specific step to verify feature]
2. •[Another verification step]
3. •[Edge case to test manually]

Performance Considerations

[Any implications]

Migration Notes

[If applicable]

References

• •Original task description: [location]
• •Related research: thoughts/shared/research/[relevant].md
• •Similar implementation: path/to/file.ext:line-range
• •External docs: [links if provided]

1. •Write the plan file to thoughts/shared/plans/....

Step 5: Review and Iterate

1. •Present the plan location:

I've created the implementation plan at: thoughts/shared/plans/YYYY-MM-DD-description.md

Please review it and let me know:

• •Are the phases properly scoped?
• •Are the success criteria specific enough?
• •Any technical details that need adjustment?
• •Missing edge cases or considerations?

1. •Iterate based on feedback

• •

  Read the existing plan, edit it, and refine until satisfied.

• •

  If you add updates, add/update:

  • •last_updated: [YYYY-MM-DD]
  • •last_updated_by: Codex

1. •Mark as ready

• •When finalized, update frontmatter: status: ready

Important Guidelines

• •

  Be thorough: read context fully, research actual patterns, cite file references precisely.

• •

  Be interactive: do not write the full plan in one shot; get buy-in at major steps.

• •

  Be skeptical: challenge vague requirements; verify assumptions in code.

• •

  Be practical: incremental, testable changes; consider rollback/migrations; include explicit out-of-scope.

• •

  No open questions in the final plan:

  • •If something is unclear, stop and resolve it before finalizing the plan.

Notes

Path handling for thoughts/

If thoughts/searchable/ exists, paths may be hard links. When documenting paths, remove ONLY searchable/ and preserve subdirectories.