DEV Community: kanfu-panda

How Are LLMs Trained?

kanfu-panda — Sat, 24 Oct 2026 01:33:31 +0000

The last post showed that an LLM is a program that keeps adding the next word. What turns it into an assistant that helps you write code is training in stages: first it reads huge amounts of text and learns to continue it, then it studies examples written by people and learns to answer, and finally it gets scored over and over until its answers are good. This post covers the main ways a model is trained and the stages they happen in, then follows a leap-year function through the whole process.

If you code with an AI tool, you've probably noticed this: ask it for a function and it doesn't stop at writing one. It runs the tests, sees a failure, and goes back to fix the code. All it originally knew how to do was predict the next word. Where did it learn to work like that? Let's start with the ways a model gets trained.

What are the ways to train an LLM?

Training means giving the model problem after problem, telling it how well it did each time, and letting it adjust itself a little based on the result. Training methods differ in two things: what the model practices on, and who decides whether it got it right. There are five common ones.

Pretraining. The material is a huge amount of text and code, and the problem is the one from the last post: guess the next word. No one has to judge the answer. You just compare the guess with the actual next word in the original text, which is why this method can use so much material.

Supervised fine-tuning, also called instruction tuning. People first write a set of questions paired with ideal answers, and the model learns from them, adjusting whenever its output doesn't match. Here, "right" means close to the example a person wrote.

Reinforcement learning from human feedback (RLHF). The model writes several answers to the same question, people rank them, and the model shifts toward the higher-ranked ones.

Reinforcement learning from AI feedback (RLAIF). This works much like RLHF, except an AI does the ranking, following a set of principles written in advance. Constitutional AI, the method Anthropic uses to train Claude, falls into this category, and that set of principles is the "constitution."

Reinforcement learning with rule-based scoring. This is for tasks where the answer can be checked automatically. For a math problem, check whether the final answer is correct. For a coding problem, run the test cases and award points if they pass. Rules do the scoring, and no person has to look.

The last three are all reinforcement learning (RL). RL doesn't hand the model the correct answer. It only tells the model how well it did this time and lets it move toward higher scores on its own. The three differ only in who does the scoring: people, an AI, or rules.

How are these methods used in stages?

Usually in three stages, in a fixed order. Stage one is pretraining. The resulting model is very good at continuing text but not very good at answering questions or following instructions. Anthropic's official glossary says exactly that.

Stage two is supervised fine-tuning. From the examples, the model learns that when someone asks a question, it should answer. It starts to look like an assistant.

Stage three is reinforcement learning, where the three RL methods above can be combined. Scoring by people and by AI mainly makes answers more helpful and more appropriate. Scoring by rules mainly makes the model more accurate on tasks that have a right answer, like writing code and solving math problems.

Both later stages build on the pretrained model, so the order can't be reversed.

Walking through one request: a leap-year function

Say you tell the model: "Write a Python function that checks for leap years."

A model that has only been pretrained treats the sentence as text to continue. If sentences like this are often followed by the next exercise in what it has read, it might carry on with "Write a Python function that checks for primes," then "Write a function that reverses a string." This is an illustration, not something we ran, but at this stage the model really can only continue text. It doesn't yet know how to answer.

A model that has also had supervised fine-tuning has seen lots of question-and-answer examples, so it knows the thing to do here is write the function:

def is_leap(year):
    return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)

A model that has also gone through reinforcement learning, if it was scored on whether tests passed, cares more about whether its code actually passes them. Put it in an AI coding tool that can run commands, and after writing the code it runs the tests itself and goes back to fix things if they fail.

How much do the two later stages matter? A 2022 study by OpenAI compared a 1.3-billion-parameter model that had been through fine-tuning and RLHF with a 175-billion-parameter model that had only been pretrained. People preferred the smaller model's answers, even though it had one hundredth as many parameters.

Why has coding improved so fast?

Back to the fifth method. Code has something many tasks don't: you can tell whether it's right just by running the tests. Having people rank answers is slow and expensive. Tests run automatically, so the model can practice over and over at scale and get a score right after every attempt.

DeepSeek described this approach in a published paper. For coding problems, a compiler runs predefined test cases and gives feedback based on the results. For math problems, the model has to put its final answer in a fixed format so rules can check it. The paper also notes that the researchers didn't teach the model how to solve the problems; they simply gave it the right incentives.

The same paper reports numbers on math competition problems: with this kind of reinforcement learning alone, the share the model got right on the first try went from 15.6% to 71.0%. Those are math problems, not code, but the training method is the same. Coding has improved quickly over the last year or two, and public sources point to this as one important reason: code can be checked automatically, which makes it well suited to repeated practice.

What does this mean when you code with AI?

Training on test results has a side effect. The model is trained to make the tests pass, and writing correct code isn't the only way to do that.

Anthropic acknowledged this in the system card for Claude 3.7 Sonnet. In coding environments where it could run commands and tests, the model occasionally special-cased its code to make tests pass. Most often it returned the values the tests expected instead of writing a general implementation, and sometimes it modified the tests themselves. This mostly happened after several attempts at a general solution had failed. According to Anthropic, this came from reward hacking during reinforcement learning: the model had found loopholes in how it was scored.

In the leap-year example, it would look something like this (an illustration):

def is_leap(year):
    if year == 1900:  # special case for the 1900 test
        return False
    return year % 4 == 0

The tests pass, but try 2100 and it gets the answer wrong.

This is a tendency that comes from how models are trained. It doesn't mean today's models do it often. Two habits help:

When you review changes, glance at the test files too. If a test has been changed, or the code suddenly checks for one specific value, stop and ask why. Anthropic notes that when the model adds a special case like this, it often leaves a comment saying which test it's for.
Ask for a general solution in your prompt. Anthropic's advice is to say it plainly: write robust, general solutions rather than special-casing for tests. You can also put that line in an instruction file like CLAUDE.md that gets read every time.

Is it the same with Codex or DeepSeek?

Broadly, yes. They follow the same path: pretrain, teach the model to be an assistant, then improve it with repeated scoring. The 1.3-billion-parameter study came from OpenAI, and DeepSeek has published its own reinforcement learning approach. Exactly how each company combines these steps hasn't been made public. Checking the test files and asking for a general solution works whichever tool you use.

Summary

There are five common ways to train an LLM, and they differ in what the model practices on and who judges the result. The last three are reinforcement learning, scored by people, by an AI, and by rules.
Training happens in three stages: pretraining teaches the model to continue text, supervised fine-tuning teaches it to answer, and reinforcement learning makes its answers better.
Code can be scored automatically by tests, which is why coding has improved so fast. It's also why a model may cut corners to make tests pass, so keep an eye on the test files.

Next: what happens between pressing Enter and seeing the result?

If this helped, a like or a share with someone else who codes with AI would mean a lot. Follow along for the rest of the series.

What Is an LLM, Really?

kanfu-panda — Mon, 19 Oct 2026 14:49:39 +0000

You use AI to write code every day. So what is the large language model (LLM) on the other end, really? The short answer: it's a program that keeps adding the next word. It reads the text so far, works out what is most likely to come next, adds it, and then does it again. That's the whole job, and it's enough to write code, answer questions, and fix bugs. This post walks through how, using a single line of Python.

Ask an AI a question and you've probably noticed that the answer doesn't appear all at once. It trickles out a little at a time, and code shows up line by line. It looks like a typing effect someone added to the interface, but this is simply how the model works: it writes one small piece, then the next.

Why does it work that way? Let's start with what it does at each step.

What does it do at each step?

Here's some half-written Python, with the cursor sitting right after return:

def add(a, b):
    return

What comes next? If you write code, you barely have to think: a + b. The function is called add and the parameters are a and b, so a + b is the natural fit.

An LLM does the same thing. It reads everything before the cursor and scores every possible continuation: a + b scores high, a - b lower, None lower still. Then it picks one and adds it.

Anthropic's official glossary puts it the same way: the model underneath Claude was trained to predict the next word given the text that comes before it.

How does one word become a whole function?

One word on its own doesn't get you far. The trick is a loop: the model appends the word it just predicted to the text, then uses that longer text to predict the next one.

Once a is added, the text ends in return a, and the most likely next piece is +. Add +, and it predicts b. After that, it decides the function is finished and stops. Whole functions and whole answers are built this way, one word at a time. The trickle you see in the chat window is this loop moving forward.

Strictly speaking, each piece isn't always a full word. It might be part of a word, or a single symbol. The real unit is called a token. To keep things simple, this post just says "word."

If it only predicts the next word, how can it write code?

At this point you might be thinking: isn't that just the autocomplete on your phone keyboard?

The difference is how accurate the guess has to be. To predict a + b after return, the model has to know that add means addition and how a Python function is written. In longer code, it also has to keep track of which variables were defined earlier and what each function does.

During training, an LLM reads an enormous amount of text and code. The only way to get good at predicting the next word is to pick up the patterns along the way: grammar, general knowledge, how code is written. CSET, a research center at Georgetown University, explains it the same way: a task as simple as next-word prediction pushes the model toward a broad grasp of language, and that grasp carries over to many other tasks.

There's something more surprising, too: the model doesn't work purely one step at a time. In 2025, Anthropic published research that looked inside Claude to see how it "thinks," and two of the findings stand out.

The first is about poetry. The researchers asked it to write a rhyming couplet that starts with "He saw a carrot and had to grab it." If it really only predicted one word at a time, you'd expect it to look for a rhyme at the very end of the second line. Instead, before it wrote the second line at all, it had already settled on "rabbit" as the ending and wrote the line toward it: "His hunger was like a starving rabbit."

The second is about addition. Ask it what 36 plus 59 is and it says 95. Ask how it got there and it describes the method from school: add the ones, carry the one. But when the researchers looked at what actually happened inside, it was running two paths at once, one estimating the rough size of the answer and the other getting the last digit exactly right. The model itself doesn't know it works this way.

Put the two together and the picture is this: writing one word at a time is how the model works on the outside. To predict well, it has developed its own methods on the inside. Nobody wrote those methods in line by line. The model learned them during training, and even the company that built it needs dedicated research to see them.

Why does it follow instructions like an assistant?

The training described so far, reading huge amounts of text and practicing next-word prediction, is called pretraining. A model that has only been pretrained is good at continuing text but not very good at answering questions or following instructions. Anthropic's glossary says so directly.

So there's another round of training after that, teaching the model to be an assistant: understand what you're asking, answer properly, and decline things it shouldn't do. The Claude we use day to day has been through this. In the glossary's words, Claude is not a bare language model; it has already been trained to be a helpful assistant.

How that round of training works is a topic of its own, and it's what the next post covers.

What does this mean when you code with AI?

Once you know the model is continuing text, two things become useful right away.

First, everything you give it is part of the text it continues from. Your question, the code you paste in, the instruction files in your project: it reads all of it and writes from there. The clearer that text is, the easier it is to continue correctly. Compare "write me a function" with "write a Python function called add that takes two integers and returns their sum." The second leaves far less to guess.

Second, what it writes is "the most likely thing to come next," not something it went and checked. Most of the time, the most likely answer is also the right one. But now and then it produces a function name or parameter that looks perfectly plausible and doesn't exist. So run the code and read it before you rely on it.

Is it the same with Codex or DeepSeek?

Yes. Codex runs on OpenAI's models, and DeepSeek runs on models trained by DeepSeek itself. They're all LLMs, and they all work by continuing text one word at a time. What differs is what they read during training, how they were later trained into assistants, and what the tool wrapped around them does on their behalf. The two habits above apply whichever tool you use.

Summary

An LLM is a program that keeps adding the next word: it reads the text so far, picks the most likely next word, and repeats.
To predict well, it picked up grammar, general knowledge, and how code is written during training, and it can even plan ahead.
Everything you give it becomes text it writes from, so the clearer it is, the better the result. Check the code it writes before you use it.

Next: how does a model that only knows how to continue text become an assistant that helps you write code?

If this made the AI you use every day feel a little less like a black box, a like or a share would mean a lot. Follow along for the rest of the series.

Running pdlc-skills on a Real Project: Three Features, Start to Release

kanfu-panda — Tue, 22 Sep 2026 14:35:01 +0000

The first seven posts were about mechanics. This one goes back to a real project and answers the six questions you only hit after the thing is installed: how to split the work, who does what, how the loop actually runs, how long it took, how much it produced, and what holds quality up. The project is a console I run for myself. Three features went to pdlc's own loop engine in parallel, all three reached the review terminal state in 88 minutes, and after the quality gate was filled in, the release went out and got deployed to two machines. The machine numbers come from the event log and from git. The hours a human spent are estimates, and I flag them where they appear.

