What a document does well, this one tries to do in full. It is a reference: searchable, quotable, re-readable the night before you introduce the loop to your team. It works at your pace and in your timezone, it costs nothing to distribute, and it is stable — you can link to it in a design discussion or a decision record.

Some things, though, no document can do, however carefully written. They are properties of the medium, not gaps in the material. PAAD is something you practise, not a set of facts to learn. Reading that you should argue with an agent's plan is a different skill from doing it in a live session, with someone there to correct you halfway through. The examples here are necessarily generic or drawn from my own work, while the cases that decide whether any of this is worth adopting live in your codebase, under your constraints. When an agent behaves strangely — and it will — working through the strangeness together in real time is high-value and unrepeatable in prose. And a document cannot answer "but what about our situation," nor check whether it has been understood: "I read it, and I understand it" is invisible from the inside, which is a large part of why instructors exist.

Two further limits are organisational rather than individual. A methodology is a team property — five people reading separately produce five private interpretations, where a team working through the material together produces one agreed norm. And when adoption stalls, it usually stalls for organisational reasons: mismatched expectations, unclear ownership, a senior engineer who is not yet convinced. Those are legitimate obstacles, they are invisible to a document, and they can be addressed in a live discussion. And a document goes out of date: the tools named in these modules change monthly. This page is accurate as of the day it was written; a conversation is accurate today. The optional appendix “Teaching this to your team” covers this in more detail: what a team still has to do once the material is understood, and who has to own each piece of it.

One consequence of all this is worth acting on. A document cannot hear you — so if a module confused you, a skill did not behave as described, or you got stuck somewhere between reading this and running it, telling me is the most useful thing a reader can do, and it is how this course improves. Live training exists for the pieces named above that a document cannot provide — practice on your own code, questions about your situation, one shared norm instead of several private readings — and arranging that, or sending that feedback, both start in the same place: LinkedIn. If you are reading this as an engineer rather than the person who arranges training, none of that is your problem: everything that follows is complete as it stands, and easy to forward to a colleague if it seems useful.

— Curtis "Ovid" Poe

Developers who use AI coding tools extensively – but don't carefully review their code – discover something unpleasant. The first day feels like magic. The first month is productive. But over time, they notice that the codebase has become a place they no longer recognise. Three different ways of handling errors, a config value hard-coded in two places, tests that pass without asserting anything, and a feature that technically does what they asked but not what they meant.

Nothing went dramatically wrong. That is the whole problem. Code quality rarely degrades in one dramatic change; it slips through a series of small decisions that each seemed reasonable in isolation. The assistant did what they asked, every time, and the sum of all those reasonable answers is a codebase carrying debt they never chose to accept.

Two arrangements

What went wrong there is not really a code-quality problem. It is a question of who was making the decisions. The developer told the assistant what to do and hoped it would take charge. The assistant did as it was told — it always does — and the developer found out what it had decided only once the code was written.

That is AI-driven engineering: the assistant sets the pace, and the engineers are downstream of decisions they never saw being made. PAAD — an open-source project for AI coding assistants, explained in full in the next section — proposes the inverse, and its README puts it as a tagline:

Engineering-driven AI, not AI-driven engineering.PAAD README

Same speed, opposite direction. You see what the AI is about to do while you can still change it, and you make the decisions. Concretely, that means something different happens at each stage of the work. The names in the right-hand column are PAAD's four core skills — things you invoke by name, each with a module of its own later:

Read the right-hand column downward and you have the shape of the rest of this course. Each module covers one row.

AI coding assistants can compress that process dramatically, but they do not reliably challenge weak requirements, detect drift from the plan, or protect long-term code quality on their own.PAAD README

What PAAD is

PAAD (pronounced "pad") is an open-source system of AI agent skills — MIT-licensed, on GitHub, created by Curtis "Ovid" Poe. It does not replace your AI-assisted development tools — it complements them, and its README names Superpowers, a separate open-source workflow toolkit for coding agents, as an example of something you can keep using alongside it. Module 3 introduces Superpowers with the other toolkits. The four letters name four common failure modes, and each failure mode has skills that address it.

The analogy that makes the idea clear

The article introducing the methodology draws a historical parallel worth noting. When Fortran was introduced in the 1950s, IBM knew developers would object, because a compiler could not produce assembler as efficient as hand-written assembler. So the marketing focused on saving developer time, while noting the generated code was almost as fast.

It was decades before compilers routinely wrote assembly that ran faster than human-written assembly. Today, very few humans can write assembly code that outperforms a compiler. This is where we are with AI.Curtis Poe, "Watching Claude Sonnet Outperform Opus"

The claim is not that AI writes better code than you. The claim is that with discipline — the D in PAAD — it produces code that is almost as good as what you would have written, and produces it in a fraction of the time it would have taken you. The analogy is about how quickly the code gets written, not how quickly it runs. And as with compilers, the quality gap is expected to narrow.

It is a good analogy, and like all good analogies it should be checked rather than admired. The appendix “How good is the evidence?” does exactly that.

What this course covers

You will work through the four letters in order, then assemble them into the per-feature loop that ties them together. Two modules do something other than advance that argument. Module 3 is prerequisite rather than PAAD-specific: it explains spec-driven development, the practice PAAD assumes you are already following — skip it if you run spec-kit, Kiro, or OpenSpec today and know why. Module 4 stops to ask what the model cannot see no matter how carefully you review its output. Along the way there are knowledge checks — they are not graded, they exist because reading about a review process and being able to run one are different skills. There is a final assessment at the end.

After the assessment there are optional appendices. One of them, “How good is the evidence?”, tests the whole argument against the independent research literature. Nothing in the course depends on any of them and no assessment question draws on them — take the methodology on trust if you prefer, and go there when you want to know which parts of the case are actually well evidenced. Another, “What the Fable review found”, prints the findings behind the case study in Module 2, so you can judge them yourself instead of taking a count on trust. Another, “Why small specs”, argues that all of these gates work far better on small artefacts than large ones — read it when you are writing your first spec rather than after.

No prior experience with PAAD is assumed. Some familiarity with an AI coding assistant — Claude Code, Cursor, Kiro, Antigravity — will help, but the ideas transfer to any of them.

Mechanism one: the assistant is a yes man

AI is a "yes man." It does what you ask it to do, focusing on what you asked it to do. It ignores the big picture unless you explicitly tell it to look at it."Watching Claude Sonnet Outperform Opus"

This is not a bug that will be patched. Instruction-following is what LLMs are designed to do. An assistant that pushed back on every third request would be exhausting and would mostly be wrong. But the consequence is that the quality ceiling of your output is set by the quality of your input — and nothing in the default loop inspects your input.

It is worth being precise about what "your input" means, because most people read it as "your prompt." It is not. Your input is the prompt plus the codebase the assistant is reading to answer it, and the second part usually matters more.

A human senior engineer handed a flawed spec says "wait, what happens when two people do this at once?" The assistant handed the same spec writes the code. Both are behaving correctly given their incentives. Only one of them saves you two weeks of work. This is the mechanical reason AI-driven engineering fails: nothing in the default arrangement asks the assistant to question the instruction, so nothing is checking direction. The capacity is there — an assistant will argue with a spec if you tell it to, which is exactly what pushback is — but it is a step you have to add, not one you get for free.

Mechanism two: debt accumulates at the speed of development

The article's formulation is compact: vibe coding rapidly accumulates technical debt while spec-driven development slowly accumulates technical debt. Note that neither number is zero. Spec-driven development is better, not sufficient. The reason is that acceleration and debt are coupled — if you ship five times as much code in a week, you also ship five times as many small structural compromises, and you have one fifth as long to notice each one.

That middle row is the one everything else in this course is built on top of, and it deserves more than a table cell. Module 3 covers what spec-driven development actually is — what a spec is, what the toolkits do, and where the practice has weaknesses. If SDD is already how you work, treat that module as optional.

Mechanism three: errors are cheapest at the earliest layer

This is the oldest idea in software engineering and PAAD's central organising principle, and the article puts the cost gradient in terms of blast radius:

If you have a bad ticket, you write some bad code. If you have a bad spec, you have lots of bad tickets. If you have bad steering, every spec you ever create is impacted."Watching Claude Sonnet Outperform Opus"

Read that as a hierarchy. Steering files sit above specs; specs sit above plans; plans sit above code. A defect at any level is inherited by everything beneath it. Which tells you immediately where review effort has the most value: as far up that stack as you can get it.

What the evidence looked like

The article reports an architecture analysis of a codebase of roughly 10,000 lines, built in a few hours by Fable — the most powerful model released at the time of the analysis — working from specifications that were themselves produced with Superpowers, PAAD and Ponytail — but with PAAD deliberately withheld from the implementation, to see what the model builds natively from high-quality input. Five specialist agents produced 79 raw findings, which an adversarial verification pass reduced to 50.

Those 50 verified findings break down like this:

Thirty-three verified flaws in 10K lines written in an afternoon. The point is not that Fable struggled — it "had no significant problems in creating the software in a few hours." The point is what it produced along the way. The conclusion is blunt: Fable "can brute force past architectural challenges, but without clear and explicit guidance, it creates the same technical debt that less powerful models create." Raw capability did not substitute for guidance.

