hezaohezao/poirot/plan

Plan Mode

Use this skill when the user wants a plan instead of execution.

Core behavior

For this turn, you are planning only.

• Do not implement code.
• Do not edit project files except the plan markdown file.
• Do not run mutating terminal commands, commit, push, or perform external actions.
• You may inspect the repo or other context with read-only commands/tools when needed.
• Your deliverable is a markdown plan saved under .poirot/plans/.

Output requirements

Write a markdown plan that is concrete and actionable.

Include, when relevant:

• Goal
• Current context / assumptions
• Proposed approach
• Step-by-step plan
• Files likely to change
• Tests / validation
• Risks, tradeoffs, and open questions

If the task is code-related, include exact file paths, likely test targets, and verification steps.

Save location

Save the plan with write_file under:

• .poirot/plans/YYYY-MM-DD_HHMMSS-<slug>.md

Treat that as relative to the active working directory / sandbox workspace. Poirot sandbox file tools are path-aware, so using this relative path keeps the plan with the workspace.

If no specific target path is provided by the runtime, create a sensible timestamped filename yourself under .poirot/plans/.

Interaction style

• If the request is clear enough, write the plan directly.
• If no explicit instruction accompanies the plan request, infer the task from the current conversation context.
• If it is genuinely underspecified, ask a brief clarifying question instead of guessing.
• After saving the plan, reply briefly with what you planned and the saved path.

Writing the Plan Well

The rest of this skill is the craft of authoring a good implementation plan — the content that goes inside the markdown file above.

Overview

Write comprehensive implementation plans assuming the implementer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, testing commands, docs to check, how to verify. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume the implementer is a skilled developer but knows almost nothing about the toolset or problem domain.

Core principle: A good plan makes implementation obvious. If someone has to guess, the plan is incomplete.

When a Full Implementation Plan Helps

Always use before:

• Implementing multi-step features
• Breaking down complex requirements
• Delegating work to a subagent (when available)

Don't skip when:

• Feature seems simple (assumptions cause bugs)
• You plan to implement it yourself (future you needs guidance)
• Working alone (documentation matters)

Bite-Sized Task Granularity

Each task = 2-5 minutes of focused work.

Every step is one action:

• "Write the failing test" — step
• "Run it to make sure it fails" — step
• "Implement the minimal code to make the test pass" — step
• "Run the tests and make sure they pass" — step
• "Commit" — step

Too big:

### Task 1: Build authentication system
[50 lines of code across 5 files]

Right size:

### Task 1: Create User model with email field
[10 lines, 1 file]
 
### Task 2: Add password hash field to User
[8 lines, 1 file]
 
### Task 3: Create password hashing utility
[15 lines, 1 file]

Plan Document Structure

Header (Required)

Every plan MUST start with:

# [Feature Name] Implementation Plan
 
**Goal:** [One sentence describing what this builds]
 
**Architecture:** [2-3 sentences about approach]
 
**Tech Stack:** [Key technologies/libraries]
 
---

Task Structure

Each task follows this format:

### Task N: [Descriptive Name]
 
**Objective:** What this task accomplishes (one sentence)
 
**Files:**
- Create: `exact/path/to/new_file.py`
- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
- Test: `tests/path/to/test_file.py`
 
**Step 1: Write failing test**
 

def test_specific_behavior(): result = function(input) assert result == expected

 
**Step 2: Run test to verify failure**
 
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: FAIL — "function not defined"
 
**Step 3: Write minimal implementation**
 

def function(input): return expected

 
**Step 4: Run test to verify pass**
 
Run: `pytest tests/path/test.py::test_specific_behavior -v`
Expected: PASS
 
**Step 5: Commit**
 

git add tests/path/test.py src/path/file.py git commit -m "feat: add specific feature"

Writing Process

Step 1: Understand Requirements

Read and understand:

• Feature requirements
• Design documents or user description
• Acceptance criteria
• Constraints

Step 2: Explore the Codebase

Use Poirot tools to understand the project:

# Understand project structure
list_dir("src/")
# Look at similar features
bash("grep -rl 'similar_pattern' src/ --include='*.py'")
# Check existing tests
list_dir("tests/")
# Read key files
read_file("src/app.py")

Step 3: Design Approach

Decide:

• Architecture pattern
• File organization
• Dependencies needed
• Testing strategy

Step 4: Write Tasks

Create tasks in order:

1. Setup/infrastructure
2. Core functionality (TDD for each)
3. Edge cases
4. Integration
5. Cleanup/documentation

Step 5: Add Complete Details

For each task, include:

• Exact file paths (not "the config file" but src/config/settings.py)
• Complete code examples (not "add validation" but the actual code)
• Exact commands with expected output
• Verification steps that prove the task works

Step 6: Review the Plan

Check:

• [ ] Tasks are sequential and logical
• [ ] Each task is bite-sized (2-5 min)
• [ ] File paths are exact
• [ ] Code examples are complete (copy-pasteable)
• [ ] Commands are exact with expected output
• [ ] No missing context
• [ ] DRY, YAGNI, TDD principles applied

Principles

DRY (Don't Repeat Yourself)

Bad: Copy-paste validation in 3 places Good: Extract validation function, use everywhere

YAGNI (You Aren't Gonna Need It)

Bad: Add "flexibility" for future requirements Good: Implement only what's needed now

# Bad — YAGNI violation
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # Not needed yet!
        self.metadata = {}     # Not needed yet!
# Good — YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD (Test-Driven Development)

Every task that produces code should include the full TDD cycle:

1. Write failing test
2. Run to verify failure
3. Write minimal code
4. Run to verify pass

See test-driven-development skill for details.

Frequent Commits

Commit after every task:

git add [files]
git commit -m "type: description"

Common Mistakes

Vague Tasks

Bad: "Add authentication" Good: "Create User model with email and password_hash fields"

Incomplete Code

Bad: "Step 1: Add validation function" Good: "Step 1: Add validation function" followed by the complete function code

Missing Verification

Bad: "Step 3: Test it works" Good: "Step 3: Run pytest tests/test_auth.py -v, expected: 3 passed"

Missing File Paths

Bad: "Create the model file" Good: "Create: src/models/user.py"

Execution Handoff

After saving the plan, offer the execution approach:

"Plan complete and saved. Ready to execute — I'll work through tasks sequentially with TDD. Shall I proceed?"

Note: Poirot currently has no subagent delegation. Execute tasks manually in order, committing after each. If subagent support is added later, this skill will reference it for parallel task execution.

Remember

Bite-sized tasks (2-5 min each)
Exact file paths
Complete code (copy-pasteable)
Exact commands with expected output
Verification steps
DRY, YAGNI, TDD
Frequent commits

A good plan makes implementation obvious.