home / skills / ahonn / dotfiles / plan-code-workflow

plan-code-workflow skill

safe

This skill helps you plan and code complex tasks by switching between analysis and concrete implementation with clear verification steps.

npx playbooks add skill ahonn/dotfiles --skill plan-code-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.3 KB

---
name: plan-code-workflow
description: "Plan/Code workflow for moderate to complex tasks. Defines when to use Plan vs Code mode. Applied automatically for non-trivial implementations."
user-invocable: false
---

# Plan/Code Workflow

Two primary work modes: **Plan** and **Code**.

## Task Complexity Assessment

| Complexity | Characteristics | Strategy |
|------------|-----------------|----------|
| **Trivial** | Simple syntax, single API, <10 lines | Answer directly |
| **Moderate** | Non-trivial logic in single file, local refactoring | Use Plan/Code workflow |
| **Complex** | Cross-module design, concurrency, multi-step migrations | Must use Plan/Code workflow |

## Common Rules

- **When entering Plan mode**, briefly restate: mode, objective, key constraints, current state
- In Plan mode, **must read relevant code first** before proposing modifications
- Only restate when mode switches or constraints significantly change
- Don't unilaterally introduce new tasks beyond scope
- When user says "implement", "execute", "proceed", "start coding" → switch to Code mode immediately

## Plan Mode (Analysis / Alignment)

1. Analyze top-down, find root causes, not just patch symptoms
2. List key decision points and trade-offs
3. Provide **1–3 feasible options**, each including:
   - Summary approach
   - Impact scope (modules/interfaces involved)
   - Pros and cons
   - Potential risks
   - Verification methods

4. Only ask clarifying questions when missing info would block progress
5. Avoid providing essentially identical plans

### Exit Conditions

- User explicitly chooses an option, OR
- One option is clearly superior (explain reasoning, proactively choose)

Once conditions met → **enter Code mode directly**

## Code Mode (Execute Plan)

1. Main content must be concrete implementation, not continued planning
2. Before providing code, briefly state:
   - Which files/modules will be modified
   - Purpose of each modification

3. Prefer **minimal, reviewable changes**:
   - Local snippets/patches over complete files
   - Mark key change regions

4. Indicate how to verify:
   - Tests/commands to run
   - Draft new test cases if needed

5. If major problems discovered → pause, switch back to Plan mode

### Output Should Include

- What changes were made, where
- How to verify
- Known limitations or follow-up TODOs

Overview

This skill defines a disciplined Plan/Code workflow for moderate to complex implementation tasks. It prescribes when to pause for planning versus when to start coding, and it applies automatically for non-trivial changes in dotfiles, Neovim, Nix, Git, tmux, and related Lua configuration. The goal is predictable, reviewable edits and fewer regressions during cross-file or design-sensitive work.

How this skill works

On detection of a non-trivial request, the skill enters Plan mode: it summarizes the objective, inspects relevant files, and produces 1–3 actionable options with trade-offs. After a user selects an option (or one is clearly superior), it switches to Code mode and emits focused, minimal patches with file-by-file notes. Code mode enumerates modified files, the purpose of each change, verification steps, and any follow-up TODOs.

When to use it

Refactoring a Neovim Lua plugin or config that touches multiple modules
Adding or changing Nix expressions that affect several derivations
Implementing new cross-cutting features (keymaps, LSP integration) across dotfiles
Any change involving concurrency, migrations, or multi-file API updates
When you need clear trade-offs before committing to code

Best practices

Always read relevant files before proposing a plan
Keep plans short: objective, constraints, 1–3 distinct options with pros/cons
Prefer minimal, reviewable code patches over full-file rewrites
State which files will be changed and why before code output
Provide verification steps and small tests or commands to validate changes
If unexpected issues arise during coding, switch back to Plan mode and reassess

Example use cases

Refactor Neovim LSP setup across init.lua and plugin modules: plan options for lazy-loading vs eager init, then implement chosen patch
Migrate tmux and shell config to a Nix-managed layout: plan dependency graph and produce Nix snippets in Code mode
Add a new keybinding layer that affects multiple Lua modules: outline options and apply minimal edits to each file
Fix a cross-module bug introduced by a recent refactor: analyze root cause, propose fixes with impact scope, then patch

FAQ

When do you ask clarifying questions?

Only when missing information would block safe progress; otherwise provide options that assume reasonable defaults and state those assumptions.

How large should code patches be in Code mode?

Prefer minimal, targeted patches that are easy to review. Avoid full-file rewrites unless necessary and explicitly justify them.