The previous module put three approaches in a table and handed one of them an acronym without explaining it. This module explains it. If you already run Superpowers, spec-kit, Kiro, or OpenSpec and know why, you can skip to the last two headings — the criticism, and where PAAD attaches.

The two ways to ask for code

Vibe coding — a phrase Andrej Karpathy coined in early 2025 and which was adopted faster than anyone expected — is describing what you want in chat, accepting the diff, and moving on. You are steering by feel. The code exists, it appears to work, and the reasoning that produced it disappeared with the session.

It has real strengths. It is also, as GitHub's write-up of the problem puts it, the source of a familiar experience: "you describe your goal, get a block of code back, and often… it looks right, but doesn't quite work."

Spec-driven development is the response. Birgitta Böckeler's definition is the most concise one available:

Writing a "spec" before writing code with AI ("documentation first"). The spec becomes the source of truth for the human and the AI.Birgitta Böckeler, "Understanding Spec-Driven-Development"

That is the whole idea. Everything else — the toolkits, the directory layouts, the slash commands — is machinery for making it convenient. GitHub frames the same shift as treating specifications as "living, executable artifacts that evolve with the project," and the underlying justification is a claim about what models are for: they excel at "pattern completion, but not at mind reading." A spec is how you stop asking for mind reading.

Three levels of ambition

"We do SDD" turns out to mean at least three different things. Böckeler's taxonomy is worth learning, because the differences matter and almost nobody states which one they mean.

They are not three options you choose between. They are a ladder — Böckeler draws them "with inheritance arrows… because they build up on top of each other." Every SDD approach is spec-first. Spec-anchored is spec-first plus keeping the spec alive. Spec-as-source is spec-anchored plus never hand-editing the code. So the question is never which level you picked, but how far up you climbed.

All SDD approaches and definitions I've found are spec-first, but not all strive to be spec-anchored or spec-as-source.Birgitta Böckeler

Two phrases in that table are doing more work than they look. "Kept and updated" means both things at once: the spec lives in the repository beside the code, and somebody edits it when the behaviour changes. A spec committed once and never touched again is not anchored — it is spec-first with a corpse in the tree. "The next change starts from the spec" means that when you return to modify the feature, you open the spec first, revise it, and drive the implementation from the revision. Under spec-first you return to the code instead, because by then the spec is out of date and you know it.

The gap between the top two levels is narrower than it sounds and larger in practice. Spec-anchored keeps a maintained spec beside code that humans still edit. Spec-as-source makes the code an artefact nobody opens, the way nobody opens a compiled binary. That is why Böckeler reaches for the model-driven development comparison: it is the same bet the 2000s made, minus the parseable spec language and the elaborate code generators — and the price for dropping those, in her words, is "LLMs' non-determinism."

The shape most toolkits share

The tools differ in vocabulary and file layout far more than in structure. Most of them run some version of this basic sequence:

Hold that table next to the per-feature loop in Module 10 and the relationship becomes obvious. PAAD does not replace any of these stages. It inserts a review gate between them.

Stage zero: steering files

This is the layer Module 2's blast-radius quote was talking about, and it is worth a section of its own because it is the piece most newcomers never find. A steering file holds what is true for the project regardless of which feature you are building: what the product is, what stack it uses, where code lives, which conventions are non-negotiable, what the assistant should never do. It is loaded at the start of every session, so its cost and its blast radius are both permanent.

The naming has not converged, but it is starting to. AGENTS.md is an open, tool-neutral format now stewarded by the Agentic AI Foundation under the Linux Foundation, used by more than 60,000 open-source projects and read natively by around 25 coding agents — Codex, Cursor, Jules, Copilot and others. It emerged from a collaboration between several of those vendors precisely to stop every tool inventing its own filename.

# CLAUDE.md
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

The toolkits

Five are worth knowing. They are more alike than their documentation suggests, with the caveat above about where they diverge.

Why SDD is generally preferred

Four reasons, in rough order of how much they matter.

1. Written intent can be reviewed. This is the big one. A prompt is gone the moment it is answered; a spec sits on disk where a colleague — or pushback — can argue with it. You cannot put a review gate in front of something that was never written down.
2. It converts silent assumptions into explicit decisions. Vibe coding does not remove the decisions; it delegates them. Every ambiguity you leave open, the model closes for you, reasonably and invisibly, and you find out which way it went at review time. A spec is where you find out first.
3. It outlives the session. Context windows degrade and sessions end — Module 5 covers the evidence. The spec is the only part of your reasoning that survives to the next session, the next developer, or the incident review in eight months.
4. It separates what from how. The stable half stops depending on the disposable half, which is what makes it possible to rebuild an implementation without re-arguing the requirements.

And the debt claim from Module 2, restated now that it means something: vibe coding rapidly accumulates technical debt while spec-driven development slowly accumulates technical debt. Slowly, not never. Treat that as an experienced practitioner's observation rather than a measured result — the appendix “How good is the evidence?” is where the measurements are, and they are messier than the slogan.

Where SDD has weaknesses

The most useful critical read of SDD comes from Böckeler, who worked through three of these toolkits properly — Kiro, Spec Kit and Tessl — and came away unconvinced by all three, for different reasons. Her objections are worth understanding before you adopt anything, because they predict exactly which parts will annoy you. Her verdict on the two workflow toolkits:

Kiro and spec-kit provide one opinionated workflow each, but I'm quite sure that neither of them is suitable for the majority of real life coding problems.Birgitta Böckeler, "Understanding Spec-Driven-Development"

Her reservation about Tessl is a different one, and it comes at the end of this section.

Her sharpest warning is historical. Model-driven development promised the same thing — write the model, generate the system — and failed because of inflexibility. Attaching an LLM to that idea does not obviously fix it:

We might end up with the downsides of both MDD and LLMs: Inflexibility and non-determinism.Birgitta Böckeler

None of this makes SDD a bad default. It does mean you should expect the markdown files to multiply, expect the agent to ignore parts of it, and be willing to run a lighter process on lighter work.

Where PAAD attaches

Notice what is missing from the document-generation toolkits in the table above. Spec Kit, Kiro and OpenSpec each generate artefacts and hand them to you, and the generation step does not review what it just produced. Nothing argues with your spec, and nothing checks whether the tasks it wrote actually cover the requirements it wrote them from.

That gap is the entire premise of this course.

PAAD is deliberately agnostic about which toolkit produced the documents. Its auto-detection scans .kiro/, specs/, docs/plans/ and docs/specs/, and it will also review a plain markdown file — or the conversation you have just had — if that is what you have. Pick whichever SDD tool suits your team. The gates attach either way.

The model reads your repository faster and more patiently than any human will. That part is real, and it is why PAAD works at all. But the expensive decisions in software rarely depend on what is in the repository. They depend on what is not in it.

None of the facts in the right-hand column are in the codebase. Most were never written down anywhere. They live in the people who were there — which is what experience actually is, once you stop treating it as a personality trait.

Why this matters to whoever is paying for it

The argument for keeping engineers in charge is usually made on feelings — trust, craft, morale. Here it is simpler than that, and it is closer to measurable.

Seniority is not nostalgia. It is an input the model does not have. The engineer who remembers the outage is not being sentimental; they are supplying a fact that is absent from every file the AI just read. Remove them from the decision and you have not made the process leaner. You have deleted a critical input and added confident output.

This is why every PAAD skill reports rather than decides, and why each one ends in a human choice rather than a merge. Not because the model is untrustworthy in some abstract way, but because it is working from a partial input while the engineer holds the rest. Engineering-driven AI is the arrangement where those two halves actually meet. AI-driven engineering is the one where the half that happened to be written down wins by default.

1. Steering files

Module 3 covered where these live in each tool — CLAUDE.md, AGENTS.md, .kiro/steering/, .specify/memory/constitution.md and the rest. This section is about what to put in one. A steering file typically describes what your project is, what technologies it uses, where to find relevant code, and the practices your codebase follows.

Good steering files more than repay their cost, in two ways. They reduce confidently wrong answers, and they save tokens, because the assistant stops searching the repo to rediscover facts you could have simply told it. Bad steering files are worse than none: a wrong statement in a steering file is inherited by every single piece of work that follows.

They are also loaded into context on every single session, which makes length a real cost rather than a style preference. Claude Code's own documentation suggests keeping each file under 200 lines, on the grounds that longer files consume more context and get followed less reliably — a useful rule of thumb whichever tool you use. Write instructions concrete enough to verify: "run npm test before committing" beats "test your changes."

2. Context management

Long contexts degrade. The four failure modes have names, and each is worth recognising when it happens to you:

Generation additionally suffers a quadratic slowdown: because each new token is compared against every token already in the window, the cost of producing one grows roughly in proportion to the context length — and the total cost of a long session grows with its square. A full window is slower as well as worse. The practical consequence is that a session which has been running for hours is measurably worse at reasoning than a fresh one, even though nothing visibly broke.

