gabrielmoreira CRISPI Planning
Overview
A multi-stage planning pipeline that separates research, design, and implementation into distinct context windows. Each stage produces a written artifact that feeds the next, preventing context window pollution and ensuring alignment before code is written.
CRISPI stands for: Context, Research, Implementation design, Structured plan, Implementation.
Core principle: Don't use prompts for control flow -- use actual control flow. Each stage runs in a fresh context window with fewer than 40 instructions, producing a document that becomes the input for the next stage.
When to Use
- Before starting any feature, bug fix, or refactor that touches more than one file
- When a ticket is ambiguous and needs research before you can estimate scope
- When you need alignment with stakeholders before writing code
- When working on unfamiliar parts of the codebase
- When a previous attempt failed due to context window exhaustion
When NOT to Use
- One-line fixes or typo corrections
- Changes where the implementation is already obvious and self-contained
- Purely mechanical refactors (rename a variable, update an import path)
- When you are already inside an implementation stage with a validated plan
Common Mistakes
| Mistake | Why it's wrong |
|---|---|
| Combining research and implementation in one context window | Research context pollutes implementation. Separate them so the agent doing research doesn't anchor on a specific solution, and the agent writing code doesn't waste tokens on exploration. (Dex [05:44:35]) |
| Writing a plan that reads like a horizontal layer cake ("first do all the models, then all the routes, then all the tests") | Horizontal plans break at integration boundaries. Build vertically -- one working slice at a time, each independently testable. (Dex [05:58:16]) |
| Skipping the plan and jumping straight to code | "Always start with a plan before coding." The plan is both your roadmap and your recovery mechanism when the context window resets. (Rafael [03:16:14], Sid [00:34:14]) |
| Writing the plan only in your head or in plan mode UI | Write plans to a file (docs/plan.md or docs/plans/). Files persist across context windows; plan mode state does not. (Rob [03:29:27], Sid [00:41:44]) |
| Letting the plan go stale during implementation | Keep the plan file updated with current task status -- check off completed items, note deviations. It is your context recovery mechanism. (Josh [03:28:11]) |
| Asking the research agent leading questions that reveal your preferred solution | Hide intent from research context. Frame as neutral questions so the agent explores broadly rather than confirming your bias. (Dex [05:44:35]) |
The Pipeline
digraph crispi {
rankdir=LR;
node [shape=box, style="rounded,filled", fillcolor="#f0f0f0"];
C [label="1. Context\n(Ticket Decomposition)", fillcolor="#d4e6f1"];
R [label="2. Research\n(Fresh Window)", fillcolor="#d5f5e3"];
I1 [label="3. Design Discussion\n(~200 lines)", fillcolor="#fdebd0"];
S [label="4. Structured Plan\n(Vertical Slices)", fillcolor="#fadbd8"];
I2 [label="5. Implementation\n(Worktree)", fillcolor="#e8daef"];
PR [label="6. PR", fillcolor="#d6eaf8"];
C -> R [label="questions.md"];
R -> I1 [label="research.md"];
I1 -> S [label="design.md"];
S -> I2 [label="plan.md"];
I2 -> PR [label="code"];
}
Stage 1: Context -- Decompose the Ticket
Goal: Turn a vague ticket into specific, answerable research questions.
Input: The ticket, issue, or feature request.
Process:
- Read the ticket and any linked documents.
- Explore the relevant parts of the codebase (
git log, grep for related files, read existing tests). - Decompose the ticket into 3-7 specific research questions. Each question should be answerable independently.
- Write questions to
docs/plans/questions.md.
Output: docs/plans/questions.md
# Research Questions for [Ticket Title]
## Questions
1. What is the current data flow from X to Y? Which files are involved?
2. Are there existing patterns in the codebase for handling Z?
3. What are the edge cases around [specific behavior]?
4. Does the current test suite cover [area]? What gaps exist?
5. Are there performance constraints we need to respect?
## Codebase References
- `src/services/foo.ts` -- current implementation of X
- `src/models/bar.ts` -- data model we'll likely modify
Key rule: Do NOT include your preferred solution in the questions. Frame them neutrally so research is unbiased.
Stage 2: Research -- Answer the Questions
Goal: Gather facts without deciding on an approach.
Input: docs/plans/questions.md (nothing else -- fresh context window).
Process:
- Open a fresh context. Load only the questions file.
- For each question, search the codebase, read relevant files, check documentation.
- Answer each question with facts, code references, and file paths.
- Note any surprises or constraints discovered during research.
- Write findings to
docs/plans/research.md.
Output: docs/plans/research.md
Key rule: This stage is research only. Do not propose solutions. Do not write pseudocode. Just answer the questions.
Stage 3: Design Discussion -- Align on Approach
Goal: Produce a short (~200 line) design document that explores 2-3 approaches and recommends one.
Input: docs/plans/research.md and docs/plans/questions.md.
Process:
- Open a fresh context. Load research and questions.
- Based on the research findings, propose 2-3 approaches with trade-offs.
- Recommend one approach with clear reasoning.
- Include an executive summary at the top (3-5 sentences).
- Include representative code snippets showing the recommended approach.
- Write to
docs/plans/design.md.
Output: docs/plans/design.md (~200 lines)
# Design: [Feature Name]
## Executive Summary
We will [approach] because [reason]. This affects [N] files and
introduces [key concept]. The main risk is [risk] which we mitigate
by [mitigation].
## Approach A: [Name] (Recommended)
[Description with code snippets]
## Approach B: [Name]
[Description with trade-offs]
## Decision
Going with Approach A because [reasons from research].
Key rule: Get alignment here. This is the cheapest place to change direction. Present this to stakeholders before proceeding.
Stage 4: Structured Plan -- Vertical Slices
Goal: Produce a detailed implementation plan organized as vertical slices, each independently testable.
Input: docs/plans/design.md and docs/plans/research.md.
Process:
- Open a fresh context. Load design and research.
- Break the approved design into vertical slices. Each slice delivers one working piece of functionality end-to-end.
- For each slice, list: files to create/modify, functions/signatures to implement, test cases to write, and acceptance criteria.
- Structure it like a C header file -- show the interfaces and phases without full implementation.
- Write to
docs/plans/plan.md.
Output: docs/plans/plan.md (~2 pages)
# Implementation Plan: [Feature Name]
## Status
- [x] Slice 1: Core data model
- [ ] Slice 2: API endpoint <-- CURRENT
- [ ] Slice 3: UI integration
- [ ] Slice 4: Error handling and edge cases
## Slice 1: Core Data Model
**Files:** `src/models/widget.ts` (new), `src/models/index.ts` (modify)
**Tests:** `src/models/__tests__/widget.test.ts`
Signatures:
- `createWidget(input: WidgetInput): Promise<Widget>`
- `validateWidget(widget: Widget): ValidationResult`
Acceptance criteria:
- Widget can be created with valid input
- Validation rejects [specific invalid cases]
## Slice 2: API Endpoint
...
Key rule: Vertical, not horizontal. Each slice should be mergeable on its own. Update the status checkboxes as you complete each slice during implementation.
Stage 5: Implementation -- Execute the Plan
Goal: Write the code, slice by slice, using the plan as both roadmap and context recovery.
Input: docs/plans/plan.md.
Process:
- Open a fresh context (or a git worktree for isolation). Load the plan.
- Implement one slice at a time. After each slice: run tests, update the plan status, commit.
- If you hit a problem not covered by the plan, update the plan before continuing.
- After all slices are complete, do a final review pass.
- Open a PR.
Key rule: When your context window resets mid-implementation, reload docs/plans/plan.md. The status checkboxes tell you exactly where you left off.
Quick Reference
| Item | Location |
|---|---|
| Research questions | docs/plans/questions.md |
| Research findings | docs/plans/research.md |
| Design discussion | docs/plans/design.md |
| Implementation plan | docs/plans/plan.md |
| Plan status tracking | Checkboxes in plan.md |
| Named plan alternative | docs/plans/YYYY-MM-DD-<topic>-plan.md |
Key Principles
- Each stage gets a fresh context window. Don't carry research tokens into implementation. Each stage reads the previous stage's document and nothing more.
- Every stage produces a file, not a conversation. Files persist across context resets. Conversation history does not. The plan file is your context recovery mechanism.
- Vertical slices, not horizontal layers. Build one working end-to-end slice before starting the next. Each slice is independently testable and mergeable.
- Research and implementation are separate concerns. Hide your solution intent from the research stage. Let facts drive design, not the reverse.
- Keep the plan alive. Update status checkboxes, note deviations, add discovered edge cases. A stale plan is worse than no plan -- it gives false confidence.
- Under 40 instructions per stage. If a stage's prompt is growing beyond 40 lines of instruction, you are combining stages. Split it.
Attribution
Based on techniques shared at the Coding Agents: AI Driven Dev Conference. The CRISPI pipeline draws primarily from Dex (HumanLayer) who presented the full Questions -> Research -> Design -> Structure -> Plan -> Worktree -> Implement -> PR pipeline [05:44:35 - 06:01:43], including the critical insight of separating research from implementation intent. Plan-as-context-recovery comes from Sid (Anthropic) [00:34:14, 00:41:44] who advocated extensive plan mode use and checking plans into docs/. The "always start with a plan" principle comes from Rafael [03:16:14] who stressed including code snippets and executive summaries. File-based plans over built-in plan mode was advocated by Rob [03:29:27], and keeping the plan updated with task status was emphasized by Josh [03:28:11].