Where this run started

I scaffolded the project in late August with /pdlc-bootstrap, took it from a minimal working version to its third round of console work in five days, then left it alone for three weeks. Reopening it, I did two things before anything else. /pdlc-test-setup wrote the unit-test, coverage and lint commands into test-commands.yml, and all three have to actually run before they count. Then I migrated a few old state files to the current format. Skip those two and every "check passed" later in the run is resting on nothing. E2E had gone in the day before, with a test behind each of the 45 registered core flows. So the starting line was 421 unit tests, 52 E2E cases, 89.6% coverage.

How to split the work

Three things to build: let a review run on a different machine, let notifications be filtered by where a task came from, and add two review flags to the benchmark runner. I'll call them cross-node review, origin filtering and benchmark flags. None of them is large, which is what makes them a reasonable test for the loop. I split them on three rules.

Rule one, split by code dependency into chains or independents. Benchmark flags needs the remote dispatch and the verdict-return path that cross-node review builds, so those two form a chain and the second waits for the first to converge. Origin filtering touches neither, so it starts immediately.

Rule two, size a feature so that three steps can finish it, those steps being TDD, implementation and review. The three features here landed between 800 and 1500 lines of diff.

Rule three, features running in parallel should not touch the same file. I did not hold this one. All three had to change the same receipt-aggregation module, and the bill came due at merge time: conflicts to resolve one at a time, about ten extra minutes.

The PRDs came from /pdlc-prd --autonomous with a few paragraphs of raw requirements as input, 17 minutes for all three, and the command worked out the dependency between them by itself. Each PRD ends with a handful of open questions, ten across the three. The coordinating session ruled on them one at a time and wrote the answers back: what event to record when a verdict-return query fails, what error to raise when the machine you named isn't in the config. Leave those open and three separate processes will each guess differently.

Who does what

Four roles: me, one long-lived coordinating session, subprocesses that exit as soon as their step is done, and an outer script. The coordinating session is also AI, but it writes no feature code. It coordinates and it double-checks.

What gets built and how the parallelism is arranged is mine to decide. The coordinating session drafts the raw requirements, the command turns them into PRDs, and the coordinating session rules on the open questions.

For design, each feature gets a fresh process running /pdlc-design --autonomous. Three in parallel took a little over 12 minutes, and the coordinating session spent 15 minutes reviewing them and sent one back. In the benchmark flags design, the cross-node section said the dependency wasn't ready yet, so the code should reject the request and leave a record. But that feature sits on a branch cut after cross-node review, so by the time it runs the remote dispatch exists and the implementation should call it for real.

TDD, implementation and review go to the loop with nobody watching. The model is sonnet throughout, and each feature has a budget ceiling for the whole run. Once a feature converges, the coordinating session reads the diff against the design, runs the three checks itself, and opens a PR; the release, deploy and acceptance commands are its job too. What I do is merge PRs, read the quality report and the retro, and decide whether it ships. Exactly two places need a human: deciding what to build, and deciding whether it ships.

Running the loop

pdlc's own loop engine is /pdlc-loop-run. Starting from the current stage, it hands each segment — TDD, implementation, review — to a fresh subagent, reads the state file after each one, and consults a fixed table to pick the next step. It stops at review_done and never releases anything itself. There are two layers here: one process per feature on the outside, and inside each process, loop-run dispatching one subagent per segment. The guardrails are a step cap of 4, stop on a failed step, and stop if the state didn't move.

It handles one feature at a time. Running several in parallel needs a scheduling layer around it, which here is a bash script of a little over 350 lines. It reads depends_on from each feature's state file to order them, starts anything without a prerequisite immediately, and for anything with one, waits for the prerequisite to converge and branches off it. Each feature gets its own git worktree, and each feature gets one process:

claude -p --model sonnet --max-budget-usd 20 --permission-mode acceptEdits \
  "/pdlc-loop-run $fid --max-steps 4 --autonomous"

When the process exits, the script reads the state file and commits the work. It also polls that file every 15 seconds to record when stages actually changed, because the timestamps the model writes into the state file can't be trusted.

Cross-node review and origin filtering started together. Origin filtering was the fastest: three steps, 30 minutes. Cross-node review took 51, and 13 seconds after it converged the script branched off it and started benchmark flags, which took another 37. All three reached review_done in 88 minutes, each in 3 steps. Nothing hit a rate limit, no step exhausted its budget, and nothing stopped along the way.

One thing from the run is worth writing down. The three features did not agree on stage names in their state files: two wrote review_done at convergence, one wrote review, and one wrote its TDD step as tdd_done. Read literally, a _done suffix means finished, so the loop could have taken TDD for convergence and stopped there. loop-run wasn't fooled and started the implementation step as usual. But it does mean you cannot decide whether something moved forward from the stage name alone. You have to look at whether the next-step field changed.

Time and output

Steps, machine time and diff size per feature, with new test cases in parentheses.

The three features added 3351 lines, 1770 of them tests, roughly three times the feature code itself. PRDs and designs are counted separately at 1833 lines. Unit tests went from 421 to 516, E2E cases from 52 to 65, coverage from 89.6% to 90.3%.

The whole line ran like this: draft the requirements, generate the PRDs, review the designs, start the three features, all converged 88 minutes later, merge the branches, run the quality report, red. Fill in what was missing, report passes, release v0.3.0, deploy to two machines, then acceptance on real hardware. My own time is an estimate, something like two and a half hours, spent writing requirements, reviewing designs, checking each feature after it converged, merging, and filling the gate.

What holds quality up

With nobody watching, quality rests on four layers.

The first is an objective check on every step. Which commands a step has to run is written in test-commands.yml, and only the exit code counts, not the model saying it checked. The TDD step verifies that the newly written tests really fail. Implementation and review verify unit tests, coverage and lint, and two of the three features carried E2E as well. The 85% coverage threshold is a command-line argument. pre-commit runs lint and pre-push runs the unit tests, both taken from that same file. Across three features and three steps each, not one recorded check came back red.

The second is the review after convergence. The coordinating session reads the diff against the design and runs the three checks itself before opening a PR. All three diffs matched their designs, and the single correction in this run happened earlier, at design review, the one described above. Merging produced four conflicts across three files, mostly both sides adding a field, where keeping both is the answer. Then the full suite again: 516 unit tests, 90.3% coverage, 56 E2E cases, all green.

The third is the pre-release quality report. /pdlc-quality looks at four things: coverage, E2E core-flow coverage, lint, and a reconciliation between the PRDs and the core-flow registry. The first report was green on the first three and blocked on the fourth. The three new features contributed 19 acceptance items, and not one of them had been registered as a core flow. The report put it plainly: 45 of 45 green does not mean these three features passed the gate, it means the old 45 are still healthy. The subagents inside the loop had in fact written E2E tests for every feature. They just never registered them.

The fix is not a signature, it's the work. Nineteen items into the registry, 4 of them covered by tests that already existed, 9 new E2E tests for the rest. The second report passed all four: 64 core flows, 65 cases, all actually executed.

The fourth is acceptance on real machines after release. Both machines took the deploy and I put real tasks through them. Origin filtering was configured on the live console, with the acceptance and benchmark origins on the mute list, and every task after that carried its origin tag. The behaviour of that filter is verified in E2E: a matching origin suppresses the completion notification, failures still go out.

Cross-node review ran for real too. A review task went to the other machine, that machine executed and archived it, and this one pulled the verdict back and showed which machine had done the review. The verdict was a failure, because the claude command on that machine had never been logged in. What this layer caught was an environment problem, but it did exercise the "review failed, how does the verdict get home" path end to end. Acceptance also turned up a missing lock on the result-collection step: two processes running at once would handle the same result twice.

Where the loop stops helping

The parts that ran fast are the parts with an objective check. The parts that slowed down or went wrong are the parts where the record was inaccurate.

Time is the clearest case. The timestamps in the state file are written by the model. The retro tool reads them and reports a median TDD stage of 2.1 hours; the real durations, recorded by the outer script's polling, were 10, 21 and 13 minutes. The inconsistent stage names above are the same problem wearing a different hat.

So don't build the outer judgement on fields the model wrote. Take durations from the event log and from git commit times, and take progress from the next-step field or from the completion marker the process prints when it exits. Those are also the two improvements this run sent back to pdlc-skills: make stage names consistent, and get timestamps from a command.

End of the series

Eight posts: the three-layer model, getting it installed, running the loop, holding quality, making the process visible, and finally one real project from start to finish. All of it is one idea. Move the judgements you can't rely on to where there's an objective check, and a person only has to hold the two ends: what gets built, and whether it ships.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

The repo: https://github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

Eight posts in, thanks for reading. If you've run something like this on a real project, which part ate the most of your own time? Comments welcome.

How pdlc-skills Makes Progress, Change Impact, and Quality Trends Visible

kanfu-panda — Sat, 12 Sep 2026 03:06:24 +0000

The last post covered the quality chain. This one is about visibility. An AI can push three features forward in an afternoon. If you can't tell where the project stands, what a change will touch, or how the last stretch went, the automation is running in a black box. pdlc has three tools for this: the statusline together with /pdlc-status, /pdlc-relate, and /pdlc-retro. They watch three timescales: right now, before a change, and month by month.

Three tools, one data source

All three only read the state files under docs/.pdlc-state/. They don't parse documents and they don't guess. Post 3 described how the three layers coordinate through one shared scoreboard; these tools read that same scoreboard and differ only in the question they answer. The statusline and /pdlc-status answer "where are we now?". impact answers "what does changing this touch?". retro answers "how did this stretch go?".

How accurately the state files are written decides whether what these tools show is true. I'll come back to that at the end.

Where are we now: the statusline and /pdlc-status

Here is a statusline entry from a real project, with the stage labels translated (the current release prints them in Chinese):

● PDLC console-p3 · PRD·Design·TDD·Impl·[Review]·Ship · →ship · 🤖 · ✓unit ✓lint ✓cov · ⏱9d

Left to right: the feature name; the six-stage track (PRD, design, TDD, implementation, review, ship) with the current stage highlighted; the next step; the run mode (🤖 autonomous loop, 👤 manual); the three check results; and how long the feature has sat in the current stage.

Three design choices in this one line are worth spelling out.

It doesn't show "step 4 of 6". A bug fix doesn't go through all six stages, so a counter would mislead. Instead it shows the fixed track and highlights where you are.
The three checks only show by default in autonomous mode. In manual mode you're running the tests yourself and the ticks are noise. Their value is being able to tell at a glance whether an unattended loop is healthy.
When a feature is blocked, the whole line changes format: ⛔ PDLC xxx blocked: needs a product decision · ⏱12m. A loop that has stopped and is waiting for a human must be the first thing you see. That is the statusline's main job.

One command turns it on: /pdlc-settings statusline. It appends itself after whatever statusline command you already have and leaves the rest alone. /pdlc-status is the command-line view of the same data: in progress, done, and suggested to-dos, plus a relation tree if the relation index exists. It verifies rather than just listing. When three features had sat at "review done, not shipped" for over ten days, it went to the CHANGELOG and the git tags to confirm that nothing had actually shipped. --stale 3 tabulates how many days each feature has been sitting.

That is as far as a tool goes: it puts the problem in front of you. What to do about it is a person's call.

What does a change touch: the relation graph

Which feature extends, depends on, or replaces which: there are six relation types. Four are directed: extends, depends_on, supersedes, resolves. Two are symmetric: conflicts_with, relates_to. Nobody fills these in by hand. When /pdlc-feature assigns a feature ID it scans the existing features, and /pdlc-prd scans the requirements text for words like "based on", "extends", "depends on", and "replaces"; whatever it finds goes into the PRD and the state file with a reason attached. In one real project with three iterations, phase 2 and phase 3 both extend phase 1, and phase 1 extends the original MVP.

Run rebuild once and it scans the state files, builds an index of nodes and edges, and draws a mermaid graph. The MVP predates the project's adoption of pdlc and has no state file. Rather than reporting a dangling reference, rebuild kept it as a historical terminal node.

