Plan-and-Solve Prompting

1. Concept Overview & Systemic Problem

When a developer assigns a large engineering task to an AI (e.g., "rewrite the authorization module from JWT to sessions in the database"), the agent's impulsive reaction is to immediately edit the first random file.

This purely reactive approach causes critical failures:

1. Disruption of Dependency Order: The agent modifies an interface component before updating the database schema or creating the necessary TypeScript types.
2. Cyclical Fixes: The model fixes one error, breaking another related file, and gets stuck in an endless cycle of syntax patching without understanding the bigger picture.
3. Loss of Primary Objective: After 10 steps of bug hunting, the context gets cluttered with compiler messages, and the model forgets the user's initial task.

Plan-and-Solve addresses this issue through the classical engineering principle: Separation of Strategic Planning and Tactical Execution.

2. Architectural Taxonomy & Mental Model

The pattern is implemented through three complementary phases:

• 1. Discovery & Planner Phase: The agent analyzes the request, reads the file system in a read-only mode, and generates a clearly structured action graph: an array of steps with designated goals, success criteria, and necessary files.
• 2. Solver / Execution Phase: A specialized executor takes the first open item from the plan, calls the necessary tools (file editing, build execution), ensures the subtask is completed, and marks the item as done.
• 3. Replanning & Feedback Phase: If an error occurs during the execution of a step that cannot be resolved by simple repetition (e.g., a required module is missing from the system), the replanner reviews the remaining items in the plan, adding a step to install dependencies.

3. Technical Pipeline & Internal Mechanics

The lifecycle of working with the Plan-and-Solve pattern:

1. Plan Generation: The model forms a valid JSON object with an array of tasks: tasks: [{ id: 1, title: "DB Schema", status: "pending" }, { id: 2, title: "API Route", status: "pending" }].
2. State Injection: The plan is recorded in the agent's state. The user sees visual progress in the form of an interactive checklist.
3. Execution Loop: The orchestrator selects the next task with a pending status. The context is cleared of old debugging details, focusing only on the current task and final goal.
4. Invariant Check & Status Transition: After completing a step, a linter or unit test is triggered. If the check is successful, the status changes to completed. If not, the replan() method is called, which adjusts the unfinished steps.

4. Production Engineering Scenarios

01. Complex Codebase Migration

Transitioning a project from Next.js Pages Router to App Router:

• Step 1: Audit the pages/ folder structure and identify common Layouts.
• Step 2: Create the root app/layout.tsx and base styles.
• Step 3: Gradually migrate static pages.
• Step 4: Rewrite dynamic routes and API Routes in route.ts.
• Step 5: Perform a full project build and remove outdated files.

02. Creating New Features Based on Specification (Spec-Driven Development)

The agent receives a business requirement. Initially, it writes documentation and Zod schemas, aligns them with the user, and only after receiving approval does it step-by-step generate the backend, client hooks, and UI components.

03. Infrastructure Deployment of Servers

Stepwise hardening of a Linux VPS:

• Generate a plan with 6 steps (SSH keys, UFW firewall, fail2ban, package updates, creating a non-root user, disabling password access).
• Each item is executed separately with a mandatory status check of the port before disabling the previous communication method.

5. Pitfalls, Common Mistakes & Security

• Premature Planning: Creating a plan without prior analysis of the repository files. The model may plan to use libraries that are not present in the project. Solution: a mandatory "Discovery" step before launching the planner.
• Plan Rigidity: The agent stubbornly attempts to execute Step 3 when it becomes clear in Step 1 that the architecture requires a fundamentally different approach. Always implement dynamic replanning hooks.
• Micromanagement of 30 Steps: Too granular steps (e.g., a separate step for importing each type) waste time and money. Maintain the level of abstraction at the level of logical functional blocks.