Plan with evidence

An illustrated, narrated adaptation of Lauren (@poteto),
The Complete Guide to pstack Pt. 2.

Source: https://x.com/poteto/article/2097732320606507506

This is an independent educational adaptation, not an official pstack production.
Synthetic narration: Microsoft Aria. Examples are explanatory, not benchmark results.

Chapters and transcript

00:00:00 — A longer plan is not a better plan.

Why can an agent follow a detailed plan and still build the wrong thing? Because a plan is not evidence that the problem, design, or result is right.

This lesson adapts Lauren, known as poteto, and her article, The Complete Guide to p-stack, Part Two. Her workflow connects research, planning, prototyping, and architecture.

The central idea is to understand the problem, explore solutions through code, and verify what actually happens. Verification is the prerequisite, not the finishing decoration.

00:00:34 — Two failures. Two missing inputs.

The article identifies two recurring failures: the agent misunderstands your intent, or it lacks the context needed to do the work correctly.

A capable coder can still solve the wrong problem. Specifying every implementation detail does not repair a misunderstood goal or an incomplete mental model.

Your job is to supply high quality context and a clear outcome, while leaving room for the agent to discover a solution you did not anticipate.

00:01:03 — Ask for the problem, not your diagnosis.

Start with an indirect prompt. Ask the agent to read the issue and restate the underlying problem in its own words before changing anything.

This compresses a noisy conversation into a problem statement you can inspect. It also exposes a red herring before the agent turns it into code.

Avoid embedding your favorite diagnosis in the question. For example, workers time out is an observation. The database needs a larger timeout is a hypothesis, not yet a conclusion.

00:01:36 — Build a shared mental model.

The article describes four complementary skills. How traces runtime mechanics: what calls what, where state lives, and how the subsystem behaves.

Why investigates motivation using evidence such as commits, review comments, issues, conversations, errors, and analytics. Teach combines mechanics and rationale into an explanation you can understand.

Recall retrieves relevant earlier conversations, so a fresh agent does not repeat old investigations. Teaching helps the agent too, because explaining its reasoning can reveal unsupported assumptions.

00:02:14 — Separate facts from hypotheses.

For an ambiguous production bug, request three things: what we know, the data supporting it, and the best hypotheses. This is one of the article's practical examples.

Keep these categories separate. A plausible explanation should not quietly become an established fact. Use the code and historical evidence to narrow the uncertainty.

The outcome of research is a grounded problem statement and constraints, not merely a confident sounding answer.

00:02:45 — Start where the user starts.

Once the problem is understood, work backwards from the experience you want. For a shared package, the article recommends readme driven development: write the user facing documentation first.

A tutorial forces you to ask what a developer must do to get a visible result. That makes awkward APIs and missing concepts easier to spot before implementation.

The tutorial becomes a concrete target the agent can check. You are specifying the outcome and the caller's experience, rather than over prescribing the internals.

00:03:19 — Four documents. Four different jobs.

The article uses the Diataxis framework to keep four documentation modes separate. A tutorial teaches a newcomer by doing. A how-to guide helps an experienced user solve a specific problem.

Reference is the complete technical description of an API or configuration. Explanation discusses background, design choices, and tradeoffs.

The technical writing skill separates these modes, and the unslop skill improves readability. Choose the document that serves the immediate goal instead of mixing all four into one sprawling readme.

00:03:55 — A prompt sequence that compounds context.

The article combines these ideas in a virtualization example. First, recall recent bug fixes and investigate how and why the existing virtualized list works.

Next, use that context to propose a new design, beginning with a tutorial showing how a developer would use the package in a React app.

Finally, ask the agent to explain the tradeoffs and demonstrate why the approach is better than the current engine. Better is something to show through verification, not a label to assert.

00:04:27 — Avoid both planning traps.

Two opposite mistakes produce weak designs. One is accepting the first proposal. The other is endlessly refining an abstract plan without running anything.

The article's alternative is prototyping: use cheap, throwaway code to answer a concrete question. Planning becomes an experiment, not just a conversation.

Give the agent room to try genuinely different approaches, and judge what the prototypes reveal rather than how persuasive the proposal sounds.

00:04:58 — Make alternatives comparable.

For a dropdown interaction, the article suggests two or three variants behind a simple switcher. Drive the real interaction, record it, and compare screenshots and relevant measurements.

Use the same task and conditions for each variant. Decide what you are trying to learn, such as whether the menu remains usable in a constrained layout.