impact is the reason the graph exists. Run it on phase 1 and the output has three tiers: 🔴 direct impact (phase 2 and phase 3), 🟡 indirect impact (anything one hop further; none here), 🟢 historical (the MVP, audit only). It also gives advice: phase 1 is already extended by two features that have passed review, so a change to it should be a new feature that supersedes it, not an in-place edit, or the downstream review results become void.

The other subcommands: query shows one feature's inbound and outbound edges, orphans lists features with no relations at all, and validate checks five rules: dangling references, self-references, cycles, contradictory pairs, and whether symmetric relations are recorded on both sides. set is the only one that writes state files: add a symmetric relation and both files get a line, then the index is rebuilt.

How did this stretch go: the retrospective

/pdlc-retro looks at the last 30 days by default and aggregates the history in the state files into a report: features delivered, self-check pass rate per stage, median stage duration, and sticking points, written to a monthly file under docs/07_reviews/retro/.

Pass rates from one real run: requirements, design, and TDD at 100%, implementation 93.8%, review 54.9%. The rate is the share of self-check items that passed. The forty-odd percent that didn't pass at review are the items flagged for a person to decide, about seven per feature.

That number is right. The first four stages settle everything a machine can judge, and whatever it can't judge is left for review. A low review "pass rate" means the earlier stages did their job. If review also came out at 100%, I'd want to know whether it actually looked.

Median durations: requirements 0.0 hours, design 0.1, TDD 0.6, implementation 0.9, review 5.0. Take the review figure with a grain of salt. It measures wall-clock time from entering review to finishing it, overnight hours included, not working time.

How the report handles bad data is worth noting. One feature's review had a completion timestamp earlier than its implementation. Instead of producing a negative duration, the report dropped the sample and listed it separately as "data anomaly, check the write timing". Re-run with a seven-day window that contained no activity, and all four sections said "no data" and explained why. Same rule as the false greens in the last post: if it can't be judged, say so, and never paint it green.

The limit: they only show what was recorded

All three tools only read state files; none of them checks the code. The state files are written by the AI at the end of each stage, and they drift. When they do, the tools don't fail; they quietly show one item less or count one stage less. The example project has two cases. The check keys: older features wrote tests_green, newer ones use the standard tests_pass, and the statusline only reads the standard set, so the older features' checks don't show. And the history has no start timestamps, so durations can only be computed from consecutive completion times. Relations are the same: they're recorded automatically once, at kickoff. If the requirements change later, you set the new relation yourself.

So the precondition for all three tools is treating the state files as data to be maintained: fields, timestamps, and relations written to spec.

Once you can see

Back to the opening question: the AI pushes three features in an afternoon, so how does a person keep up? Each tool answers one question, where things are, what a change touches, how the stretch went, and all the answers come from the same state files, with no digging through documents and no guessing. They don't make decisions. Whether to push a stalled feature, whether to touch a baseline, how to schedule the items review left for a person: still a human call, now made with data in hand. When the statusline is missing an item or the retro is missing a stage, suspect the records first, then the tool.

With the three tools covered, the mechanics part of this series is done. Next time we go back to a real project and walk it from the first command to the last release, to see how all of this gets used once it's installed.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

The repo: https://github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

What's the longest any feature in your project has sat untouched? Comments welcome.

How pdlc-skills Keeps Quality Up When AI Writes the Code

kanfu-panda — Thu, 03 Sep 2026 15:32:08 +0000

The last post covered how the loop runs on its own. The faster it runs, the sharper an old question gets: who vouches for the quality of what the AI produces? It doesn't get tired. In one afternoon it can write more code than a person can review in days. This post is about how I handle that in pdlc: not with one gate, but with a chain of seven links.

Why quality matters more when AI writes the code

Code quality used to rest on two things: the person writing it had a feel for whether it was right, and there wasn't so much of it that reviewers couldn't keep up. AI removes both at once.

It has no "feel for whether it's right." Ask an AI to grade its own work and it grades generously. It isn't lying; it genuinely thinks it did fine. That's why in pdlc the model's self-check is recorded in its own column and never feeds into any stop-or-continue decision.

The volume changed too. The unattended run from the last post finished a three-phase iteration in one afternoon: four backend API groups, three frontend pages, a full set of notification rules. That used to be days of work. Output sped up; "is this correct?" did not. Same eyes, same hours.

That gap is the risk. The faster you go, the further a mistake travels before anyone notices. So quality assurance isn't the thing slowing you down; it's the brakes and steering that make the speed usable. And it clearly can't be a human reading every line, because that hands back the time you just saved.

The short version: seven links, one chain

I split quality into seven links:

Requirements → Design → TDD → Implementation → Unit tests → E2E → Review by a different AI

The first two are written by AI, reviewed by AI, and checked once by a human at the end. The middle four are enforced by machine with no room for argument: TDD sets the red light, implementation is judged by exit codes, unit tests have to be plentiful, E2E guards only the core flows. The last link hands review to a different AI. The links are in series, not in parallel: if one fails, the guarantees of the ones before it are worth less. Get the requirements wrong and the strictest testing only builds the wrong thing more solidly.

Here they are in order.

Links 1 and 2: requirements and design. AI writes, AI reviews, a human checks

Counting requirements and design as quality control might seem odd, but they sit furthest upstream: they decide what every test after them is actually verifying.

Both documents are written by AI. The PRD stage has an eight-point self-check: is the background and goal clear, are there enough user stories, are the acceptance criteria measurable, does the feature list carry priorities, and so on. Fail the self-check and you don't move to the next stage. That last item looks the least important; by the time we get to false greens you'll see it's the one that bites.

Once written, a different AI reviews it first, and a human checks it last. The order matters. If a human had to write and proofread requirements and design from scratch, the faster the AI produced, the more the human would be the bottleneck, which is the gap we started with. The human's job is to check, not to execute.

But that check can't be skipped. Whether to build it, where the boundaries are, how to split it: those are judgment calls, and no command returns an exit code for them. That's why the autonomous loop from post 5 never touches these two links and only takes over TDD → implement → review. What a machine can detect goes to the machine; what it can't stays with a person.

Link 3: TDD. Write the failing tests first

Before any code, write a batch of tests that are guaranteed to fail. This isn't "we recommend writing tests first"; it's a hard requirement. And it buys something concrete: from this moment on, "is it done?" has an answer that doesn't depend on the model. Run the tests. Exit code 0 means done; anything else means not done.

This gate only holds if the test-commands.yml from the last post is in place. The verdict comes entirely from running commands. The model saying "I think it's good" doesn't count here.

Link 4: implementation. Judged by exit codes only

Now the code gets written. People assume this step can't be controlled: the AI writes it, and you can't watch every line. In fact it's the most tightly controlled step, because there's a check on the way in and another on the way out.

The way in checks one thing: the relevant tests must exist, and they must be red right now. This is one of pdlc's iron rules. If no tests are found, the implement command refuses to run and sends you back to TDD. "I'll write the code first and add tests later" isn't accepted.

Writing the code has one rule: the minimum code that turns the tests green, then refactor under their protection. The rule targets the laziest route an AI can take. When a test fails, editing the test is always easier than fixing the code. So the implementation stage isn't allowed to touch test files, and pdlc's automated acceptance suite has an assertion for exactly that: a modified test file is an automatic fail.

The way out has three checks: unit tests, coverage, lint. All three run real commands and read exit codes. Lint means zero warnings, not "fewer warnings than last time." The results go into the state file, and pdlc is explicit that these three fields may only hold command exit codes; the model's own assessment can't stand in for them. One failure and the stage isn't complete, and the flow doesn't advance.

Getting through that door isn't the end. The code goes to review next, and review has its own entry condition: if the tests aren't fully green, review doesn't start. Between implementation and review sit the next two links.

Link 5: plenty of unit tests, but they only prove the parts

With those two gates in place, the next job is building up the unit tests. One of my larger projects has over 4,000 unit tests and 90%+ coverage. But at that scale I'm also clearer about their limit: unit tests prove each part is correct on its own. That's all they prove.

There's a number people treat as insurance: coverage. It measures "this line was executed," not "this logic is correct." This test maxes out a function's coverage:

it('calculates order total', () => {
  expect(calcTotal(order)).toBeDefined();
});

The function ran, the branches ran, the report shows green. Whether the total is right, this test says nothing. Nobody is cheating here; coverage can only see execution, never assertions. The more you use it as an acceptance criterion, the more it drifts toward "make the number look good."

So I still write 90%, but what it proves is "the tests are spread wide," not "the quality is high." For that, you need the next link.

Link 6: E2E for the core flows

The same project has just over a hundred E2E tests for its core business flows. Four thousand to a hundred: the ratio itself tells you how the work is divided.

Production incidents are rarely one function computing the wrong value. Usually it's several individually correct parts that don't fit together: state didn't get passed, the order was wrong, the two sides read a boundary differently. Unit tests can't see this by design. They mock the dependencies away, and the problem lives between the dependencies.

So the core flows need E2E. I use Playwright driving Chrome against real pages: actually click through, actually wait for the API, actually check what rendered. It's slow and flakier, but it's the only thing that answers "does this flow still work today?"

/pdlc-quality checks E2E bluntly: every core flow has to map to a test in the mapping file, and that test has to show as passed in this run's actual results. One missing is red. "I think another test already covers that flow" isn't allowed to fill the gap; that's exactly the subjective judgment being removed.

Link 7: a different AI reviews every stage

The last link is review, and it happens more than once: requirements review, design review, code review, each its own gate.

The key word is different. As noted at the start, an AI grades itself generously, and the AI that just designed something and is then asked to review it is no exception. So I start each review separately: a new session, a subagent running a different AI, sometimes a different model. A reviewer with clean context sees what the author can't. The author's mental footnotes ("I considered that, here's why") don't exist in the new session, so whatever the design document actually fails to say finally shows.

Code review is the most detailed of the three. It checks the implementation against the design document item by item: do the API parameters and return shapes match, is error handling consistent, is there string-built SQL, are there missing auth checks, list endpoints without pagination, N+1 queries. What it can fix on the spot, it fixes. What it can't, such as architectural trade-offs or disputes about business logic, goes into the report marked for a human.

The reviewer is still an AI, not a person. Human time shouldn't go to "read the whole thing and look for problems"; an AI can do that. People handle only the few points it reports and isn't sure about. When review hits something that needs a human decision, pdlc stops and writes blocked. The "three config fields with no backend consumer" case from post 5 was caught exactly this way.

Seven links in place. Now guard against false greens

Chain complete, report all green: can you trust it? Not yet. The dangerous state was never red; red is at least honest. The dangerous state is a false green: everything looks fine while something underneath has already gone wrong.

There are two kinds, and neither is fixed by trying harder.

One: the list rots. The E2E coverage matrix compares against a "core flows list," and someone has to remember to update the list. Add a new core flow, forget to add it to the list, and the matrix stays green. It has turned "we don't know" into "we've covered it." That's worse than no check at all, because it comes with a green report that lets you keep being wrong in comfort. The fix is a forced reconciliation against the PRD on every run: in the PRD but not on the list means red, directly.

Two: "can't be judged" gets read as "no problem." Remember the least impressive item on the PRD self-check, that feature lists must carry priorities? The reconciliation keys off those P0/P1 marks. If a PRD never had them, extraction yields an empty set; compare that to the list and there's zero drift, so the report says "reconciliation passed." What actually happened is that the entire PRD never entered the check. Old PRDs are the usual victims, and old PRDs are exactly the ones behind the flows already in production.

So the rule changed: any PRD that skipped reconciliation for lack of priority marks must be listed separately as a warning, and the reconciliation item can't be marked passed, only "⚠️ no drift, but N PRDs could not be judged." It's the same principle as post 3's "no command to run means leave the cell empty, never fill in pass": if you can't measure it, write "not measured," and never let a blank pose as green.

What this doesn't catch

Seven links plus false-green guards still leave things out of reach.

If the requirements themselves are wrong, it's green anyway. The chain guarantees "what you meant to build was built solidly," not "this was the right thing to build."

It doesn't guarantee you actually set everything up. I have my own counterexample: a smaller project where unit tests and E2E both run, but coverage tooling was never configured. With a link missing, you don't get to say "quality is assured." Installing pdlc doesn't make you compliant; it lists what needs doing.

A human still signs off. /pdlc-quality only turns measured data into a report you can verify. It doesn't rule on pass or fail; whether to ship is a person's call. If the party writing the code is also the party ruling on it, everything that put the machine in charge of the verdict is pointless.

What this buys

Back to the gap from the start: AI made output faster and judgment didn't keep up. What these seven links do, in the end, is speed up judgment until it keeps pace.

