Skip to content
pdsa

Your First Cycle

A PDSA cycle is four commands. Each one reads back coaching from the LLM and records structured data to the graph. Do the work between the steps — the point is to test the hypothesis you set in plan, then capture what you learned in study.

Plan — commit to an expected outcome

Section titled “Plan — commit to an expected outcome”
Terminal window
pdsa plan "what & why & how"

plan starts a new cycle and asks the LLM to turn your intent into a verifiable expected evaluation — a one-sentence success criterion or metric. People usually plan but omit this; pdsa makes it explicit so study has something concrete to judge against.

  • Override the auto-generated criterion with --expect "<your own>".
  • Force a brand-new cycle (don’t link it as a reinforcement of the previous one) with --fresh.

Do — report what you actually did

Section titled “Do — report what you actually did”
Terminal window
pdsa do "what you changed / ran / observed"

do organizes Plan → Do from a graph-engineering view and points out the gap between what you planned and what happened. Now go verify the hypothesis.

Study — what did we learn?

Section titled “Study — what did we learn?”
Terminal window
pdsa study "results, numbers, observations — did the hypothesis hold?"

This is the heart of PDSA. study is not “Check (did it pass?)” — it’s “Study (what did we learn?)”. The LLM compares your result to the Plan’s expected evaluation and records a verdict:

met — fully met the expected outcome · partial — partially · unmet — not met.

It also records the measured actual and a short learning narrative.

Act — decide the next move

Section titled “Act — decide the next move”
Terminal window
pdsa act --note "optional memo"

act proposes the next improvement action and decides whether immediate reinforcement is needed. If the verdict wasn’t met (or something clearly needs fixing), the next pdsa plan is automatically linked as a reinforcement cycle (a REINFORCES edge) — unless you pass --fresh. You can also force it with --reinforce "<what to reinforce>".

The result

Section titled “The result”

After one cycle your graph holds four phase nodes (Plan/Do/Study/Act) with the expected criterion, the verdict, and the measured actual — plus a REINFORCES edge if this cycle carried forward from a previous one. Run it again next time and the memory compounds.

Terminal window
pdsa status    # progress + hit-rate
pdsa view      # visualize it

Read more about the model in The PDSA Loop and Expected → Verdict → Reinforce.