I try to keep my context under 30%. I get much higher quality work out of this."Watching Claude Sonnet Outperform Opus," on a 1M-token context window

The article notes there is no hard-and-fast rule. It reports hearing others put the ceiling at 40–50% on smaller windows, while allowing that on a 200K window you sometimes have no choice but to spend a large share of it just guiding the model's reasoning. The number matters less than the habit: treat a fresh session as a resource you spend deliberately. This is why the per-feature loop tells you to execute tasks in new sessions, and why agentic-review has a pre-flight check that stops and asks you to start a fresh session if your conversation already has substantive history.

3. A test suite that pins current behaviour

If you are bringing PAAD to an existing codebase, tests come first — but not the kind of testing you may be imagining.

Your goal is not to fix bugs. Your goal is simply to lock down current behavior to ensure that you haven't unexpectedly changed things."Watching Claude Sonnet Outperform Opus"

This is the single most counter-intuitive instruction in the whole methodology, and the most important. When you write tests against a legacy codebase you will find bugs. Do not fix them. Write a test that asserts the buggy behaviour, note the bug, and move on. The suite's job right now is to be an alarm that sounds when something changes — not a statement of what ought to be true. With legacy codebases you often encounter so many bugs that trying to fix them all will overwhelm you before the safety net exists.

Three layers are expected: unit tests for isolated components, integration tests validating that components communicate correctly, and end-to-end tests for critical user journeys. The article targets 95%+ coverage when working with AI, against a traditional 80% baseline — the reasoning being that AI makes writing tests cheap enough that the old cost/benefit line moves. Treat that number as a heuristic rather than a target to optimise: as the next paragraph explains, coverage is famously easy to inflate without improving anything.

4. A consistent way to run your checks

Whatever your project uses — a Makefile, npm scripts, a justfile, a shell script — agents work far better when there is one documented command for testing, one for linting, and one for coverage. PAAD includes a makefile skill that will generate these for you, though Makefiles are less popular than they once were and this may not suit your stack.

The value is not the tool. It is that developers and agents run the same quality checks through the same commands. An agent that knows how to run your tests does not have to guess whether this project uses pytest, jest, or cargo — and a steering file naming those commands does most of the same work.

AI assistants rarely tell you your spec has problems. pushback does. It critically reviews specs, PRDs, requirements documents, and design plans before work begins, so you do not build on flawed assumptions.

I'm using it for every non-trivial change, and so far, I think I've argued with 2 of maybe 40 recommendations. It has improved EVERY SINGLE spec I've fed it so far.A PAAD user, quoted in the README

How to run it

/pushback docs/specs/checkout-rework.md   # review a specific file
/pushback                                 # auto-detect from the
                                          # conversation or common paths

With no argument it resolves the spec in order: an explicit path, then a spec in the conversation history (it will confirm with you first), then a scan of docs/plans/, docs/specs/, and files named requirements.md, PRD.md, spec.md. If it finds nothing it asks. Notably, pushback does not ask for a fresh session — the conversation you have just had may itself be the spec.

Phase 1 — the reality check

Before it reads a single requirement, pushback looks at your git history: git log --oneline -50 --since="2 weeks ago", reading commit messages and diffing anything relevant. It is asking one question — does this spec assume things about the codebase that are no longer true?

Conflicts are presented upfront, before any other analysis, with what the spec assumes, what actually changed (SHA and date), why it matters, and options. The reasoning is direct: a spec that assumes deleted infrastructure is wrong before the analysis even starts. If your project is not a git repo, this phase is skipped.

Phase 1.5 — scope shape

Two structural checks, in this order:

Feature cohesion. Do the features in this spec serve different user goals? If it bundles things that would naturally be separate PRs, it identifies the groups and asks whether you want to split before continuing.

Spec size. Heuristic signals — multiple unrelated system areas, a very long document, an implementation that would touch many modules. Note what is deliberately not a signal: the skill's own words are "requirement count is not a signal — estimate the diff instead. A spec can list a dozen requirements that are all facets of one small change." But size alone is never the argument. If a meaningful split exists where each piece delivers independent value, it suggests the split. If the features are genuinely interdependent, it flags the size and explains why splitting is not practical, then moves on.

Phase 2 — the six categories

See it work

Here is a spec that looks entirely reasonable. Read it, decide what you would flag, then reveal the findings.

How findings are presented

This detail matters more than it appears to. Findings are ranked by severity — critical, serious, moderate, minor — and presented one at a time. For each: state the problem, give concrete options from best to worst with a recommendation and a short explanation for each, then wait for your response before moving to the next.

You can say "good enough" or "stop" at any point, and the remaining issues are recorded under an Unresolved Issues heading rather than lost. At the end, pushback asks whether to update the spec in place or write a separate report to paad/pushback-reviews/.

What good pushback avoids

• Critiquing without reading the codebase. "This contradicts what already shipped" outranks every stylistic concern, which is why the reality check runs first.
• Raising a problem without options. "This is ambiguous" is an observation. "This says 'fast response times' — do you mean under 200ms for 99% of requests? Under a second? That determines whether you need caching" is pushback.
• Manufacturing issues to fill all six categories. Not every spec has security concerns. Saying a category is clean and moving on is the correct behaviour.
• Softening findings to seem agreeable. The entire value is saying what a reviewer would say before the code exists. Criticism that has been softened is worse than no criticism at all.
• Rewriting the spec instead of critiquing it. A silent rewrite replaces your judgement with the model's.

Where pushback asks "is this spec any good?", alignment asks "does the planned work actually match it?" It needs two things: an intent document (requirements, spec, PRD) and an action document (plan, tasks, implementation steps). It classifies whichever documents it finds into those two categories and compares them.

/alignment                            # auto-detect
/alignment requirements.md plan.md    # specific files
/alignment docs/specs/ docs/plans/    # directories

Auto-detection scans .kiro/, specs/ (spec-kit), docs/plans/, docs/specs/, and common filenames. Like pushback, it opens with a source-control reality check against recent history.

The three checks

The two-directional structure is the point. Coverage alone catches what you forgot. Scope compliance catches what the assistant added on its own initiative — and that second category is where AI-assisted projects drift, because an assistant that adds a caching layer nobody asked for is being helpful in a way that costs you a maintenance burden.

Issues arrive dependency-ordered

Unlike pushback's severity ordering, alignment presents issues in dependency order, root causes before symptoms:

1. Missing or unclear requirements first. A missing requirement explains why there is no task for it and no design for it.
2. Design gaps second, where design docs exist — a design gap may explain why tasks are missing or wrong.
3. Missing, orphaned, or out-of-scope tasks last. These often resolve themselves once the upstream issues are fixed.

Severity is Critical / Important / Minor, and as with pushback you get one issue at a time with options best to worst, and you can stop whenever you like.

The mandatory TDD rewrite

This is the part people are surprised by. Once alignment is confirmed, alignment rewrites your tasks into red/green/refactor format. It skips this only if the tasks are already in that format, or if they do not involve code — infrastructure provisioning, documentation, design work, data migrations, manual processes.

Each rewritten task names the requirement it addresses and then specifies three steps:

Pushback and alignment operate on documents. Architecture operates on the codebase you already have — and unlike the other two, it is a diagnosis you run periodically rather than a gate you pass through per feature.

/agentic-architecture — the diagnosis

/agentic-architecture                              # whole repo
/agentic-architecture src/                         # scoped
/agentic-architecture packages/api/ packages/shared/

Five specialists analyse the codebase in parallel, each from a different angle so that problems cannot hide behind a single reviewer's blind spots. A verification phase then filters false positives by reading actual code and checking git history.

Between them they cover 34 flaw and risk types and 14 strength categories, with a coverage checklist ensuring every category is actually assessed. The report — written to paad/architecture-reviews/ — includes strengths as well as flaws, plus a hotspots list of the files and directories most worth your attention.

Diagnosis onlyThis skill does not propose fixes. That is a deliberate separation — mixing "here is what is wrong" with "here is what I changed" makes it impossible to review either one properly.

/fix-architecture — the treatment

Fixing is a separate skill that takes an architecture report as its input and works through findings one at a time, test-first. It requires a feature branch — not main or master — and an existing report.

Before starting it runs pre-flight checks: branch protection, report staleness detection, test infrastructure verification, and a baseline test run. Then it has a conversation with you about how you want to work — solo or team, batch size, auto-commit or manual, how to sort flaws by priority — before confirming a plan.

Each fix validates that the flaw still exists, writes safety-net tests where needed, proposes options with trade-offs, and executes red/green/refactor. Outcomes are recorded in the report itself: Fixed, Won't fix, Partially fixed, Skipped, Fixed (pre-existing), Attempted/reverted. That status tracking is what makes the work resumable across sessions.

Discipline is the letter that is not a technique. The other three describe things to do; this one describes doing them every time, including the Friday afternoon when the change is small and the deadline is Monday. The skills grouped under it are the ones that make consistency cheap enough to sustain.

/agentic-review — the pre-merge gate

