juanibiapina/dotfiles/plan

Plan

Research the codebase and produce an implementation plan. Make no source-code changes.

Self-containment

A plan must be self-contained. Assume the reader has only the plan, with no access to the conversation that produced it. It must carry enough context and rationale for a fresh agent to make good decisions on its own: key constraints, decisions already made and why, and relevant background found during research. It does not need exhaustive detail or exact code locations; it needs enough that a competent agent can find the rest and choose well. When deciding whether something belongs in the plan, apply this test: could a fresh agent build the right thing from the plan alone?

Workflow

1. Load skills

Load all three before reading any source:

• vocabulary — consistent software-design terms in the plan
• deep-modules — designing the code
• documentation — structuring the plan

Completion criterion: all three loaded before the first source-file read.

2. Research

Before planning, explore the codebase to understand what exists:

• Read project documentation (READMEs, docs) for conventions and guidelines
• Explore relevant files, where changes will be made, potentially related files that may need to change
• Check for related patterns, prior art, and existing implementations
• Review recent git history for context
• Understand the architecture and constraints
• Understand the current state of the code involved in this change
• Find what the platform already offers for the problem: existing dependencies, libraries the platform recommends, and widely adopted packages

Before concluding anything is absent (a file, usage, dependency, or pattern), confirm the checkout is current: git fetch, and fast-forward if behind the upstream default branch.

3. Plan

Keep the plan focused on what the user wants. Choose the smallest set of changes that achieves that goal. Avoid scope creep: include adjacent work only when it is necessary to deliver the requested outcome.

When the change is to agent instructions, name the skill that owns the procedure and leave out its commands. Add a guard step only for a case that exists today.

Prefer a library over custom code when it is maintained, current, and recommended by the platform the project runs on (e.g. Cloudflare's Agents SDK on Workers, expo-* packages in an Expo app). Write custom code only when no such library fits, and state in the plan which library was rejected and why.

When relevant, include data models as code in the project's language and Mermaid diagrams that clarify relationships, flows, or state transitions. Keep each artifact limited to the design needed for the task.

When breaking the work into steps:

• Operationalize the task: turn it into observable/measurable steps.
• Name a step by its outcome — "what's true when done."
• Make steps specific and measurable (from SMART goals).

Choose a detail level based on complexity:

Minimal, for simple, well-understood changes:

• Goal
• What to change and why, including libraries used
• Out of scope
• Tests to add or update
• Docs to add or update
• Skills to use
• Acceptance criteria

Comprehensive, for architectural changes, complex features or entire new projects:

• Goal
• What to change and why
• Out of scope
• Technical approach with alternatives considered
• System-wide impact (what else is affected, error propagation, state risks)
• Implementation phases
• Test strategy: what kinds of tests, coverage of new paths, edge cases
• Documentation strategy
• Skills to use
• Acceptance criteria
• Risks, dependencies, and mitigations

Default to minimal.

Under "Out of scope", name the adjacent work the plan deliberately excludes and, where useful, why.

A plan has no "Open questions" section and leaves no question for the reader to answer. Turn each unknown into one of:

• a proposed decision, stated as decided, with its reason, so the requester

can accept or change it in review;

• a solution that removes the unknown, such as a design that works either

way, or a check the builder runs first with the action for each result;

• an out-of-scope item under "Out of scope", with why.

For "Skills to use", recommend the skills available in your context that match the work in the plan. List them by name, each with a one-line note on when it applies during implementation (e.g. "tdd — for the parser changes", "commit — when committing").

4. Output

Present the complete plan using the Minto Pyramid.