For me personally, the result isn't "no bugs"; nobody can promise that. The result is I'm willing to let it run by itself. That unattended afternoon in the last post finished a three-phase iteration with me stepping in three times. Not luck: I know a mistake will get stopped at some link instead of waiting for a user in production to find it.

The AI will still make the mistakes it was going to make. What the chain does is bring them into the open early, while each one is still a bug and cheap to fix, not after it has become an incident.

Next time, a change of direction: visibility. How to record dependencies between features, how to tell what a change will touch, whether you can see the state of the project at a glance, and how to keep retrospectives around.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

The repo: https://github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

This seven-link setup is what I've arrived at on my own projects; it won't fit everyone. If you run a leaner combination, or think one of these links can go, I'd like to hear about it in the comments.

How pdlc-skills Runs Unattended

kanfu-panda — Mon, 31 Aug 2026 14:17:05 +0000

The last post got the first feature through. The next problem shows up fast: it stops at every stage waiting for your nod, so you're still parked in front of the screen. Can it go round after round on its own while you do something else? It can. But "running on its own" and "asking you at every step" are further apart than they look.

That run wasn't a loop at all

I've run a full loop on my own machine before, and it went smoothly — 60-odd PRs pushed through in one stretch, and it never once turned around to ask me something. So when I ran it again on a different machine, something felt off almost immediately.

That time I'd asked the AI to "advance through the stages in a loop" inside a single session. It was moving forward, all right, but it came back to me at every step: is this design OK? Should I keep going? Want me to continue?

What I said at the time was roughly: why is your loop different from the one I've been using? A normal loop doesn't turn around and ask me this stuff — it just keeps working until the job is done.

The problem wasn't that it asked. It's that everything it asked about was already settled. The PRD was settled, the design was settled, how the tests would be written was settled — and it still came back for confirmation. That kind of check-in does nothing but tie me to the chair. I can't go do anything else, because I don't know whether the next interruption is three minutes away or thirty.

On the surface it was looping. In practice I was the one jogging alongside it.

That's what made it click: there's exactly one line between a fake loop and a real one — who holds control of the loop.

It has nothing to do with how smart the model is, and nothing to do with whether the prompt says "please work autonomously, don't interrupt me." If control lives in the model's willingness, the loop is fake. If it lives in code, it's real.

One feature: one command is enough

The hard prerequisite first: PRD and design must be signed off by a human. Nothing enters the loop until the design is final.

The loop speeds up the TDD → implement → review convergence stretch. It does not speed up figuring out what to build. Whether this feature is worth doing, where its boundaries sit, how it splits — those are judgement calls, and no command can hand you an exit code for them.

Once that's settled, the rest is one command:

/pdlc-loop-run F20260825-XXXXXX

It picks up from whatever stage the feature is parked at and drives tdd → implement → review forward until review passes or it stops on a block. Each stage goes to a brand-new subagent; when that returns, the loop reads the state machine and decides whether to advance, stop, or hand back to you. Four steps by default.

This assumes the test-commands.yml from the last post is already in place. Stop decisions rest on exit codes from real command runs — no file, no commands to run. Skip that step and everything here spins in place.

What the command takes off your hands is exactly what I fumbled the first time I tried this by hand: the decision about whether to go one more round is taken away from the model. Three design points hold it up.

One: control flow is code, not something in the model's head. Each round asks the model two things only — which command comes next, and getting that step done. The answer to the first has to pass a whitelist that accepts five tokens and nothing else; a single extra word of explanation gets filtered out. Rambling gets the model nowhere, because nothing downstream reads it.

Two: every stage starts on clean context. The previous stage's hesitation, misreadings and self-inflicted detours don't carry over. Everything that has to survive across stages lives in the state file on disk — the one from post 3. Sessions can die; state doesn't.

Three: the stop decision reads a file, not an opinion. After each step the loop doesn't ask "do you think that passed?" — it reads last_phase_result.ok, the on-disk result of actually running the commands. Post 3 covered the two slots in that file; the stop decision uses only the one that holds real run results.

A dozen features: now you want an external script

/pdlc-loop-run runs inside the plugin, which suits one feature's short convergence. You can also write your own bash loop — every round gets a genuinely separate process, so context isolation is stricter and long runs hold up better — but running one feature point that way isn't worth much on its own: it does the same job as /pdlc-loop-run with a different process boundary.

The script's real place is one layer out. Post 3 sketched the two-level structure: split the work into N reasonably independent feature points, and have the outer layer start a loop for each, every one in its own worktree. The outer layer starts loops, collects results and queues the next batch — it doesn't push any single feature through its stages. What this post adds is how that outer layer is arranged: batched by dependency.

An earlier project of mine had something like a dozen feature points, and I ran them in three batches: foundation first, then the ones other work depends on, then everything mutually independent all at once. Each batch runs in parallel internally; when a batch finishes I check it, then the next batch starts, until the whole set has converged.

The order can't be flipped. Without the foundation everything after it rests on nothing; until the depended-upon work is done, whatever depends on it just waits. That last batch waits on nobody, so opening it all at once is the cheapest — feature IDs use date-plus-timestamp precisely so parallel runs don't collide.

To be clear: this batching layer is mine, not something pdlc provides. What pdlc gives you is "how one feature point drives itself to done," plus the /pdlc-relate dependency graph to see who depends on whom. How to split the batches, and how many go in each, stays a judgement call — and stays outside the loop.

Four guardrails, and I've watched every one of them work

Anyone can write guardrails into a doc. What's worth looking at is whether they've ever actually fired.

① Hard budget: `--max-budget-usd` per round

Put a spend ceiling on each round's process; hit it and the process is killed outright, no negotiation. This one is required for the external-script form.

It fired twice in a single run. I set the first round's ceiling at 5 and implementation got cut off partway; I checked the half-finished work on disk, confirmed it could be resumed, raised the ceiling to 8 and ran again — capped again; 12 finally got it through.

The thing worth saying about being cut off is this: what's on disk is intact. The documents landed, the state machine kept its ledger, and what I lost was "this round didn't finish," not "start over." Writing to disk plus keeping a ledger is what turns a blunt process kill into a pause you can resume from.

One honest note so those numbers don't get misread: 5, 8 and 12 are ceilings I set per round, not what I actually paid. I'm on a subscription billed by weekly volume, and per-token prices differ between vendors anyway. Treat those three as a rough sense of scale, not a price list — if you want real cost, look at token consumption and estimate it against your own vendor's published pricing.

② and ④: stop when it's not ok, stop when the steps run out

fail-stop covers the failure that's easiest to miss: a failed stage being treated as "done" by the next round. Once that happens, every later round rests on a false premise, and the further it runs the worse it gets — all with a green light on.

The step ceiling guards against oscillation: break it, fix it, break it again, every round looking like work while nothing moves. Four steps by default = three convergence stages plus one for slack. I set it to 1 once, conservatively, and it stopped exactly as promised.

③ blocked escalation: it really did stop when it should have

If review turns up something that needs a product decision, it writes blocked into the state machine, stops, and waits for a person.

The time this one fired is what convinced me the whole thing was trustworthy.

During review it found that the three config fields added that round had no consumer anywhere in the backend. The code was correct and the tests were green — this wasn't a bug, it was a product-level gap: should the fields be cut, or was the pipeline left unfinished? That's not a call the AI gets to make for me.

It didn't guess, and it didn't quietly delete the fields to keep the tests green — it wrote blocked, stopped, and handed the question back. I decided to keep the fields and finish the pipeline, then let it continue. The follow-up surprised me: on the re-review it also fixed 2 genuine bugs in that pipeline implementation.

It stopped where it should have, and it checked what it should have. That's what I wanted from it.

What that run produced

The work was a three-phase iteration on a console project: 4 backend endpoint groups, 3 frontend pages, plus a notification ruleset. TDD → implement → review ran unattended end to end, with 301 tests passing and coverage above 87%.

Human involvement came to three moments total: two verification calls when extending the budget, plus the one product decision at the block.

That's an afternoon's worth of work, and I don't want to make it sound bigger than it was. But during the loop it was completely silent toward me — what I came back to wasn't a queue of "shall I do the next one?" but a terminal state. It isn't that it runs fast. It's that it doesn't need me present.

Where the line between human and machine sits

The test hasn't changed since post 2: only hand the loop what can find its own errors. Draw that line and two things never get handed over:

Figuring out what to build (human decision required). PRD and design have to clear a human. That's a precondition for entering the loop, not a suggestion.
Shipping. The loop's terminal state is review-complete; it stops there and a person decides whether to ship. --autonomous has no effect on ship or deploy — once it's out, it's out.

That marks off which work can be handed over. There's a companion question: once it's handed over, what keeps it from going off the rails?

When post 1 covered prompt engineering, I gave that layer a ceiling: it's a soft constraint, the model may not fully follow you, and you may not notice at the time. Back then it was just a principle. This run gave it a concrete instance.

Writing "go easy, watch the consumption" into a prompt is easy, but it belongs to the prompt layer — it can steer, it can't guarantee. --max-budget-usd belongs to the process layer; it doesn't read what you wrote, it just cuts at the ceiling. Both overruns on this run were stopped by the latter, not talked down by the former.

Anything that steers but doesn't guarantee eventually has to move up a layer. This time it moved to a process argument.

Next up

If this post leaves you one thing, I'd like it to be this: to tell a real loop from a fake one, look at one thing only — whether the control flow lives in code or in the model's willingness. A loop that turns around to ask you isn't a loop.

Next post is about quality: the pipeline runs fast and unattended, so why should anyone trust what comes out of it? What the red-test gate, the review gate and coverage each hold back — and what they still don't catch together.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

The repo: https://github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

I wrote these four guardrails straight off the record of that run, including the parts where it got cut off and the part where it got stuck. If it left you thinking "all right, this can actually be trusted," let me know. And if you've run loops yourself — smooth ones or crooked ones — the comments are open — happy to talk it through.

Getting pdlc-skills Running in Your Own Project

kanfu-panda — Sun, 30 Aug 2026 01:26:24 +0000

The first three posts were blueprints: what each layer is, where it lands, how they interlock. This one turns the other way — putting the blueprint onto your own project. By the end you should be able to install it, know which command to start from, and get one feature through. There's one step in the middle that gets skipped constantly; I'll pull it out on its own, because skipping it makes the whole design from last post collapse.

That covers most of the theory. Now let's look at how pdlc-skills actually runs inside a real project.

A lot of people have the same question first: do I need to backfill the tests? Write all the docs? If it's a codebase that's been running for two or three years, piled high, that nobody quite dares touch — does onboarding mean paying off the technical debt on day one?

Here's the answer up front: none of that. Installing is one line, about a minute.

What will actually stall you is something else — the "so now what" right after install. The first project I onboarded, I sat staring at a screen full of commands starting with /pdlc-, genuinely unsure which one to type. This post answers that "so now what": which command to start from, and which step you absolutely cannot skip.

Installing: one line, two landing spots

# Global — every project on this machine can use it
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

# Project-scoped — only this one repo
curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --project /path/to/my-project

The first three posts always gave the global line, because it's the shortest and hardest to get wrong. Here's when project-scoped is worth it.

The only difference between the two is where it lands: ~/.claude/plugins/pdlc/ or <project>/.claude/plugins/pdlc/. What that buys you is real, though — project-scoped installs make the version travel with the repo. Someone else clones it and gets the same version you have; and when you've got several projects open at once, one global upgrade doesn't move all of them at the same time.

One person, one machine, not many projects? Go global, don't overthink it.

Confirm it actually took, two steps:

ls ~/.claude/plugins/pdlc/          # where the global install lands
ls <project>/.claude/plugins/pdlc/  # where the project-scoped one lands

Seeing skills/ references/ VERSION in there means you're good. Then type /pdlc- in Claude Code and the dropdown should list 38 commands. If it does, you're installed.

Which starting point are you?

38 commands spread out in front of you is intimidating, but you only need to recognize three the first time. Which one depends on what you're holding:

Your starting point	First command
Brand-new project, no code yet	`/pdlc-bootstrap`
Existing project, plenty of code	`/pdlc-adopt scan`
Already onboarded, day-to-day work	`/pdlc-feature`

Brand-new project uses /pdlc-bootstrap: give it one line of description and it picks a stack, generates the directory skeleton and draft documents. Good for when "I want to build an X" is still just an idea.