/agentic-review                   # diff against main
/agentic-review develop           # diff against a different base
/agentic-review main src/auth/    # scoped to a directory

Six specialists examine your branch in parallel. Where typical AI review features give shallow, unsystematic feedback, this is designed as a deliberate quality gate: parallel analysis, then a verification pass that reads the actual code to drop false positives, assigns severity, merges duplicates, and classifies what is yours to fix.

Findings are ranked Critical / Important / Suggestion and the report is written to paad/code-reviews/.

The three categories

What makes this more than a linter is how it decides what is yours to fix:

That middle category is the forgiving one. Without it, every review of a legacy file mixes problems you did not cause into the list of things blocking your merge. With it, each one gets a stable ID and a single backlog entry — later reviews re-confirm that entry rather than creating a duplicate, and the finding is set aside in the report's out-of-scope section instead of blocking your PR. The backlog is explicit-removal only: agentic-review never auto-resolves an entry, so you or a later agent deletes it when the work is actually done.

Run it more than once. The README is explicit that repeated runs are valuable, and equally explicit that this is a stronger automated safety net, not a replacement for human review.

/agentic-a11y — accessibility as a default

Discipline also means accessibility is not an afterthought. This skill scans for meaningful accessibility barriers and organises them by who they affect, with dedicated specialists for screen reader usage, visual and colour contrast, keyboard and motor interaction, cognitive load, and multimedia.

It supports web, iOS, Android, React Native, Flutter, desktop, CLI, and games, detecting the platform automatically. It evaluates against WCAG 2.2 AA — applied through WCAG2ICT for non-web platforms — with AAA noted as bonus recommendations, and draws on platform guidance such as the Apple HIG, Material Design, and the Xbox Accessibility Guidelines. Output includes an impact summary by user group and the five highest-impact, lowest-effort quick wins.

/vibe — speed without recklessness

Not every change deserves a spec. vibe exists for the small fix that still benefits from guardrails — roughly one to three files in the same module.

Its pre-flight checks are where the value sits:

• Test infrastructure. If there is no test framework, it says so and asks whether to set one up or proceed without TDD. If you proceed, it still does GREEN and REFACTOR — it just skips RED.
• Scope check. One to three files in the same module is good vibe territory. Four or more files, or crossing module boundaries, and it warns you that this may want a more structured approach.
• Architecture smell. If a conceptually simple task — "only admin users can download finance reports" — turns out to require a great deal of work, it stops and investigates whether deeper structural issues are making it harder than it should be.
• Reusable components. Before building a toast notification (the small message that appears briefly and then disappears), a modal, a validator, or a permission check from scratch, it searches the codebase for existing utilities, half-finished implementations, and established patterns.

Then red/green/refactor is mandatory. If the test passes when it should fail, or fails in an unexpected way, it stops and reassesses rather than continuing. Note what it does not do: vibe writes code, but staging and committing stay with you.

This is the loop the article prescribes for each feature. Several stages are marked may repeat — that is not a sign of doubt; it is the design. Pushback and alignment are often worth running more than once, especially when a spec evolves or a plan changes mid-execution.

Where the other skills fit

The rhythm underneath

Strip away the skill names and the loop has a simple shape: every artefact gets reviewed by something other than the thing that produced it, before anything downstream is built on it. The spec is reviewed before tasks are generated. The tasks are reviewed before code is written. The code is reviewed before it merges.

That is not an AI insight — it is how engineering organisations have worked for decades. What is new is that each of those review passes now costs minutes instead of days, which changes which ones are worth doing. The reason PAAD reviews the spec is not that specs got worse; it is that reviewing them got cheap.

Which is the whole tagline, stated mechanically. Engineering-driven AI is not a new philosophy of software; it is the ordinary review discipline you already believe in, running at a cadence that can keep up with a machine. The loop is what that looks like in day-to-day work.

Install — Claude Code

/plugin marketplace add Ovid/paad
/plugin install paad@paad

The install command opens the plugin's details rather than installing immediately — you pick a scope there: install for you (user scope), for all collaborators on the repository (project scope), or for you in this repo only (local scope). Then run /reload-plugins to activate the skills in the session you are already in.

After that, start with /paad:help to see the available skills and when to use each. Every skill announces its own name and version on invocation — Running paad:vibe v1.24.1 — which is how you see what version you are running.

Install — Cursor, Kiro, Antigravity

PAAD skills use the same SKILL.md format Cursor skills expect, so installation is a copy:

