Cycle: plan · do · study · act

The four cycle commands. Each records to the active project’s graph and (if an LLM is configured) prints coaching. See Your First Cycle for a narrative walkthrough.

pdsa plan

Enter a plan; the LLM sets a verifiable expected evaluation and a new cycle starts.

pdsa plan "<what & why & how>" [--expect "<expected>"] [--fresh] [--no-recall] [--json] [--project <name>]

Flag	Effect
--expect "<text>"	Use your own expected evaluation instead of the LLM-generated one.
--fresh	Start an independent cycle; do not link it as a reinforcement of the previous one.
--no-recall	Skip auto-injecting recent-cycle learnings into the coaching prompt.
--json	Emit a JSON object instead of prose. See For AI Agents.
--project <name>	Record to a specific project’s DB.

If the previous cycle’s act asked for reinforcement, plan links this cycle to it with a REINFORCES edge (unless --fresh).

Recent-cycle learnings are auto-injected into the coaching prompt so the LLM avoids repeating past mistakes — pull them explicitly with pdsa recall, or disable injection with --no-recall.

pdsa do

Report what you actually did; organizes Plan → Do and flags the gap.

pdsa do "<what you changed / ran / observed>" [--json] [--project <name>]

Requires an in-progress cycle (run pdsa plan first).

pdsa study

Report results; the LLM judges them against the expected evaluation and records a verdict.

pdsa study "<results / metrics / observations>" [--json] [--project <name>]

Records: verdict (met / partial / unmet), the measured actual, and a learning narrative.

pdsa act

Learnings + reinforcement decision; closes the cycle.

pdsa act [--note "<memo>"] [--reinforce "<what to reinforce>"] [--json] [--project <name>]

Flag	Effect
--note "<memo>"	Attach a free-form memo.
--reinforce "<text>"	Force reinforcement of a specific thing (next plan links here).
--json	Emit a JSON object (includes reinforce, what, and the running hitRate).

If the verdict wasn’t met, the next pdsa plan auto-links as a reinforcement cycle unless it’s run with --fresh.

Machine-readable output

Every cycle command takes --json — the prose banners are skipped and a single JSON object is written to stdout, exposing the fields the CLI already parsed (expected / verdict / actual / …). Default output is unchanged. See For AI Agents.