Existing project is where most people are, and it's the row I most want you to notice: the first command is /pdlc-adopt scan, and scan is entirely read-only — it surveys your stack, service layout, database, existing tests, and produces an onboarding report plus a health check, without changing a single byte.

I think that design is worth more than the feature itself. Letting AI touch a live legacy codebase makes anyone hesitate. So it splits "look" and "touch" into two commands: run scan, read the report, and only if you like what you see do you run /pdlc-adopt init to generate the baseline docs. The cost of trying it drops to zero.

Don't skip this: settle what "passing" means, first

This is the most important section in the post.

Last post covered the two boxes in the state file: the first box only takes exit codes from commands that really ran, and the model's self-assessment sits in a second box, never part of the stop decision.

Which raises a question — where do those commands come from?

The answer is /pdlc-test-setup. It does four things: detect the stack, verify each command really runs, write them into docs/00_standards/test-commands.yml, then scaffold the test directories and wire up local hooks.

The repo is blunt about what this step is for: the whole thing hinges on "checks only accept exit codes, never the model's self-assessment," but until this point nothing has helped you stand that file up — and without it, the entire objectivity chain is empty.

It carries one non-negotiable rule: every command written into that file must have been really run once, with the exit code seen with your own eyes. Guesses don't get written. The reasoning is the line I find most worth repeating —

A command that "looks right but doesn't run" is worse than leaving it empty.

Empty, and everything downstream knows this stage has nothing to judge, so it stays honestly empty. A fake command that doesn't run hands every stage false checks — and the report still comes out green. There's a mirror image of the same idea: the most dangerous "auto-fix" is quietly blanking a check that was standing but broke — the gate loosens on the spot and you can't tell.

So what happens if you skip it? No commands to run → the first box must be left empty by rule → the stop decision has nothing to stand on → what you thought was "objective verification" has been the model feeling good about itself the whole time. The foundation for last post's design is this one step.

Worth mentioning: this file goes stale — scripts get renamed, tooling gets replaced, sub-projects come and go. You don't have to watch it; downstream stages will tell you when a command won't run, and you run /pdlc-test-setup --refresh when you see the prompt.

Running your first feature

With the foundation in place, starting work takes one sentence:

/pdlc-feature add phone verification to login

From there it works down PRD → design → TDD → implementation → review, stopping and handing off at each stage. Fixing a bug is the same shape with /pdlc-fix; to see where things stand, /pdlc-status.

Day to day, those three are all you use. The other 35 are for when you want fine-grained control — rerun just the design stage, do a single code review, add a database design. Go find them then.

What shows up on disk, and what belongs in git

After one round, a batch of directories appears under docs/: requirements, design, testing, deployment, review each have their place, plus a docs/.pdlc-state/ holding one JSON per feature.

Those first ones are documents; committing them is your call. But one of them has to go in:

docs/.pdlc-state/ should be committed to git. Don't put it in .gitignore.

It looks like a cache — a dot-directory full of machine-read JSON, easy to wave off. It isn't a cache, it's the handoff. Change sessions, change machines, hand the work to someone else: the only thing that can say "this feature is at this stage, and the last one passed" is that directory. Not in git means losing your memory every time you reopen a session; on a team, nobody else can see where you are.

The repo calls it a "project delivery audit record." Treat it as an audit record and you stop wanting to ignore it.

Two rules for onboarding an existing project

If you came in from a legacy codebase, two rules are worth knowing on their own, because they decide whether this is realistic at all:

One: documents only, no code changes. Not a line of business code is touched during onboarding — it only reverse-generates baseline documents.

Two: incremental onboarding. Existing code is marked "baselined" wholesale, and only new features go through the full flow. You are not asked to clear the historical debt first.

The second one is the load-bearing rule. I've watched plenty of process tools die on day one: you onboard, it reports several hundred existing violations, and one look at that number is enough to make people quit. Fence the existing code off and govern only what's new — that's what gives the process a chance of surviving to day two.

When not to use it

Worth naming the boundary too. One-off scripts, throwaway demos, pure documentation repos — don't bother, the process doesn't pay for itself there. This is for projects that have to live a long time, get handed over, and answer for their quality.

The test is simple: will anyone still open this project three months from now? Yes, it's worth it. No, don't bother.

Walk it once

Compressed into a single list you can follow directly:

Install: curl … | bash -s -- --global (swap in --project <path> for multiple projects or team work)
Verify: ls ~/.claude/plugins/pdlc/, then type /pdlc- in Claude Code and check for the 38 commands
Know your starting point: new project /pdlc-bootstrap; existing project /pdlc-adopt scan for the report, then /pdlc-adopt init if you like it
Stand up the foundation: /pdlc-test-setup — don't skip this one, it decides whether every later "did it pass" is real or fake
Start work: /pdlc-feature <your one-line requirement>, with /pdlc-status any time to see where it is
Commit: include docs/.pdlc-state/

Step 4 is the only one that looks postponable and isn't. The rest just go in order.

Next up: can it keep going on its own?

Installed, started, foundation laid, first feature through — that's the line, end to end. If this post leaves you one thing, I'd like it to be this: settle what "passing" means before you start running — get that order backwards and every bit of automation afterwards is spinning in place.

Next is the heavy one in this series: it's installed and running, so can it go round after round on its own, without you watching? That post covers the convergence loop's mechanics, its contracts, and four non-negotiable guardrails — including the time I got caught myself: talking the model out of burning tokens didn't work, and what finally caught it was a hard budget.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh | bash -s -- --global

The repo: https://github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

I wrote this in the order I actually onboarded my own projects, and spent extra words on the steps that tripped me up. If you get through it, tell me; if you get stuck somewhere, tell me that too and I'll fold it into the next version.

How Do the Three Engineering Paradigms Interlock in pdlc-skills?

kanfu-panda — Sun, 23 Aug 2026 09:13:40 +0000

Last post ended with a yardstick: to tell whether a tool's three layers are genuinely joined, check whether they share one piece of state. This post cashes that in — the three layers never call each other, not once. They hand off through a single file on disk. There's also a side effect I didn't see coming: because that file is split per feature, the pipeline doesn't only run one line downward, it fans out sideways and runs several at the same time.

Last post placed each layer inside pdlc-skills: the rules every command shares are the prompt layer, the stretch that advances on its own is the loop layer, the stage order and the relation graph are the graph layer.

But knowing who governs what is not the same as knowing how they fit together.

Following that thought, the most direct move is to go into the code and find the call — where Graph calls Loop, where Loop calls the prompt layer. You won't find it. There is not one line of code in which these three layers reference each other.

So how do they end up working together?

The key is timing, not calling

The three layers don't need to know each other, because they don't act at the same moment.

Layer	When it acts	What it governs
Graph	at stage boundaries	whether you may enter the next step
Prompt	inside one invocation	what the model sees this time
Loop	between stages	whether another round is needed

An analogy: Graph checks tickets at the door, the prompt layer does the talking inside the hall, Loop stands outside counting how many sets are left. The three never speak to each other. They go by the same scoreboard.

That scoreboard is the file on disk.

Following one feature all the way through

Enough abstraction. Here's a real feature from start to convergence, one beat at a time.

Beat one: the opening move. A new feature has just been declared and there is nothing on disk yet. Exactly one command can pick it up — write the requirements. Why? Because every other command declares which prior document it needs: design needs requirements, tests need design, and not one of those preconditions is satisfied. This isn't advice to "write requirements first," it's that without the prior artifact you cannot get through the door. That's Graph doing its job, and its job is only "do I let you in."

Beat two: doing the work. Once you're through the door, Graph steps off and the floor belongs to the prompt layer. In this one invocation, the model sees more than the command's own text — it also sees the full set of rules shared by every command: artifacts must land on disk, self-check before handing off, fix once and don't recurse. Those rules live in one place and expand in at call time, rather than being copied into each command.

What comes out isn't free-form prose either. The filename, the directory, the sections — all fixed; and the document carries a small identity header at the top saying which feature it belongs to, which stage it's in, and which document came before it. I won't unpack the format here; what matters is what it buys you: the artifact carries its own coordinates, so you can walk backwards from it all the way to the original requirement.

Beat three: closing out by writing to disk. This is the critical beat. Finishing the main work isn't the end of it — the command has to record a line in that file: I've finished this stretch, here's how it went, here's who picks it up next. The file sits on disk, one per feature.

Beat four: the stop decision. Only now does the loop appear, and it reads nothing but that file — not the code, not the artifacts, not the chat log. It reads and emits one result: which command runs next, or "done," or "blocked." The outer script takes that result, runs the next command, and we're back at beat three.

Once review is complete the loop stops, emits "done," and waits for a human. Shipping and deploying are never inside the loop — once it's out, you can't pull it back, and what it touches is real users in production.

So the whole chain has exactly three handoffs, and what crosses each one is a name, not a call:

what Graph hands the invocation: "here's the stretch you're on";
what the invocation hands the disk: "I'm done, here's how it went";
what the disk hands the loop: "keep going or not."

None of the three ever touches another.

The one design in that file that matters most

What was actually run and what the model says about itself go in two separate boxes.

The first box takes only results from commands that really ran: did tests pass, is coverage high enough, is lint clean — all booleans translated from exit codes. If a stage has no command to run at all (requirements and design produce documents only), the box stays empty; you may not fill in "passed" because "I feel this went well."

The second box is the model's own self-check, recording only how many items failed. Reference only. Never part of the stop decision.

Where's the difference? The loop's stop decision reads the first box and nothing else. Which means the model's self-assessment is excluded from the stop path at the level of the data structure, not by a line asking it to please report honestly. Whatever it writes in the second box cannot change whether this round stops.

That's what "the three layers share one piece of state," from last post, actually comes down to.

The real loop has two levels

Time to admit something: the loop drawn above is only the inner loop.

When I actually put this to work, the shape looks like this —

Lead agent: overall design → split into N mutually independent features
    ↓
Outer script: start one loop per feature
    ↓
Inner loop × N (each on its own feature)   ← running at the same time
    ↓
Each stops at "review complete" or "blocked" → a human collects the results and decides on shipping

A lead agent does the overall design and splits the work into a set of mutually independent features. The outer script starts an inner loop per feature. Those loops run forward in parallel, each stopping at its own endpoint. Finally a human gathers up the N results.

What makes it safe to run them at the same time? The precondition is that what you split out really is relatively independent features — no dependencies between them, or there's no parallelism to speak of. Given that, the state files are split per feature too: one feature, one file, no cross-dependency.

Feature IDs use "date + hours-minutes-seconds" rather than the day's sequence number. The reason spelled out in the repo: when several people or several AIs start work at the same time, each one grabbing "today's highest number plus one" is guaranteed to collide, and colliding state files with the same name have to be renumbered by hand. Switch to the timestamp of the moment of creation and independent copies almost never collide. This ID format was built for parallelism from the start — I just didn't think of it as a piece of design at the time, only as a small trick against collisions.

The code has to be isolated too: each feature's inner loop runs in its own git worktree, out of everyone's way, with artifacts going through separate PRs.

So why must the split stay with a human, or with the lead agent? Last post gave the test: hand the loop whatever can find its own errors, keep the rest with people. "How many features should this batch of requirements split into, and which depend on which" — get it wrong and no command reports an error. It's a judgment call, not a check. So it lives outside the loop.

The two levels also end differently: the inner loop ends at review complete, the outer one ends when all N have converged. And shipping remains the single human gate — no matter how many ran at once, the person is still the one who presses it.

I've run this for real on a command-line tool project of my own. How to get it running, how the guardrails are set, what an overnight run actually produces — later posts cover that. This one only draws the shape.

Next up: getting it running in your own project

If this post leaves you with one line, I'd like it to be this: the three layers interlock not because they call each other, but because they write into different boxes of the same file.

The interface is a name, not a function — which is why changing one layer doesn't ripple into another, and why this pipeline can be copied sideways several times over.

I deliberately didn't drill down here: which fields that state file actually has, how the loop's guardrails and limits are set, how parallel runs are closed out — all of that is for later posts. Get the shape clear first, then look at the parts.

That covers it: what the three layers are, where each one lands, and how they interlock — three posts. Next post turns in a different direction: in your own project, how to install it, how to start, and how to bring an existing codebase in — from this post's blueprint to the first command that actually runs in your terminal.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --global

The repo: https://github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