# Cursor
cp -r kiro_and_antigravity/skills/.kiro/skills/* .cursor/skills/

# Kiro
cp -r kiro_and_antigravity/skills/.kiro/skills/* .kiro/skills/

# Antigravity — the .agent files are wrappers pointing at the .kiro files,
#                so copy both directories
cp -r kiro_and_antigravity/skills/.kiro/skills/*  .kiro/skills/
cp -r kiro_and_antigravity/skills/.agent/skills/* .agent/skills/

Invoking skills

You rarely need to type a prefix anywhere. Three routes work:

One caveat worth flagging: the Claude Code plugin documentation describes plugin skills as always namespaced, which does not fit well with the README's claim that the prefix can be omitted. If the bare form does not resolve for you, use the qualified one — it works either way.

Starting on an existing codebase

The two-week plan further down was written for a new project, or for one that already has a test suite you trust. Brownfield work is a different problem and wants a different order. The codebase is large, nobody currently on the team wrote all of it, and the safety net you would need before changing anything is the thing you do not have. If that describes your situation, follow the sequence below instead — in order, because each step is what makes the next one safe.

1. Everything the AI produces goes into source control

Specs, plans, architecture reports, test roadmaps, review backlogs. Commit them, on the same branch as the code they describe, by default.

PAAD's own outputs make that a single decision rather than a running one: everything it writes lands under one top-level paad/ directory in your repository — paad/pushback-reviews/, paad/alignment-reviews/, paad/architecture-reviews/, paad/code-reviews/, paad/test-roadmap/, paad/dedup-reviews/, paad/a11y-reviews/. One directory to add, one convention to explain to the team.

The first reason is mechanical: PAAD's long-running skills keep their memory on disk, so an uncommitted artefact is a skill that has to start over. test-roadmap resumes from paad/test-roadmap/test-roadmap.md — across unrelated commits, squash merges, fresh clones and sessions that remember nothing about the last one. fix-architecture writes its outcomes back into the architecture report and is designed to be picked up again in a later session against that same file. agentic-review gives each out-of-scope finding a stable ID in paad/code-reviews/backlog.md so that later runs re-confirm the entry instead of raising a duplicate. None of that survives a file that only ever existed in one person's working tree.

The second reason matters more on a legacy codebase than anywhere else. Git already tells you what changed. It does not tell you what somebody decided was wrong, what they considered instead, or which of the findings they consciously chose not to act on. On code older than the current team, those documents are frequently the only written account of the reasoning — and they cost nothing to keep.

2. Validate the steering files before anything else

This is first among the things you actually do, because everything after it inherits whatever it says. Module 5 gives the cost — a wrong statement in a steering file is inherited by every single piece of work that follows — and the practical test: read it line by line and ask whether each line is still true. On a legacy codebase you will usually find one of two situations. There is no steering file, in which case the assistant is inferring your conventions from whatever it happens to read. Or there is one, written during a setup that nobody remembers, describing a project that has since moved.

Do the Module 3 decision at the same time, once, deliberately: pick a canonical document and make the other locations import or symlink it rather than repeat it. Two steering files that disagree is the same cost as one that is wrong, plus the question of which one is wrong — and nothing will tell you. It is also the arrangement PAAD's own skills expect: agentic-review and agentic-architecture scan for CLAUDE.md and AGENTS.md by name before they dispatch anything.

Bad steering does not fail loudly. It produces confident, plausible, wrong work at every layer beneath it, which is the most expensive failure mode in the whole method and the one you can eliminate in an afternoon.

3. Build a test suite that pins current behaviour

PAAD's own README puts this bluntly: "PAAD is risky to use with codebases without a strong test suite." Every skill that changes code — fix-architecture, vibe — works test-first, and test-first on untested legacy code means the tests get written under time pressure, one flaw at a time, by whoever happens to be fixing that flaw. Doing it deliberately first is the same work in a better order.

Module 5 gives the rule that makes this survivable, and it is the most counter-intuitive instruction in the methodology: your goal is not to fix bugs. You will find them. Assert the current behaviour, write the bug down, move on. The suite's job right now is to be an alarm that sounds when something changes, not a statement of what ought to be true.

The experimental test-roadmap skill exists for exactly this step, and there is one thing people get wrong about it often enough that the README calls it out. It is not a single command. The first run detects your stack, grades the tests you already have, and writes a phased plan — and writes no tests at all. Every run after that writes one phase, proves each test catches the bug it claims to by injecting that bug in a throwaway git worktree, commits the phase, and tells you where you are. A fourteen-phase roadmap is fifteen invocations. Teams run it once, read the plan, feel informed, and stop with zero tests written.

4. Take an architecture baseline — then argue with it

agentic-architecture is diagnosis only: five specialists, 34 flaw types, 14 strength categories, a verification phase that filters false positives by reading the code and checking git history, and a report written to paad/architecture-reviews/. On a codebase you inherited, that report is the first honest description of the thing you are responsible for.

It is also a document produced by an AI, which puts it under the same rule as every other document produced by an AI in this course: something other than the thing that made it should review it before anything is built on it. Run pushback on the report.

The larger the codebase, the more that pass earns its place, and the reason is in the skill's own design. Specialists report only findings they hold at 60% confidence or above, and cap a finding at 79 where confirming it would require changing code — so the report is calibrated, not certain. Past roughly 500 source files the skill partitions the files across two instances of each specialist, which means that on a large repository no single reviewer saw the whole thing. That is the right engineering trade-off and it has a predictable consequence: the findings that get missed or mis-weighted are the ones whose evidence is spread across the partition. A cross-cutting flaw looks small from inside either half.

What you are checking is not whether each individual finding is real — the verification phase already did that, against the code. You are checking the list: what is not on it that you know is true, which severities do not match the risk as you understand it, and which findings are technically correct and practically irrelevant to this system.

5. Now the report is a rescue roadmap

A reviewed, prioritised architecture report with a test suite underneath it is the thing this whole sequence was for. fix-architecture works through it one flaw at a time, test-first, on a feature branch, recording an outcome against each finding — Fixed, Won't fix, Partially fixed, Skipped, Fixed (pre-existing), Attempted/reverted — so the work resumes cleanly across sessions. It detects when fixing one flaw resolves others, which is also why it refuses to parallelise: merging several structural refactors back together is a reliable way to introduce new bugs.

It will write safety-net tests where a flaw sits in untested code. You do not want that to be how your test suite gets built. Discovering the absence of tests one flaw at a time, mid-refactor, is the slowest and least deliberate version of step 3 — which is the whole reason step 3 comes first.

Module 8 is careful to say agentic-architecture is a periodic diagnosis rather than a gate, and Module 11's two-week table says to run it once the rest feels routine. Both hold for a codebase you already understand. On an inherited one the first pass is a different thing: it is what tells you whether the codebase can carry the rest of the method, and how much work stands between you and that. Sequence it early, and give the work that follows it a date before you run it — the appendix on teaching this to your team explains why finding that time afterwards is harder than reserving it in advance.

6. None of it replaces human judgment

Module 4 is the reason, and it lands hardest here. The AI sees all of your code and none of your context. A clean architecture report says no problems were found in what the review could see — and what it could see was the repository. The outage that explains the retry loop, the partner whose feed has been malformed since 2019, the compliance rule that made a class ugly on purpose, the volume of traffic arriving next quarter: none of that is on disk, and on a codebase older than the current team, none of it is in anybody's head either.

This is not a caveat attached to the end of the sequence. It is the reason a person runs the sequence rather than an agent. Every step above produces a document that looks finished, and each one is worth precisely what the human reading it brings to the reading. A report you accept without argument has told you nothing you did not already have.

A realistic first two weeks — new or well-tested projects

This is the gentler on-ramp, and it assumes something: that the codebase either does not exist yet or already has tests you would trust to catch a regression. If your codebase already exists and that is not true of it, ignore this table and follow the sequence above instead. Adopting the gates one at a time is the right move when the foundation is sound; on an inherited codebase it postpones the only step that makes the rest safe.

Reference card

Sources

Primary

• github.com/ovid/paad — repository, README, and skill definitions (v1.24.1, MIT licensed)
• "Watching Claude Sonnet Outperform Opus" — Curtis Poe's article introducing the methodology
• Claude Code — Discover and install plugins and Create plugins
• Superpowers — a complementary toolkit PAAD's README names as compatible with it, and a spec-driven workflow in its own right (see Module 3)

Spec-driven development (Module 3)

• GitHub, "Spec-driven development with AI: Get started with a new open source toolkit", and the spec-kit repository
• Birgitta Böckeler, "Understanding Spec-Driven-Development", martinfowler.com — the source of the spec-first / spec-anchored / spec-as-source taxonomy and of the critical case
• OpenSpec — specs by domain, change proposals, and spec deltas
• Kiro — steering files
• AGENTS.md — the cross-tool format, stewarded by the Agentic AI Foundation under the Linux Foundation
• Claude Code — How Claude remembers your project, including the documented @AGENTS.md import and symlink patterns

Independent research cited in “How good is the evidence?”

• Liu et al., "Lost in the Middle: How Language Models Use Long Contexts", TACL 2024
• Modarressi et al., "NoLiMa: Long-Context Evaluation Beyond Literal Matching", ICML 2025
• Hong, Troynikov & Huber, "Context Rot", Chroma 2025
• Becker et al., "Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity", METR 2025 — and METR's 2026 qualification of that result
• Peng et al., "The Impact of AI on Developer Productivity: Evidence from GitHub Copilot", 2023
• Perry et al., "Do Users Write More Insecure Code with AI Assistants?", ACM CCS 2023
• DORA, State of DevOps 2024 and State of AI-Assisted Software Development 2025
• GitClear, AI Copilot Code Quality (2025) and The Maintainability Gap (2026) — vendor-produced; see the caveat in “How good is the evidence?”
• Boehm & Basili, "Software Defect Reduction Top 10 List", IEEE Computer 2001
• Bossavit, The Leprechauns of Software Engineering, and a summary of its cost-of-defect critique
• Bacchelli & Bird, "Expectations, Outcomes, and Challenges of Modern Code Review", ICSE 2013
• Sadowski et al., "Modern Code Review: A Case Study at Google", ICSE-SEIP 2018, and "Lessons from Building Static Analysis Tools at Google", CACM 2018
• Méndez Fernández et al., "Naming the Pain in Requirements Engineering", EMSE 2017
• Eveleens & Verhoef, "The Rise and Fall of the Chaos Report Figures", IEEE Software 2010
• Fucci et al., "A Dissection of the Test-Driven Development Process", IEEE TSE 2017
• Ghafari et al., "Why Research on Test-Driven Development is Inconclusive?", ESEM 2020
• Du et al., "Reducing False Positives in Static Bug Detection with LLMs", ICSE-SEIP 2026
• Stack Overflow, Developer Survey 2025 — AI section

Review size and decomposition (“Why small specs”)

• Karl Wiegers, "Improving Quality Through Software Inspections", Software Development, April 1995 — the source of the 150–200 LOC/hour reading rate, and of the 300–400 lines / 8–12 pages per session limit that follows from it
• SmartBear, "Code Review at Cisco Systems" — 2,500 reviews of 3.2M lines by 50 developers. Vendor-produced and uncontrolled; see the caveat in the appendix
• Rigby & Bird, "Convergent Contemporary Software Peer Review Practices", FSE 2013 — the median-review-size measurements
• Google, Engineering Practices: Small CLs — the 100/1000-line guidance, the files-changed dimension, and the stacked-CL pattern
• Maddila et al., "From Code Review to Code Critique: Intent, Drift, and Spotlight for AI-Generated Diffs at Scale", arXiv 2026 — Meta on agent-generated diffs outgrowing review capacity. A preprint, not peer-reviewed

Any methodology is worth checking against evidence gathered by people who were not involved in building it. That is not scepticism about the methodology; it is how you find out which parts of the argument the rest depends on.

The short version: the strongest evidence supports the parts of PAAD concerned with security and correctness review. Some of the more commonly repeated industry claims about AI and technical debt are, on close inspection, less settled than they appear — but the case for review gates does not depend on them.

AI-generated code contains more security defects

This is the best-established claim in the field, and it comes from multiple independent teams using different methods.

Rates vary widely with methodology, and the moderating study is a genuine caution against quoting the scariest number. But the direction is robust across peer-reviewed venues and independent groups. If you adopt only one thing from PAAD, the security specialist in agentic-review and the security category in pushback are the parts with the firmest evidence behind them.

AI-generated code carries a different defect profile

Here the picture is more interesting than "AI code is worse." The largest study of real production code, Liu et al. (2026), examined 304,362 verified AI-authored commits across 6,275 repositories. Of 484,606 issues found, 89.1% were code smells rather than runtime bugs or security problems. More than 15% of commits from every assistant introduced at least one issue, and 24.2% of those issues survived to the latest revision — which is the accumulation mechanism, documented directly.

The honest synthesis is that AI code has a different failure profile rather than a uniformly worse one: more unused constructs, broader exception handling, more verbosity, more shadowing (inner names hiding outer ones) — and materially more security weaknesses. That is a profile a targeted review pass is well suited to catch, which is more or less what PAAD's specialists are organised around.

The duplication question is still open

You will see it stated frequently that AI-assisted development is driving code duplication up and refactoring down. The source is almost always GitClear's analyses, which report duplication rising to 15.7% of changed lines while refactoring fell to 3.8%. Those are striking numbers and they may well be right.

Two things are worth knowing before you repeat them. First, the analysis has no control group and its central metric is proprietary, so it establishes a correlation over calendar time rather than a cause. Second, the one rigorous within-repository comparison that exists — Mao et al. (2026), matching 19,816 AI-generated files against 36,467 human files from the same repositories — found the opposite direction: duplicated lines at 18.69% for AI code against 25.89% for human code. What it did find is that AI duplication is more fragmented, at 0.679 clone instances per file against 0.534.

Does AI adoption accumulate debt over time?

The strongest causal evidence is not GitClear but a Tilburg University difference-in-differences study that exploits a natural experiment: when GitHub Copilot launched in preview it supported some languages and not others, giving genuine treatment and control groups across 2,755 repositories and 1,699 contributors over 24 months.

It found more output — 17.7% more lines, 4.1% more commits — and 2.4% more pull-request revisions controlling for volume. Note that effect size: real, measurable, and modest. The more striking finding was distributional. Peripheral contributors committed 43.5% more, while core contributors committed 19% less and absorbed 6.5% more review burden. More work arrived, and the reviewing of it concentrated on fewer people.

That fits PAAD's actual proposition closely. The problem is less that AI writes bad code and more that it shifts effort from writing to reviewing — and reviewing is the part that does not scale by adding another assistant.

Does AI make developers faster?

This is the most contested question in the field, and the honest answer is that it depends heavily on the task.

METR has since qualified its own result, warning that selection effects likely cause it to understate true speedup, and is redesigning the experiment. So the fair reading is not "AI makes developers slower." It is that task type and codebase familiarity dominate the direction of the effect, and that perceived speedup is an unreliable guide in either direction.

Two claims to handle carefully

Defects are cheaper to fix earlier

The direction is well supported. The famous magnitude is not. Boehm and Basili (2001) is the usual source for "100 times more expensive after delivery" — but the same sentence qualifies that the ratio is "more like 5:1" for smaller, non-critical systems. The exponential version has been credibly challenged as resting on evidence that does not support it, and it originates in 1970s projects with expensive release cycles that continuous delivery has largely shortened.

Use the directional claim, which is sound and sufficient for PAAD's argument. Avoid the 100:1 figure.

Code review catches defects

Bacchelli and Bird (ICSE 2013) found that although 44% of programmers ranked defect-finding as their top motivation for review, only 14% of 570 analysed review comments were defect-related. Sadowski et al. (ICSE-SEIP 2018) report that at Google, review expectations centre on readability, maintainability, and education rather than problem-solving.

Requirements defects are a real failure source

"Naming the Pain in Requirements Engineering" surveyed 228 companies across 10 countries: 48% cited incomplete or hidden requirements as a critical problem, and 39% of those linked it directly to project failure. Boehm and Basili separately estimate projects spend 40–50% of effort on avoidable rework. This is the empirical backing for putting a review gate at the spec, where pushback sits.

Automated review needs a verification pass

An ICSE-SEIP 2026 industrial study at Tencent found that of 433 verified static-analysis alarms, 328 were false positives — a 76% rate, rising above 90% once incomplete-context cases are included. Meanwhile Google requires code-review checks to produce fewer than 10% effective false positives, on the reasoning that developers abandon tools they cannot trust.

Real-world false-positive rates run roughly an order of magnitude above the level at which a tool stays usable. That gap is the whole justification for PAAD's verification phases — agentic-review and agentic-architecture both dispatch specialists and then run a separate pass that reads the actual code to drop false positives. The same Tencent study found LLM-based filtering removed 94–98% of false positives at about 93% accuracy. The verification step is not empty process; it is the difference between a tool people use and one they turn off.

Long contexts degrade model output

This one is well established, and it is the evidence behind the context-management advice in Module 5.

• "Lost in the Middle" (Liu et al., TACL 2024) — performance is highest when relevant information sits at the start or end of the context, and degrades significantly for information in the middle, even in models built for long contexts.
• NoLiMa (Modarressi et al., ICML 2025) — when literal keyword overlap is removed so retrieval requires inference, 11 of 13 models fell below half their short-context baseline at 32K tokens.
• "Context Rot" (Chroma, 2025) — across 18 models, performance degrades non-uniformly as input grows, even on trivially simple tasks.

One qualification: these measure retrieval and question-answering, not coding. Extending them to "long agent coding sessions produce worse code" is a reasonable inference rather than a measured result. Module 5, "Groundwork before the skills," covers what to do about it.

Where this leaves you

Read down that table and a pattern emerges. The claims that hold up best — more security defects, degraded self-assessment, degraded long-context reasoning, review burden concentrating on fewer people — are all arguments for putting a check between the model's output and your codebase. That is precisely what PAAD is. The claims that are shakier are mostly about the size of the quality problem, not about whether a review gate helps.

Worth noticing which way the good evidence points. The best-supported findings are not about the model's code being bad. They are about the human losing the ability to judge it — believing you were faster while being slower, believing the code was secure while it was less so, absorbing more review burden as more work arrives. Those are findings about the arrangement rather than the tool, which makes them the empirical case for engineering-driven AI specifically, not a general case for being careful.

Which points at the right way to decide: run pushback on a spec you already believe in and see what comes back. One such result on your own work will tell you more than this entire page.

What was reviewed

The subject is a browser application built around a deterministic simulation, with a React and three.js interface. Its central design idea is that the save file is the history: the simulation records every action taken, and rebuilds the current state by replaying that list from the beginning. The report calls one replay a rewalk, and the promise the whole design rests on is that a rewalk produces exactly the state that live play produced.

How the review was run

The report is the output of /agentic-architecture: five specialists working in parallel, each with one narrow brief, then a separate verification pass that reads the actual code and the git history and discards what it cannot substantiate. Module 8 names the five specialists and what each one looks for.

The specialists produced 79 raw findings between them. Verification brought that to 50: 33 flaws and 17 strengths. Most of the 29 that went were the same problem found by more than one specialist and merged into a single entry; a smaller number were false positives dropped after the verifier read the code.

The four High-severity flaws

Read the four together before reading them separately, because the shape of the group is the most useful thing in the report. Three of the four are about the save file. The fourth is that the layer holding the save file has no tests. These are not four unrelated defects; they are one untested area and the three problems that grew in it.

F1 — Replay can produce a different result from live play

When two events can legally resolve at the same moment, the code resolves them in the order the two blocks happen to be written in, rather than in the order the events occurred. Playing forward in small time steps reaches one of them first. Loading a save, or using a "skip" control, jumps the clock in a single step and reaches the other first. The two paths then produce different outcomes — a different result, recorded at a different time, with different consequences downstream.

The report locates this in the settle() function, where one block runs ahead of the other, and in the load path, which sets the clock forward and then advances by zero — which is what routes a load through the same branch a skip uses. The verifier confirmed it by replaying the scenario from beginning to end rather than by reading alone.

Why it is High: it contradicts the invariant the architecture is built on. It also contradicts the project's own architecture decision record, which specifies resolution in time order. One of the two is wrong, and nothing in the codebase notices the disagreement.

F2 — The version number covers the envelope, not the contents

The save file carries a version number, which has never been incremented, while the set of recorded action types grew from eight to sixteen. The deeper problem is that the real format is larger than the file. Because loading means replaying, every recorded action is re-checked against today's tuning constants and content rules. Adjust a balance value — which the project's own steering file describes as "a data change" rather than a code change — and actions that were legal when they were recorded are no longer legal, so the replay fails.

Why it is High: a routine content change invalidates existing saves, and the version number, which is the one mechanism that exists to detect exactly this, does not move.

F3 — A save that fails to load is discarded, then overwritten

The load path wraps everything in a single catch that returns nothing. The code underneath it produces genuinely useful diagnostics — unknown save version, delta log epochs must be non-decreasing — and every one of them is thrown away at that boundary. Nothing is logged, copied aside, or quarantined. A fresh session is created instead, and the automatic save, which runs every 30 seconds, writes over the unreadable file under the same key.

Why it is High: put F2 and F3 together and the mechanism is complete. A balance change makes the save unreplayable, the error explaining why is swallowed, and the file is overwritten within half a minute. The user's data is gone, and no signal was produced at any point in that sequence.

F4 — The layer where the first three live has no tests

All 154 tests are in the simulation layer, where they reach roughly 92% of statements. The state layer — save, load, skip, automatic save, and the code that runs when the module is first imported — has none. F1's trigger and F3's swallowed error both live there.

Why it is High: on its own this is not a defect at all; it is the reason the other three could exist without anyone noticing. The suite is thorough about the layer that is pleasant to test, which is the layer that was already deterministic and already correct.

The other twenty-nine

Listed by the report's own titles, grouped by severity. They are worth skimming rather than studying: the point is the texture of what accumulates, not any individual entry.

Seventeen Medium

Twelve Low

Read down the list and the same few kinds keep appearing. Simulation rules copied into the interface, where they can drift apart silently: F11, F12, F22, F24, F32. Missing coverage: F21, F29, and F4 above. Unexplained literal values: F23, F31. Structural growth pressure on one or two files: F7, F8, F18. None of these names is invented for the occasion — they are categories from the 34 flaw types the architecture specialists work through, which is why the report can be compared against the next one rather than read as an essay.

What the same review found working

The report records strengths as well, and deliberately so — Module 8 explains why. Omitting them here would misrepresent a report whose verdict was mixed rather than damning.

Two of those are worth holding next to the flaw list. S11 says the simulation fails fast and detects corruption at its edges — and F3 is the load boundary throwing those detections away. S16 credits the versioned save with its migration switch — and F2 is that version number not covering what actually varies. In both cases the mechanism was built. What was missing was the check that it still did the job.

Where the risk concentrated

Every architecture report ends with a hotspots list, which is the part to read first if you only read one. This one names three.

What to take from this

None of the 33 is "the program does not work." The article is explicit that the model "had no significant problems in creating the software in a few hours." What the review found is inherited risk: things that are fine today and expensive at the point where somebody changes a balance value, or adds the seventeenth mechanic, or resumes a save on a second device.

The flaws cluster where the tests are not. That is the single most reusable observation in the report, and you can check it against your own codebase this afternoon without running anything: find the layer with no tests, and it will be the layer where the model was least constrained and least often corrected.

The report ends in questions, not patches. Its last section is five questions for the author — is the F1 scenario reachable in normal play; should a rebalance break old saves or not; is direct access to the live simulation sanctioned or not. That is agentic-architecture being diagnosis only, which Module 8 covers: several of these are decisions somebody has to make, and a tool that quietly picked one would be removing the choice rather than surfacing it.

Two of the four High flaws are contract questions. What does a version number promise? What does a save guarantee about a future release? Those are answerable in a paragraph before any code exists, and they are exactly the kind of question pushback asks of a specification. By the time they appear as F2 and F3 they are a load path, an automatic save timer, and a data-loss sequence — which is Module 2's cost gradient, visible in one codebase.

Everything else in this course is about putting a review gate somewhere. This page is about the one variable that decides whether the gate works at all: how much you ask it to look at.

The number you half-remember is real

Most engineers have absorbed a rule of thumb along the lines of "review quality collapses somewhere past a few hundred lines." Almost nobody can cite it. It comes from two places, and they agree with each other more closely than you would expect.

The first is Karl Wiegers' 1995 write-up of inspection practice, which converts a reading-rate finding into a size limit:

Data in the software literature indicates that slowing the preparation and inspection rates increases the number of bugs found, with the optimum balance around 150–200 lines of code per hour. […] This rule limits the quantity of material that can be covered in a single inspection to about 8–12 pages of design or text documents, or 300–400 lines of source code.Karl Wiegers, "Improving Quality Through Software Inspections", Software Development, April 1995

Note the second half of that sentence, because it is the part this appendix is actually about: the same constraint that caps a code review at 300–400 lines caps a document review at 8–12 pages. The limit was never specific to code. It is a limit on how much material a reviewer can hold in mind at one time, and a specification is material.

The second source is the largest study of lightweight code review ever run: SmartBear's case study at Cisco Systems, covering 2,500 reviews of 3.2 million lines of code by 50 developers over ten months ending in May 2006. Its findings on size:

What contemporary practice converged on

The stronger evidence is not a threshold study at all. It is the observation that when many independent organisations moved from formal inspection to lightweight review, they all converged on roughly the same size — without coordinating, and without citing Wiegers.

Rigby and Bird measured this across open-source projects and industrial ones, and the medians are startling if your mental model of a code review is a big pull request:

Their reading of it is the useful part: "By creating smaller changes, developers can work in shorter intervals," and the distributions are left-skewed, meaning "the majority of changes are small" was the norm rather than the exception. Only 23% of Chrome changes were as large as a median Lucent inspection.

A CL, or "changelist", is Google's term for one reviewable change — their equivalent of a pull request. Google's published guidance says the same thing prescriptively, and adds the dimension that a line count misses:

Small, simple CLs are: Reviewed more quickly. […] Reviewed more thoroughly. […] Less likely to introduce bugs.Google Engineering Practices — Small CLs

There are no hard and fast rules about how large is "too large." 100 lines is usually a reasonable size for a CL, and 1000 lines is usually too large, but it's up to the judgment of your reviewer. […] A 200-line change in one file might be okay, but spread across 50 files it would usually be too large.Google Engineering Practices

Note that Google refuses the thing this appendix is doing — it will not treat a line count as a threshold, only as a prompt for a reviewer's judgement. That is the honest reading, and it is compatible with the argument here: what follows is a ceiling past which the evidence says review degrades, not a number to enforce.

The automated reviewer has the same problem, for different reasons

The obvious hope is that agentic-review escapes all of this. It does not get tired, it does not skim, and it will read the ten-thousandth line as carefully as the first. Two of those three are true, and the third is the one that matters.

Model review degrades with size too, through three mechanisms that compound:

The first two combine in a particularly damaging way. Suppose a review pass catches any given defect with probability p, and your branch contains n of them. You expect to miss (1 − p) × n. Doubling the size of the change roughly doubles n — and, because the input got longer, lowers p at the same time. A big diff fails twice over: more to find, and a worse chance of finding each one. That is the whole argument in one line, and it applies to the human reviewer and the model reviewer alike.

Which is why this is a spec problem

Diff size is not something you decide at review time. By the time you are running agentic-review you cannot shrink the thing you are reviewing; you can only scope the review and compensate. Diff size is decided much earlier, and mostly by one document.

Module 2's blast-radius hierarchy, restated in units of review load:

An oversized spec is not a documentation problem. It is a commitment, made before any code exists, to a review you will not be able to perform properly. That is the cheapest possible moment to fix it and the last moment at which fixing it is free.

But size is the alarm, not the place to cut

Here is where this appendix has to argue with itself, because PAAD's own pushback skill contains a rule that looks like a direct contradiction of everything above. From Module 6:

Size alone is never the argument. If a meaningful split exists where each piece delivers independent value, it suggests the split. If the features are genuinely interdependent, it flags the size and explains why splitting is not practical, then moves on.Module 6, on pushback's phase 1.5

That rule is correct and this appendix does not overturn it. The two fit together once you separate detection from decomposition:

Cut a long spec at an arbitrary point and you do not get two reviewable specs. You get two specs that cannot be understood or shipped without each other, which is worse than one long one: you have hidden the coupling instead of removing it, and now two review passes each see half a picture. Length tells you to go looking for a seam. It never tells you where the seam is.

Where the seams actually are

Four decomposition strategies, in rough order of how often they work.

Order the pieces, do not just pile them up

A split spec is a chain, not a heap. Each piece should name the piece it depends on, and they should be built in that order — the same principle alignment applies when it presents issues root-cause first, and the same reason fix-architecture refuses to parallelise structural fixes. Dependencies you do not write down get discovered during integration, which is the expensive place to discover them.

Google's stacked CLs pattern is the mechanical version: write one small change, send it for review, and immediately start the next one based on it. Specs stack the same way.

A worked example

Take the data-export feature from Module 7 — the one with the Redis cache nobody asked for. As a single spec it is three requirements, a background worker, an email path, and a rate limiter: comfortably past the point where one review pass will see all of it.

Three splits that look right and are not

• Splitting by line count. "This is 900 lines, so it becomes two 450-line specs." You have not reduced anything; you have made one artefact into two halves that only make sense together.
• Splitting by file or layer with no shippable middle. "Spec 1: the migration. Spec 2: the endpoint." Neither delivers value alone, so neither can really be reviewed alone — the reviewer of Spec 1 has to imagine Spec 2 to judge it.
• Splitting phases of one coherent feature into separate specs. pushback's own documentation warns against mistaking sequenced phases of a single feature for bundled unrelated features. Phases are a task-list structure. They are not independent value.

When it genuinely cannot be split

Then compensate downstream, deliberately and in writing:

• Say so in the spec. One paragraph naming why the pieces are inseparable. This is the thing a reviewer most needs and least often gets.
• Scope the reviews. agentic-review takes a path: /agentic-review main src/auth/. Several scoped passes over a large branch beat one pass over all of it, for exactly the context reasons above.
• Run more passes. Module 10's rule applies with more force here: a pass returning many findings means more remain hidden behind them. On a large branch, expect to need three passes where you would normally run one.
• Stage the branch even though the spec is whole. An unsplittable spec does not always imply an unsplittable branch. Stacked commits, reviewed in order, recover most of the benefit.
• Insist on the human pass. This is precisely the case where the automated safety net is weakest and where "the AI found no problems" carries the least information.

The counter-argument, which is real

Splitting is not free, and a page that only argued one side would be the kind of unchallenged input this whole course is against.

Which is why the rule is a search for a seam rather than an instruction to split. The claim is not "smaller is always better." It is that past a certain size your review stops being reliable, and you should know that you have crossed the line rather than find out afterwards.

How good is this evidence?

The practical conclusion survives all of those caveats intact, because it does not depend on the threshold being exactly 400. It depends only on the direction — reliability falls as size rises, for both reviewers you have — and on the observation that the cheapest place to act on that is the document you write before any code exists.

The teams I have run this material with rate the sessions highly. That is worth saying plainly, because it makes the first explanation anyone offers — that the material was unclear — an unlikely one. It also cannot settle the question. A rating collected at the end of a session measures how the session felt, not what anyone can still do a month later, and the evidence appendix is sceptical of self-reports for exactly that reason. What I see when I go back is not confusion about the method. It is that people returned to the deadlines they already had, and a method you understand is not yet a method you can perform.

The preamble names the organisational reasons adoption stalls: mismatched expectations, unclear ownership, a senior engineer who is not yet convinced. Those are real. This appendix is about a cause that sits underneath them and is easier to fix — the practice has simply not been performed enough times to be available under pressure. Engineers know this about every other skill they have. Nobody expects to read a debugger's manual and then use it well. It is easy to forget here, because the material is easy to read, and material that is easy to read feels finished.

1. Understanding it and being able to do it are different things

This is what stops teams most often, and it is the hardest thing to see from the inside. A new practice competes with an old habit at the worst possible moment: the point where the work is late and there is the least room to stop and think. At that moment people do what they can already do without having to decide. Reading that you should argue with an agent's plan is one skill. Doing it on a feature that is already late is a different skill, and it is built the way skills are always built — by repetition, on real work, with someone watching the first few attempts.

So do not try to strengthen anyone's intention. Remove the decision instead. Module 5 asks for one documented command for testing, one for linting and one for coverage, and it is explicit that the value is not the tool: it is that developers and agents run the same quality checks through the same commands. The same reasoning applies one level up. Put agentic-review into whatever your team already treats as the list of things that must happen before a merge — the pull request template, the review checklist, the list that a team agrees describes finished work. The aim is not to make skipping the review impossible. The aim is to make skipping it a visible act rather than a silent one.

Then practise once, before it matters. Module 11 sets out a first two weeks for one person. The team version of day 2 is worth doing together: take a spec somebody on the team wrote and is happy with, run pushback on it in a shared session, and read the findings aloud. The findings are not the point. The point is that everyone has watched a colleague disagree with an agent, once, with other people in the room, before they have to do it alone under time pressure.

2. One project truth, more than one place to keep it

Module 3 sets out where each tool keeps its project context — CLAUDE.md, .cursor/rules/, .kiro/steering/, .github/copilot-instructions.md, a Spec Kit constitution — and gives the documented fix for the commonest collision: Claude Code does not read AGENTS.md, so CLAUDE.md imports it with a single @AGENTS.md line, or is a symlink to it. PAAD adds no steering format of its own; it reads whatever your tool already reads.

That fix is a paragraph in Module 3 and a decision nobody makes. It is worth making deliberately, because the number of places project context can live grows quietly: a second editor, a colleague who prefers Cursor, a Copilot user, a bot in CI. Each arrival is reasonable on its own, and each one can bring a second document describing what the project is. Module 3 names the real problem exactly — two steering files that slowly start contradicting each other — and Module 5 gives the cost: a wrong statement in a steering file is inherited by every single piece of work that follows. Two files that disagree is that cost, plus the question of which one is wrong. Nothing will tell you. The divergence makes no noise, which is the same reason Module 5 asks you to read each line and check whether it is still true.

So choose one canonical document and make every other location point at it rather than repeat it. AGENTS.md is the reasonable default: it is tool-neutral, read natively by around 25 coding agents, and Module 3 gives both patterns for connecting Claude Code to it. Then check occasionally that the pointers are still pointers. A copy made once, just for now, becomes invisible the moment it is committed.

None of this is a PAAD decision. It is a decision about your repository, and it needs somebody to make it rather than being settled by whoever configured their editor first. It is also the arrangement PAAD's own skills look for: agentic-review and agentic-architecture both scan for CLAUDE.md and AGENTS.md by name before they dispatch anything.

3. Nobody has reviewed your steering file

Steering sits above specs in the cost hierarchy, so getting it right pays off across everything written afterwards. In most teams I have worked with it is also the document nobody has reviewed: written once during setup, by one person, and relied on by everybody since.

It is worth knowing where PAAD does check it, because it does. agentic-review, agentic-architecture and agentic-a11y all read the steering files before dispatching their specialists, and every specialist prompt carries the same instruction:

Steering files (CLAUDE.md, etc.) describe conventions but may be stale. If you find a contradiction between steering files and actual code, flag it as a finding.agentic-review, v1.24.1 — the same caveat appears word for word in agentic-architecture and agentic-a11y, and in paraphrase in agentic-dedup

That is a check against the codebase, which is the only place most steering claims can be tested at all: “we use dependency injection here” is true or false relative to the code, and reviewing the document with nothing to compare it against would be guessing. So the placement is sensible. What no skill's stated scope covers is a review of a steering file as a document, before anyone relies on it — pushback's description names “a spec, PRD, requirements doc, or design plan”, and steering is not in that list. Nothing stops you from pointing pushback at one; that is your judgement rather than the skill's stated scope.

Two things follow, and both need an owner:

• Read the steering files yourself, on a fixed date. Module 5 gives the test: line by line, is this still true. Do it before the first spec, then put the next pass in the calendar, because nothing else will remind you. A steering file that has gone out of date still loads without complaint.
• Treat a steering contradiction reported by agentic-review as a finding about the steering file. It arrives inside a report about a branch, which makes it easy to read as noise attached to somebody's diff. It is the cheapest correction PAAD will hand you: one edit, and everything written afterwards starts from the corrected version.

4. The architecture pass that is scheduled for “later”

Module 8 is careful to say that agentic-architecture is not a gate: it is a diagnosis you run periodically, rather than something every feature passes through. Module 11 adds when to start — once the rest feels routine, and only when you are ready to act on the results, because a report you ignore is worse than no report. Both statements are right, and together they are the sentence teams use to postpone the pass indefinitely. “Later” is a plan only once it has a date.

Postponing it is different in kind from skipping a gate, and the difference is worth stating. pushback, alignment and agentic-review all act at or before the moment code arrives, so they slow down how quickly new debt accumulates. agentic-architecture is the step that gives an experienced developer a way to manage the debt that is already in the codebase. Leave it out indefinitely and you keep the part of PAAD that slows new debt while losing the part that addresses what is already there — which is usually the part that made an established team interested in the first place.

Attach the pass to something that already recurs — a release, a quarter, whatever planning cycle you have — so that running it does not depend on one person arguing for it each time. Decide before you run it who owns the report and how much time is set aside to act on it, and reserve that time in the same conversation. fix-architecture works one flaw at a time, test-first, on a feature branch, and is resumable across sessions (Module 8). That is a body of work rather than an afternoon, and the time for it is much harder to find once the report already exists than before.

5. On an inherited codebase, the order is what slips

Module 11 gives a six-step sequence for bringing PAAD to a codebase that already exists: commit the artefacts, validate the steering, build a suite that pins current behaviour, take an architecture baseline and argue with it, work the resulting roadmap, and supply the judgment none of it can. Most teams that adopt PAAD are adopting it into a codebase like this. The sequence is not difficult and it is not controversial. What happens to it is that the order changes.

It changes in a predictable direction. agentic-architecture is the interesting step — it produces a document, it produces it quickly, and it makes visible something everybody already suspected about the codebase. Step 3 is the opposite of interesting: it is weeks of writing tests that assert behaviour you know to be wrong, producing nothing anyone can demo. So the baseline gets run first, the report exists, the report is right, and now there is a prioritised list of structural fixes and no safety net to make any of them on. At that point the team either stops, or starts refactoring without tests — which is the failure this whole method was assembled to prevent.

So make the safety net the visible thing. test-roadmap is unusually well suited to being tracked in public, because it reports where it is at the end of every run — Phase 8 of 14 — 7 done, 6 to go — and each phase lands as its own commit. Put that fraction wherever your team already looks at progress. A number that moves every few days survives a planning conversation; "we are writing tests" does not.

Two smaller items in that sequence also need somebody to decide them once, for everyone:

• Whether AI artefacts are committed. Module 11 makes this a strong default rather than an absolute, which means it is a decision, which means it needs to be made deliberately rather than by whoever creates the first report. Agree it once, write it in the steering file, and settle the one exception PAAD names for itself — security entries in a review backlog on a repository that is public or shared outside the team — before the first push rather than after.
• Who reads the architecture report. Step 4 asks you to run pushback on it and then bring what the tooling could not see: the outage behind the retry loop, the constraint that made a class ugly on purpose. That is not a review anybody can do from the report alone. It wants the person with the longest memory of the system, and an hour of their time booked in advance.

What the extra work actually is

Written out, the whole of it is smaller than most teams expect. That is an argument for planning it rather than for skipping it: work this small is exactly the kind that never acquires an owner. The times below are my own rough estimates from doing this with teams, not measurements.

None of that is difficult and none of it is surprising once it is written down. The reason to write it down is that every line of it is work with no default owner, and a method with no owner stays in the training material. If you would rather not do it alone, the preamble says where to find me. If you would rather do it yourself, everything on this page is something you can run without me — the only real failure is assuming it will happen without anybody doing it.

PAAD itself

Working with coding agents

Spec-driven development

Software-engineering terms the course assumes

Research terms, used only in the evidence appendix