markmdev Planning
Good plans prove you understand the problem. Size matches complexity — a rename might be 20 lines, a complex feature might be 500.
The handoff test: Could someone implement this plan without asking you questions? If not, find what's missing.
Verbatim Requirements
Capture the user's exact words at the top of every plan. No paraphrasing, no compression.
## Verbatim Requirements
### Original Request
> [User's ENTIRE message, word for word]
### Clarifications
**Q:** [Your question]
**A:** [User's ENTIRE answer, verbatim]
The Core Loop
ASK → EXPLORE → LEARN → MORE QUESTIONS? → REPEAT
Keep looping until you can explain: what data exists, how it flows, what needs to change, and what could go wrong.
Interviewing
Interviewing is the most important part of planning. You cannot build what you don't understand. Every unasked question is a assumption that will break during implementation.
Interview iteratively: 2-4 questions → answers → deeper follow-ups → repeat. Each round of answers should trigger new, deeper questions. If the answers don't spark follow-ups, you're not thinking hard enough.
Simple bug → 3-5 questions. Complex feature → 20-40+ questions across multiple rounds.
Push back if something seems wrong. You're the technical expert.
Exploring the Codebase
More exploration = better plans. The number one cause of plan failure is insufficient exploration.
Spawn as many Explore agents simultaneously as the task demands — 5, 10, 15, there is no limit. The system default of 3 concurrent agents does NOT apply here. Each question or area gets its own agent, all launched in parallel.
Follow up aggressively. When a round of Explore agents completes, read their findings, identify every new question or uncertainty, and immediately spawn another round of agents to investigate those. Expect 2-4 rounds of exploration before you're ready to plan. Findings always raise new questions — if they don't, you're not reading carefully enough.
Explore until you stop having questions, not until you've "done enough."
Plan Content
Plans document your understanding. Include what matters for this specific task:
- Current State: What exists today — relevant files, data flows, constraints, existing patterns. Ground the plan in reality before proposing changes.
- Changes: Every file to create/modify/delete, how changes connect
- Decisions: Why this approach, tradeoffs, assumptions
- Acceptance criteria: What must be true when each step is "done" — specific, not vague
- Test cases: For behavioral changes, include input → expected output examples
- Non-Goals: What is explicitly out of scope. Fence adjacent tempting work to prevent implementation drift.
Use ASCII diagrams when they'd clarify visual concepts, data flow, or architecture.
Self-Review Before Finalizing
Before presenting the plan, verify against real code:
- Existing controls: Identify permissions, lifecycle checks, feature switches, and constraints already in the codebase. State how new behavior integrates with or extends them.
- State invariants: Define legal lifecycle transitions and where enforcement lives (service layer, DB, or both). Don't leave state management implicit.
- Transaction boundaries: For multi-write operations, define boundaries so retries can't create split state.
- Verification executability: Every verification command must work with current tooling. If scripts or runners are missing, add setup steps.
Rules
No TBD. If the plan says "figure out during implementation," you haven't planned — you've procrastinated. Investigate now.
No literal code. Describe structure instead. Reference patterns: "Follow the pattern in validateUser."
External APIs: Check .meridian/api-docs/ for existing docs. Not documented? Run docs-researcher to research it.
Integration
If your plan creates modules or touches multiple systems, document how they connect: imports, entry points, configuration. Plans fail when code exists but isn't wired up.
Verification
Every plan ends with verification — commands or checks that prove the implementation works.
Plan Review
Before exiting plan mode, run the plan-reviewer agent. It validates the plan against the actual codebase — checking file paths, APIs, dependencies, and feasibility. The plan must score 9+ to proceed. If below 9, address findings with the user, update the plan, and re-run until passing.
TLDR
End every plan with a TLDR — 2-4 sentences that capture what you're building, the approach, and why. Anyone should be able to read just the TLDR and understand what this plan accomplishes.