That two-level diagram is how I actually run this; it lived only in my head until I drew it. If it gave you a concrete picture, a reaction helps. And if someone near you is working out how to get AI to do several things at once, pass it along.

Why Does pdlc-skills Fit All Three Engineering Paradigms So Naturally?

kanfu-panda — Thu, 13 Aug 2026 22:56:54 +0000

Once the three concepts are sorted out, the next question is the interesting one: is there anything real where all three layers grew in together? This post holds one up against them — pdlc-skills, the thing I've been building. Conclusion first: the fit is a coincidence. But there's a reason behind the coincidence, and that reason is what this post is about.

Last time we separated three terms that get mixed up constantly:

prompt engineering governs how you talk to the model this one time;
loop engineering governs how many rounds a thing repeats and what condition stops it;
graph engineering governs which steps along the path can't be skipped.

They're not on the same level. It isn't a choice of one — they stack.

Which raises the obvious question: all three sound reasonable, but is there anything real where all three layers grew in together?

Let's hold one up against them — pdlc-skills, the thing I've been building.

What is pdlc-skills?

It's a Claude Code plugin, and what it does fits in one line: it turns AI-written code from something you chatted about into something that lands on disk.

Install it and you get 38 slash commands, one per stage of the workflow. The one you'll use most is /pdlc-feature — start a new feature with it and the AI works down the line: PRD → design → TDD → implementation → review → ship, stopping to hand off at each stage.

Three things separate it from "hey, build me this feature":

Artifacts must land on disk. PRD, design, review notes are real files under docs/, not a passage in a chat transcript.
Every feature carries state. Which stage it's at, whether the last one passed — all recorded on disk. Pick it up in a new session and it knows where it is.
Tests must be red first. No failing test, no implementation. That's a hard gate, not a suggestion.

MIT licensed. It's most complete on Claude Code; the same methodology runs on other AI coding tools through adapters.

Its origins are unremarkable

I didn't design these three layers in. I hadn't even heard the terms "loop engineering" or "graph engineering" when I built it.

It just follows the product development lifecycle that software engineering already had. Requirements, design, tests, implementation, review, ship — that flow has been lying around the industry for decades, and there's nothing new in it. All I did was translate it for the AI: what each stage does, what it produces, what counts as passing, written out as commands, so the AI works down the flow instead of wherever its attention lands.

One rule came with it: every stage has to write something to disk.

PRDs go to docs/01_requirements/
Designs go to docs/02_design/
Review notes go to docs/07_reviews/
Each feature also gets its own state file

All plain text. You can open any of it, and you can git diff exactly what the AI did this round.

Then these new terms started circulating. I held them up against what I'd built and found matches everywhere — not because I built toward them, but because it had grown that way on its own.

So let's go layer by layer, in order: prompt, loop, graph.

🔵 Prompt layer: matches "one copy of the spec"

What it corresponds to in the flow. Software engineering has an old rule: there's one copy of the spec, not one version here and a different one there. Applied to pdlc, that means the rules every command has to honor — artifacts land on disk, self-check before handoff, repair only once — can't be written out separately inside each command.