The prototypes are disposable. Their purpose is to replace open questions with observations and help you choose a design. This applies to backend behavior as well as visual interfaces.

00:05:34 — Skills are tools. Playbooks are workflows.

One distinction matters: p-stack playbooks are reference files inside poteto mode, not separate skills. The agent loads the relevant playbook for the task.

For example, ask poteto mode to prototype a few options for a feature. The workflow organizes exploration and uses verification tools to inspect the result.

You do not need to manually invoke every ingredient when the established workflow already selects it.

00:06:03 — A five-phase architecture loop.

For larger changes, the architect skill structures the work into five phases: ground the problem, sketch competing designs, cross judge and synthesize, implement, and scrap the design if evidence shows it is wrong.

This is a loop, not a one way approval ceremony. Architecture starts from how the affected systems actually work and what their ownership boundaries allow.

The goal is a coherent interface and data model before the agent fills in the implementation details.

00:06:34 — Sketch a usable contract, not an essay.

In the sketch phase, independent candidate runners receive the same grounding brief. They may use different model families, and each produces a complete design package.

That package contains a caller usage sketch, core types, public function signatures, and a concise rationale. The signatures should follow from how the call sites ought to look.

The candidates also examine interface depth, design red flags, and failure modes with weaker models. The contract must be usable in practice, not just elegant on paper.

00:07:09 — Judge candidates. Then synthesize.

A cross judge using a different model evaluates the candidates against a strict rubric. The point is to challenge the designs before selecting and combining their strongest ideas.

Do not confuse this with adversarially reviewing a vague plan. The article warns that abstract debate can invent theoretical risks and unnecessary complexity.

Use executable prototypes to settle real uncertainties. Different models provide competing perspectives; empirical evidence still decides whether the design works.

00:07:42 — Let implementation challenge the design.

Implementation replaces the sketch's placeholders with real logic. If it suddenly needs extra parameters or unexplained shared state, surface that discrepancy instead of hiding it.

The article highlights repeated workarounds across unrelated callers and forced casts as evidence that the design may be wrong. Investigate the model, not just the symptom.

When the architecture does not fit, throw away the sketch and start again. Do not preserve a bad boundary merely because effort has already been spent on it.

00:08:16 — Now write the execution plan.

A tactical plan comes after you have a design you are happy with. The multi phase planning playbook breaks it into small, self contained, reviewable changes.

Each task is organized around proof and verification. Tests are useful, but the article says tests alone are not sufficient: the agent must actually run the code and check that it works.

The playbook also checks the plan's structure automatically. Temporary plans can coordinate large projects, but the author does not keep them as permanent competing sources of truth.

00:08:51 — Migration means preserving a contract.

Consider the article's UI library migration example. The request is not to improve the interface. It is to move the implementation while preserving the original result, bugs included.

A useful execution unit therefore needs a baseline, a bounded slice of migration, and visual regression plus live verification steps.

This shows why the acceptance target matters. If preserving behavior is the contract, an attractive redesign is still the wrong result.

00:09:23 — Choose the workflow for the uncertainty.

For an ambiguous bug, investigate first and report evidence and hypotheses. For a new webhook rate limiting boundary, architect first, answer open questions with prototypes, and review the design before proceeding.

For a reported regression, reproduce it on the baseline branch, fix it if confirmed, and show the real behavior afterward. The article gives a video as one useful form of proof.

Short prompts can work when the context is already rich and the workflow is established. Do it is a shorthand for a grounded process, not a replacement for one.

00:10:00 — The plan is convincing. Nothing ran.

Quick check. An agent presents a convincing architecture plan. You have not tried alternatives, and the key usability question remains unanswered. What is the best next move?

Add more detail to the same plan, try competing prototypes, or implement the entire design immediately? Pause here and make your choice.

Try competing prototypes. Make the uncertain behavior observable, compare the options fairly, and use the result to choose the design. More prose would not answer the question.

00:10:35 — Make planning produce evidence.

Here is the workflow to remember. Restate the problem without leading the diagnosis. Ground it in code, history, and relevant earlier work. Design backwards from the user's experience.

Prototype real alternatives. Sketch contracts for larger changes. Let implementation expose design mistakes, and then execute in small units with observable proof.

That is the article's core lesson: rigorous planning is not a longer document. It is a process that turns uncertainty into evidence. Source: Lauren at poteto, The Complete Guide to p-stack, Part Two.