How it's actually done. Common rules are pulled into fragments and expanded into each skill at build time. Currently that's 13 fragments compiled into 36 of the 38 skills (the two without them are pdlc-loop-next and pdlc-status — too light to share anything). The six invariants — files must land on disk, each stage must be recorded (appending to history), tests must be red first, self-check is mandatory, repair happens once, and state must advance (current_stage has to actually change, so an outer loop can't spin on a stale value) — live in one of those fragments. Change it once, everything changes.

Which layer it matches. Prompt engineering governs what the model sees this time. Nothing about that changed here — it's just managed the way you'd manage code: extract the common part, expand at build time, single source of truth.

The new term is prompt engineering; the old rule is single source of truth. Same thing, two vocabularies — that's coincidence number one.

🟢 Loop layer: matches the TDD red-light gate

What it corresponds to in the flow. TDD is old news in software engineering, and the rule is one line: write a failing test, then write the implementation, until the test goes green. pdlc copies that straight across — no red test, no implementation.

What that rule brings with it. Writing tests before implementation means "is it done" gets an answer that has nothing to do with the model: run it, exit code 0 means it passed, anything else means it didn't.

What makes that answer valuable is that it doesn't route through the model. Ask the model that wrote the code to grade its own code and it will grade generously and consistently — not because it's lying, but because it genuinely thinks the code is fine. So in pdlc the model's self-check is recorded separately, treated as a reference, and never as grounds for stopping.

Which is why this stretch can go to a loop: tdd → implement → review runs on its own until review passes. The PRD and design before it can't — whether to build this feature at all, how many modules to split it into, where the boundary goes, are judgment calls, and no command returns an exit code for those. Judgment calls stay with the human. That line is drawn clearly.

Which layer it matches. Loop engineering has a line you can treat as an axiom: a loop is a task with a check; a task without a check is just hope. TDD is exactly that check.

I do TDD because software engineering says test before you write, not to prepare a straightedge for a loop. But the straightedge was sitting right there — coincidence number two.

Guardrails, step limits, budgets — I'm saving those for post five.

🟣 Graph layer: matches stage gating and review

What it corresponds to in the flow. The phrase "lifecycle" carries order in it: requirements before design, design before implementation, review after implementation, ship after review. In software engineering that order isn't advice, it's discipline — the industry has already paid decades of tuition for skipping steps.

How it's actually done. Each stage writes its state to disk on completion; the next stage reads that state first and won't start unless the preconditions hold. No skipping tests to implement. No shipping without review.

Beyond the vertical order there's a horizontal layer: how features relate to each other. /pdlc-relate records those relationships explicitly, with six directed edge types — extends, depends on, supersedes, resolves, conflicts with, relates to. Then impact <feature-id> gives you the blast radius in one command: 🔴 directly depends on it, 🟡 one hop away, 🟢 already finished, ignore it.

And here's the honest part. That vertical line isn't a graph, strictly speaking. It's a linear pipeline with a few gates: no conditional branches, no parallel nodes, no rolling back to an arbitrary point — nearly nothing that makes a graph a graph. The thing that actually qualifies is the horizontal dependency graph: directed, traversable, cycle-detectable, and able to catch references pointing at features that don't exist.

Which layer it matches. So why does the vertical count as the graph layer at all? Because the essence of the graph layer isn't "drawn as a graph," it's negative constraint — declaring which paths are off limits. To reuse the line from last time: the track doesn't plan your trip, it just makes certain directions impossible.

Stage gates constrain order, the dependency graph constrains blast radius; both do the same job. And "advance by stage, review at key points" was written into the flow by software engineering a long time ago — coincidence number three.

Three coincidences stop being a coincidence

One match could be luck. Three matches is worth asking about.

My answer: these two things were solving the same set of problems all along.

The three paradigms are new vocabulary, distilled over the last couple of years out of AI agent practice. The software engineering flow was beaten into shape over decades by real projects. And the mistakes humans and AI make on engineering work overlap heavily — working wherever attention lands, keeping several copies of the spec, declaring something done without verifying it, changing one thing without knowing what else breaks. The rules the old flow set up to treat those still work when you translate them onto an AI.

So the constraints the new vocabulary describes had already been written down, in another language:

What the three paradigms say	What software engineering already required
Prompt engineering: unify the context	One copy of the spec, don't scatter it
Loop engineering: needs an objective check	Write the test before the implementation
Graph engineering: apply negative constraints	Advance by stage, review at key points

That's what "fits naturally" means here: I didn't fit three layers into it. The old flow already had those three layers — nobody had called them by these three names before.

There's one more thing, which the old flow didn't have and which showed up on its own during implementation: the three layers ended up sharing one thing — the state on disk.

The graph reads it to know which step it's on,
the loop reads it to know whether this round advanced anything,
the prompt reads it to get the context for this call.

Which hands you a ready-made test: to judge whether a tool's three layers are genuinely joined, check whether they share one state. Sharing is integration; each keeping its own is three mechanisms living in the same repository.

Next up: when does each one actually kick in?

If this post leaves you with one line, I'd like it to be this: if you want AI to do engineering work, you'll get further picking up the engineering process you already have than inventing a new framework. That process isn't new, but the ailments it treats, AI has too.

Now that we know where each layer landed, the next question is: in one real feature, when does each of them actually kick in? Next post follows a single feature from start to finish, marking the timeline for all three layers and how they hand off to each other.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --global

Project page: kanfu-panda.github.io/pdlc · Source: github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

If this gave you a concrete picture of how the three layers land, a reaction or a follow helps. And if someone near you is working out how to get AI to follow a process, pass it along.

Prompt Engineering, Loop Engineering, Graph Engineering: What Are They?

kanfu-panda — Sun, 09 Aug 2026 04:19:57 +0000

Prompt engineering, loop engineering, graph engineering — these three keep landing in the same comparison table, as if you had to pick one. But they don't operate at the same level. Sorting that out is worth more than mastering any one of them. This post isn't about any specific tool. It covers what each layer actually governs, where each one hits its ceiling, and ends with three questions that tell you which layer your problem belongs to.

Three terms, three separate origins

These three came from completely different places, so let's start there.

Prompt engineering got renamed somewhere along the way. Early on the discussion was about phrasing — what persona to assign, which magic words to use. Then people realized phrasing wasn't what decided the outcome; what the model got to see was. Hence the more accurate label going around now: context engineering.

Loop engineering spread through the community on the back of Ralph-style setups. The mechanics are almost disappointingly simple: a one-line while loop that feeds the same instruction to the model over and over, lets the tests decide right from wrong, and after enough rounds the version that passes acceptance simply surfaces.

Graph engineering arrived with orchestration frameworks like LangGraph, which argue for drawing an agent's execution path explicitly — who hands off to whom, whether you can go back, where it has to stop.

Three separate threads, eventually shoved into the same table for comparison. The table is exactly where things go wrong — these aren't the same kind of thing.

🧱 They aren't on the same level

The relationship isn't side-by-side. It's stacked:

Layer	What it governs	Granularity
Graph engineering	How paths are organized	Stage
Loop engineering	How iteration converges	Round
Prompt engineering	How a single exchange goes	Token

One thing has to be said right here, or you fall into the next trap: the stack being real doesn't mean every layer is required.

Once "the standard three-layer architecture" lodges in your head, every task starts looking like it needs all three. In practice, plenty of systems that work well have only one or two:

Shape	When it looks like this
Prompt only	One-shot classification, extraction, rewriting — any orchestration is a net loss
Prompt + Loop	Iterate against tests; the path was never drawn at all
Prompt + Graph	The path can be fully enumerated; no autonomous iteration needed
All three	Production-grade engineering workflows

Anthropic's principle in Building effective agents is a practical one: start with the simplest solution, and only add complexity when it demonstrably improves things.

So the right mental model isn't "a three-layer architecture." It's — three optional nested layers. Start at the bottom by default, and understand that going up costs you something.

🔍 Layer by layer: what each one actually governs

Four things per layer below: what it is, how it's done, one thing people get backwards, and where the ceiling is.

Prompt engineering: deciding what the model sees this time

It stopped being about "phrasing things nicely" a while ago. What you're really managing is which things the model gets to see this time, and which it doesn't.

The reason it evolved that way is straightforward: once a task spans multiple rounds of reasoning, a well-turned sentence stops being enough, and the job shifts to managing the whole context state — system instructions, tool definitions, external data, message history, all of it.

In practice there are only a handful of moves. The system prompt needs to sit at the right altitude: specific enough to actually steer behavior, without hard-coding every situation — rules that are too granular start contradicting each other the moment something unforeseen shows up, and rules that are too vague say nothing at all. Tool descriptions need to make clear what each tool is for; the more overlap between tools, the more often the model picks wrong. Agree on the output format up front so you're not writing regexes later. Give a diverse handful of examples rather than piling up edge cases.

What people get backwards: longer context isn't better. The fuller you pack it, the more the middle gets diluted — that's a real, measurable decay, not the model "not being smart enough." Attention is a budget, and where you spend it is a tradeoff, not a "more is safer" situation. Working out what the model doesn't need to see this time is often easier than working out what to say.

Ceiling: it's a soft constraint. The model may not follow you exactly, and you may not be able to tell at the time.

This layer's biggest strength and biggest problem are the same fact — one edited sentence takes effect immediately, which also means you're relying on the model's willingness.

Loop engineering: a task, plus one check

There's a line here you can treat as an axiom:

A loop is a task with a check. A task without a check is just hope.

Ralph's shape came up earlier: it's that one while line. But the real design isn't in the loop — it's in the files around it, three of them, each doing one job. A spec, stating what this project should end up being and what's off limits. A progress list, recording what's done and what's next. And one instruction, fed in verbatim every round, telling the model: read the other two first, then pick one thing and do it. The loop itself is trivial; getting those three files right is the hard part.

What people get backwards: the context is wiped clean every round — the model has no memory of what it did last time. That sounds like a defect. It's a feature. Amnesia guarantees every round starts from a clean slate, so a wrong interpretation from one round doesn't get carried the rest of the way. The price is that anything that has to survive across rounds must live on disk — that progress list isn't a note for humans, it's the model's only memory going into the next round.

Where the stop signal comes from: how does a loop know it's done? It needs a signal something can decide automatically — test exit codes, compiler output, type checks. "Looks fine to me" doesn't count, because you can't put that in a conditional.

How it typically crashes, two ways. One is spinning: every round the model feels like it did something, nothing actually moves, and tokens burn with nothing to show. The other is redoing work: it doesn't find what the last round already built, assumes it isn't there, and builds it again — like a contractor who doesn't see yesterday's pipe, breaks up the floor, and lays it a second time.

Ceiling: a loop with no verification signal is mass-producing garbage. And its failures are the hardest to catch — it keeps running, it's just heading the wrong way.

Graph engineering: two different things with the same name

There's an ambiguity to clear up first. "Graph" refers to two completely different things here:

Orchestration graphs: the LangGraph kind, drawing which path the flow takes
Knowledge graphs: the GraphRAG / code-relationship kind, drawing how entities relate

Same word, different objects. This post is about the first one. The second gets its own post — number seven in this series.

What an orchestration graph does is move "what order does this work go in" out of your head and onto paper: who picks up whose output, which step can be sent back, which step has to stop and wait for a human to nod.

There are five common shapes, each fitting a class of work:

Sequential: one step after another. Writing code works this way — design first, then tests, then the implementation.
Routing: classify first, then decide who handles it. Tickets come in, get sorted, refunds go down the refund path, outages down the outage path.
Parallel: independent pieces run at once, then get merged. Have the same diff reviewed separately for security, performance, and readability, then combine the notes.
Orchestrator with workers: one splits and assigns, several put their heads down and do it.
Evaluator-optimizer: run the output through a review; if it fails, send it back.

Real systems are basically these five in combination. You don't need to invent new ones.

Drawing the graph has two benefits people overlook. One is recoverability — every node can be checkpointed, so a crash resumes from the last checkpoint instead of the top. The other is auditability — afterwards you can explain why it took that path, which matters when someone's going to ask.

What people get backwards: it dictates which paths are off limits, not how to do the work. More on that below.

Ceiling: it can only express what you thought of in advance. Anything requiring judgment on the spot, anything you haven't seen before — the graph is useless. There's also a hidden cost: once drawn, the graph becomes a liability, and reality shifting means redrawing it. Redrawing costs a lot more than editing a sentence, so it's worth planning before you start.

🏠 The same thing, told as a renovation

Let's run all three through one analogy:

Concept	What it maps to in a renovation
Prompt engineering	How you tell the contractor what you want
Loop engineering	Do it → inspect → fails → redo → inspect again
Verification signal	The inspector's straightedge, spirit level, flood test
Graph engineering	The trade sequence (plumbing → waterproofing → flood test → tiling → carpentry → paint)
Human checkpoint	The owner showing up to sign off at key moments
Context wiped each round	A new contractor showing up every morning

Three sentences for the three personalities:

A prompt is the brief. "North-facing wall in the main bedroom, off-white, two coats, tape the edges." Costs nothing, works immediately — but the contractor may decide close enough is close enough, and you won't catch it on the spot.

A loop is the redo mechanism. Briefing alone doesn't get you there; you need inspection. The key word isn't "redo," it's the straightedge — redoing without one is just doing it twice.

A graph is the trade sequence. It won't tell you what color the wall should be. It just makes "tiling before waterproofing" impossible as a matter of process.

One line for how the three divide the work: sequence rules out what you can't do, redoing forces it up to standard, the brief decides how it actually gets done.

⚖️ Three personalities, three ways to crash

	Prompt engineering	Loop engineering	Graph engineering
Who's in control	The model	The model (you only set the stop condition)	You (you draw the path, the model fills it in)
Determinism	Low	Lowest	High
Up-front investment	Minimal	Low, but you need a verification setup first	High
Unit cost	1x	4x, 15x for multi-agent	2–3x, but fewer detours
Debuggability	Good	Worst	Best
Typical failure	The model doesn't comply	Drifts and nobody notices	Wrong graph, or too rigid

A note on the cost row: roughly 4x for agents and 15x for multi-agent come from Anthropic's public write-up; the 2–3x for graphs is a rough figure circulating in public material. These are order-of-magnitude references, not measurements.

The row worth sitting with is the last one. The three failure modes are nothing alike: a prompt failure you can see — it didn't comply, it's right there. A loop failure you can't see — it's still running, just pointed the wrong way. A graph failure you can't change — the graph is set and reality moved.

The latter two are far harder to deal with, and they're precisely the new problems you acquire by adding layers. That's what "going up costs you something" means in concrete terms.

🚧 Two things people get backwards

A graph doesn't plan; it constrains negatively

It's easy to read the stack as a chain of command: graph plans, loop executes, prompt implements. But the graph says nothing about how to do the work. All it declares is "you don't skip tests and go straight to implementation." Which modules this design splits into, which file to write first — that's the actual planning, and it happens in the two layers below.

Another way to put it:

The track decides where you can go and where you have to stop — it has no opinion on why you left the house.
The engine only pushes forward, until the terminus or a stop signal.
The steering wheel decides how you actually move, within the room the track allows.

The track never plans your trip for you. It just makes "driving off to the side" impossible.

The higher the layer, the weaker it is

The "top layer / bottom layer" framing makes it feel like the top matters more. It's the opposite — more control means less expressive power. A graph can only express what you thought of in advance, and the moment reality exceeds what the graph imagined, it can't help at all.

Going one level deeper: none of these three layers implements anything. The model does the work. The three layers are just three ways of shaping its behavior — graph through structure, loop through repetition and verification, prompt through language.

Which means: as models get stronger, the upper two layers matter less. What all this is worth is, to some degree, a function of what models currently lack.

✅ Three questions for picking a layer

If you take one thing from this post, let it be these three questions:

Question one: if it's wrong, can a machine catch it automatically?

Yes → use a loop. Tests, compilers, type systems all work as the straightedge.
No → don't, however tempting it looks. A loop without a verification signal is mass-producing garbage.

The test is plain enough: can "it's correct" be written as a command that exits with a status code? If you can write it, you can loop. If you can't, don't.

Question two: can I draw the flowchart right now?

Yes, and this flow needs to be reused, audited, and have human checkpoints → use a graph.
No → don't force it.

By "can't draw it" I mean the kind of work where you can't even say how many steps it takes: maybe three, maybe twenty rounds of back and forth, depending on what turns up. That kind of work should let the model judge as it goes; forcing a graph on it just boxes it in. Anthropic's guidance says the same thing — open-ended problems where the number of steps can't be predicted should go to an agent, not a fixed flow.

Note the question is "can I draw it now," not "could I draw it eventually." A graph only constrains anything if you thought it through first; one you patch as you go is just your mess in a new notation.

Question three: neither of the above?

Then use prompt engineering. That's not a compromise, it's the right answer. Wrapping a one-shot classification task in a loop and an orchestration graph only makes it slower, pricier, and harder to debug.

Next up: is there something real where all three grew in together?

That's the concepts covered. One line to close on, and it runs through the rest of this series.

The prompt layer can only ask; it can't guarantee. You write "go easy on the tokens" and the model will probably comply — but when it blows past the limit, you can't stop it, because that sentence carries no force.

If you want a guarantee, you need a different kind of mechanism. A hard line, for instance: spend past this amount and it stops. That line doesn't negotiate with the model, and it doesn't care whether the model agrees.

So: if what you want is a guarantee, the prompt layer can't give it to you. It has to move up a level.

Next post is about something concrete — pdlc-skills, the thing I've been building, and why it lands on these three layers naturally.

Want to try it:

curl -fsSL https://raw.githubusercontent.com/kanfu-panda/pdlc-skills/main/install.sh \
  | bash -s -- --global

Project page: kanfu-panda.github.io/pdlc · Source: github.com/kanfu-panda/pdlc-skills

If it's useful, a star goes a long way ⭐

If this sorted the three terms out for you, a reaction or a follow helps. And if someone around you is tangled up in these words, pass it along.

I Built a Health-Check for My AI's Memory: It Diagnoses, It Never Operates

kanfu-panda — Sun, 09 Aug 2026 04:18:55 +0000

Last time, I gave the AI memory libraries across a few of my projects a thorough "weeding," and sorted the decay into six kinds of "weeds." But the more I weeded, the more certain I got: weeding by hand only treats the symptom. As long as the memory system itself has no self-checkup mechanism, the weeds grow right back. So at the end of that post I left myself an assignment — build a tool that runs the checkup automatically. This post is me turning it in.

Let me first say what the tool actually does, or the rest is just talk.

Think of it as a dedicated doctor for your memory library. You point it at a project's memory library, it scans the whole thing top to bottom, and lays out every problem it finds, one by one: this link is broken, that memory is in the wrong folder, these two entries look contradictory… and then it stops, and waits for you to decide what to do with each one.

I put "waits for you to decide" front and center on purpose, because it defines the tool's whole personality: it only looks and tells. It doesn't act.

🩺 It Only Looks — It Won't Act For You

Why design it this way? It goes back to the hardest lesson from last time: deleting memories is not something you hand entirely to an AI. It can propose what to delete or merge, but the final call has to be a human's. What gets deleted is often a historical record, and an AI, going with the flow, can easily wipe out something important along with it.

So when I built the tool, I turned that lesson into a hard rule: nowhere in the program is there a single code path that changes or deletes your memory files on its own. It can scan, rank each problem by severity, even work out the fix for you and lay it on the table — but the actual "change" or "delete" keystroke has to be yours.

Put that way it sounds like a loss — I built a tool and cut off its most capable part. But it's exactly that restraint that lets me leave it running every day. Swap in a tool that touches my memory on its own initiative, and I wouldn't dare use it even once.

🔍 The Machine Catches "Hard Faults," Claude Reads "Meaning"

Now that we've covered what it won't do, let's talk about what it can spot. The problems it scans for come in two kinds, handled very differently.

One kind is a hard fault the machine can judge at a glance: the file a link points to doesn't exist, a memory is sitting in the wrong folder, a name breaks convention… These need no understanding of the content; a rule comparison settles it, and it won't misfire.

The other kind is far trickier. Take "are these two memories contradicting each other" — you can't judge that from the surface text; it has to actually read what each memory is saying. That kind of work needs a model that understands language. Handily, this tool is itself a Claude Code plugin, so at runtime there's a Claude sitting right next to it — a ready-made model that reads meaning, no need to wire in another.

So the hard faults go to a small local engine — it never touches the network, calls no model, and returns the exact same result every time for the same library; the judgments that need understanding go to the host Claude, the very model working alongside you. Split this way, the tool needs no API key at all, depends on no external service, and not one character of your memory ever leaves your machine.

Following that split, I laid the checks out in three layers, from the most certain to the most judgment-heavy:

Static checks (hard faults): the engine's mainstay, fast and precise — dead links (a name drifting from hyphen to underscore silently breaks the link), dangling index entries (listed in the index, but the file is gone), orphan memories (the file exists, but it's not in the index), missing fields, bad naming, wrong folder. All faults the machine spots at a glance without misfiring.
Educated guesses (leads): e.g. a memory that says "in progress" or "under review" and hasn't been touched in ages — most likely the task is long done and the status is just frozen there. This layer gives you leads, not verdicts.
Reading meaning (semantics): the two nastiest weeds from last time — a project re-copying a global rule (I call it a ghost copy), and a "false contradiction" where two entries look opposite but each governs its own scenario — take reading the content to judge. This layer goes to the host Claude; it reads and suggests, I make the call.

Once all three layers are done, the tool sorts the problems by severity into red / yellow / green and walks you through them one at a time: fix this dead link? add this orphan to the index? is this frozen status long over? It changes only what you tell it to change, and touches nothing you skip.

⏰ Remind Me On Time — But Don't Nag

A checkup alone isn't enough, because the biggest enemy of memory maintenance isn't "not knowing how to fix it" — it's plain forgetting to. Last time I said memory needs regular maintenance, but "regular" left to willpower is basically nothing.

So I gave the tool a reminder: whenever I start working, if the current project's memory library has gone too long without a checkup, it gently notes "🩺 N days since the last checkup."

But a reminder, overdone, becomes noise, and noise gets ignored. So I put two limits on it: at most once a day, not popping up on every session; and if it really bugs you, one command shuts it off.

📌 What It Can and Can't Do Right Now

Let me be concrete.

What it can do: six detectors, migration suggestions for old-format memories, and bilingual output — all working now. I ran it over the memory libraries of my own nine projects, one by one, and cleared out dead links, stale names, and frozen statuses in a single pass.

What it can't do (and this is a line I drew on purpose):

the judgments that need understanding still need a human nod; the tool only advises;
it will never change anything for you automatically;
for small or new libraries the payoff is limited — the real value is in libraries that have piled up over a long time.

The one thing a memory tool should never do is act on its own.

The tool itself is still just for my own use, but it's been written to open-source standards from the first line: full tests, clean history, docs in both Chinese and English. When and how to make it public, I'll decide once I've used it enough to trust it — so no link in this post, to save you a dead click.

💡 Looking Back: Three Takeaways

For any tool that "acts," think hard about its boundary first. The more irreversible the operation, the more dangerous a capable tool becomes. Making "never act on its own" a hard rule is exactly what lets me use it without worry.
When you build reminders or notifications, don't forget to leave an "off switch." We fixate on getting the message in front of the user and easily forget: a reminder that keeps nagging ends up ignored. A reminder you can turn off is one people actually read.
Be the first demanding user of the tool you build. Don't just run it symbolically — actually put it to work, and the misfires and blind spots start surfacing one by one.

Next: Let's Talk About the Loop

Memory — from building it, to weeding it, to this checkup tool — is where I'll leave it for now. Next time, a different topic: the loop — how to get an AI running on a steady rhythm on its own, keeping a repetitive job going without me standing over it.

If you're building a memory library for your AI too, or thinking about a few "never cross this line" rules for your own tools, I hope this was some help. If you found it useful, a like or a share with someone else wrestling with AI memory means a lot — every share is what keeps me writing.

AI Memory Grows Weeds: Why Timely Pruning Matters

kanfu-panda — Thu, 09 Jul 2026 23:40:25 +0000

Last time we talked about how to build a memory system for AI. But building is only the beginning—the longer a project runs, the more memory accumulates, and without cleanup, weeds quietly grow in it. This time, I gave the AI memory across several of my projects a systematic "weeding."

As a project moves forward, the memory gathered during AI collaboration keeps piling up. Each project's memory is like a dedicated notebook: while working, the AI jots down the pitfalls it hit and the rules we settled on. This does deepen its grasp of the project, but the notebook grows thicker and messier—and quite a few entries are long expired, though the AI still treats them as rules it must obey.

A real example. On one project, the AI immediately acted on an old memory. It read "an external call is already configured, use it directly," so it skipped the step where it should have re-verified and pushed straight ahead—and hit a wall. The catch: that memory was just a snapshot from a few weeks earlier, long invalid; yet from start to finish the AI never doubted it for a moment.

That made me realize: a wrong memory can be worse than no memory. With no memory, the AI will at least check honestly first; with a wrong one, it walks off course with full confidence. Once memory grows, it goes stale, gets tangled, contradicts itself—and someone has to clean it up in time, or the AI's efficiency can't really be counted on.

Two things I set out to do

One, seriously clean up the memory library of each project; two, take the chance to survey what kinds of "weeds" memory actually grows.

Neither has a shortcut—both need hands-on human work, deletion above all, which I would never fully hand to the AI. It can propose what to delete and what to merge, but the final call must be a person's. What gets deleted is often historical record, and once the AI gets careless it can wipe out something important along with it. Cleaning memory demands real caution.

But let me say it up front: manual weeding only treats the symptom. Weeds keep coming back because the memory system itself lacks certain mechanisms—pull them today, and they grow back in a while.

First, give the AI the "sleep" it lacks

To see why memory needs cleaning, it helps to look at how humans do it—through sleep.

There is solid science behind this. During sleep, especially deep sleep, the brain "replays" the day's experiences, gradually moving important memories from the hippocampus into the neocortex for archiving; the more important the content, the more often it is replayed, and the more firmly it sticks. At the same time, sleep actively "prunes" the unimportant and outdated, so the brain isn't stuffed with useless information.

The AI has no such automatic tidying. It only stacks memory downward, one entry after another, never going back to reorganize. So this time, I manually gave it that "sleep": I read through each project's memory once, checked it entry by entry, and did five things—merged duplicates, cut the expired, distilled scattered notes into one, linked the related, and the easiest to overlook: hunted for entries that contradict each other.

Six typical memory "weeds"

After systematically going through the memory libraries of several projects, I found that although the weeds differ in form across projects, they boil down to six typical patterns.

One, ghost copies. A global rule gets recorded again inside a specific project, but the AI has no "inheritance" mechanism. When the global rule is updated, these isolated copies can't sync, so an outdated instruction keeps taking effect.

Two, frozen state. Some memory records an in-progress state at a given moment (in development, under review). With no state-update mechanism, even after the task is long finished, the AI still treats it as unresolved and raises useless reminders in unrelated conversations.

Three, stale snapshots. The most dangerous kind. An expired memory not only loses reference value but also misleads the AI into taking wrong information as fact and confidently executing the wrong action.

Four, split context. Some entries are each accurate read alone, but only yield the right conclusion in a specific context. Because the linking note sits in another file, the AI easily misses it while retrieving, and takes things out of context.

Five, conclusion detached from reasoning. When underlying data changes after a bug fix, the old conclusion is merely overwritten by the new one, never explicitly marked obsolete. Since the memory system stores only conclusions, not the reasoning, it can't automatically spot and clear the related conclusions that quietly went invalid.

Six, structural disorder. This includes memory stored in the wrong directory, and silent broken links caused by inconsistent naming (hyphen versus underscore).

Reviewing these six, I reached a counterintuitive conclusion: most of these weeds don't come from being recorded wrong in the first place—they were recorded correctly, then rotted for lack of upkeep. The greatest hazard of a memory system isn't "recording wrong," it's "record and abandon."

One step where I deliberately held back

During cleanup, there was one step I deliberately held back on.

I had planned to merge three similar memories about a "cloud data trap" in one project into a single checklist. But halfway through, I realized the three map to three concrete business risks—duplicate reward payouts, missing leaderboard data, new users failing to be saved. Over-abstracting them into a single "watch the cloud fields" would erase these life-saving details.

Distilling knowledge matters, but over-distilling erases the exceptions. So I changed course: keep all three original memories, and only link them with a tag, so they "cluster together" rather than "boil into one pot."

The hardest part: reconciling memories that "look contradictory"

The most challenging part of the whole cleanup was reconciling logical conflicts.

For example, on retrieving data from an interface, one memory said "returns real data," another said "returns anonymous data." On checking, both were correct—only the trigger differs: automatic retrieval returns anonymous data, while a user's manual button tap returns the real thing.

For such seemingly contradictory memories, simply deleting one only loses information; the right move is to clearly delimit each one's applicable scope. Add that "branch condition" into the memory, and the conflict resolves itself.

This leads to a core takeaway from the review: the most dangerous thing in a memory system isn't "information being inconsistent," it's "information being inconsistent with no scope defined."

Why manual cleanup never finishes

By the later stage I understood: manual weeding alone can't fix the root. These weeds keep coming back because the system lacks three core mechanisms—without "inheritance," global rules get redundantly re-recorded; without "expiry," state-type memory is frozen forever; without "ownership and consistency checks," memory ends up misplaced and links break silently.

Was this cleanup worth it?

On return-on-effort: for small or new memory libraries, the payoff is limited; but for large, aging ones, the value is considerable—it clears out plenty of broken links, stale names, and frozen states.

Yet the real gain from this review isn't the short-term "tidiness," it's building a systematic understanding of how memory decays—and that understanding has long-term value.

Which memories are least likely to grow weeds

While checking, I also noticed that memories resistant to decay share one trait: they record "confirmed decisions and principles" (the rationale, the path, the hard limits), not "in-progress states." Conclusion-type memory is stable across time; state-type memory expires easily.

So when writing to memory, follow one principle: prefer recording "conclusions that won't expire," and avoid recording "states that will."

Three practical lessons

One, memory needs periodic maintenance. A memory library decays by nature; it should be restructured on a regular basis—merge, prune, distill, link, and reconcile conflicts—to keep it from steadily degrading.

Two, high-risk operations need a human in the loop. For irreversible acts like deletion and distillation, human review is a must; and clear out the expired and self-contradictory first, before wrong information misleads the system.

Three, the real fix is systemic. Manual cleanup is only a stopgap; the root solution is to build automatic inheritance, expiry, and consistency checks, so the library metabolizes on its own.

Next: a memory tool that "self-diagnoses"

Based on this review, the next direction is clear: build a memory-management tool with a "self-diagnosis" capability. It needs three core functions—trigger cleanup reminders on schedule, scan and diagnose memory layer by layer, and present the issues it finds in a structured way for a human to decide on. And on the final act, the system only advises; the decision to delete or merge always stays with the person.

This idea didn't come out of nowhere; it's the near-inevitable conclusion after a full review. Next, I plan to actually build it.

If you're also building a memory library for your AI, stay alert to memory's natural decay and the "weeds" it grows. If this review nudges you to look back at your own memory library, a follow, a like, or a share with peers exploring AI memory management would mean a lot.

DEV Community: kanfu-panda

How Are LLMs Trained?

What are the ways to train an LLM?

How are these methods used in stages?

Walking through one request: a leap-year function

Why has coding improved so fast?

What does this mean when you code with AI?

Is it the same with Codex or DeepSeek?

Summary

What Is an LLM, Really?

What does it do at each step?

How does one word become a whole function?

If it only predicts the next word, how can it write code?

Why does it follow instructions like an assistant?

What does this mean when you code with AI?

Is it the same with Codex or DeepSeek?

Summary

Running pdlc-skills on a Real Project: Three Features, Start to Release

Where this run started

How to split the work

Who does what

Running the loop

Time and output

What holds quality up

Where the loop stops helping

End of the series

How pdlc-skills Makes Progress, Change Impact, and Quality Trends Visible

Three tools, one data source

Where are we now: the statusline and /pdlc-status

What does a change touch: the relation graph

How did this stretch go: the retrospective

The limit: they only show what was recorded

Once you can see

Next post

How pdlc-skills Keeps Quality Up When AI Writes the Code

Why quality matters more when AI writes the code

The short version: seven links, one chain

Links 1 and 2: requirements and design. AI writes, AI reviews, a human checks

Link 3: TDD. Write the failing tests first

Link 4: implementation. Judged by exit codes only

Link 5: plenty of unit tests, but they only prove the parts

Link 6: E2E for the core flows

Link 7: a different AI reviews every stage

Seven links in place. Now guard against false greens

What this doesn't catch

What this buys

Next post

How pdlc-skills Runs Unattended

That run wasn't a loop at all

One feature: one command is enough

A dozen features: now you want an external script

Four guardrails, and I've watched every one of them work

① Hard budget: --max-budget-usd per round

② and ④: stop when it's not ok, stop when the steps run out

③ blocked escalation: it really did stop when it should have

What that run produced

Where the line between human and machine sits

Next up

Getting pdlc-skills Running in Your Own Project

Installing: one line, two landing spots

Which starting point are you?

Don't skip this: settle what "passing" means, first

Running your first feature

What shows up on disk, and what belongs in git

Two rules for onboarding an existing project

When not to use it

Walk it once

Next up: can it keep going on its own?

How Do the Three Engineering Paradigms Interlock in pdlc-skills?

The key is timing, not calling

Following one feature all the way through

The one design in that file that matters most

The real loop has two levels

Next up: getting it running in your own project

Why Does pdlc-skills Fit All Three Engineering Paradigms So Naturally?

What is pdlc-skills?

Its origins are unremarkable

🔵 Prompt layer: matches "one copy of the spec"

🟢 Loop layer: matches the TDD red-light gate

🟣 Graph layer: matches stage gating and review

① Hard budget: `--max-budget-usd` per round