0001 · The Thesis & the Four Failure Modes

You already run skills daily, so we skip the "what is a skill" preamble. The question worth your time is narrower: what does Pocock's repo believe that a pile of ad-hoc skills doesn't? Get the thesis and its four target failure modes into memory, and every individual skill in the repo stops looking like a list and starts looking like a plan.

The thesis. Frameworks like GSD, BMAD, and Spec-Kit help by owning the process — and in doing so take away your control and make bugs in the process hard to resolve. Pocock's bet is the opposite: skills should be small, easy to adapt, and composable, working with any model. You keep the wheel; the skills are hand tools, not an autopilot.[readme]

That single design choice explains the repo's shape. There is no monolith. There are ~40 tiny SKILL.md files, each doing one thing, that you wire together and hack on. The composition is yours. Hold onto the word composable — it is the load-bearing idea, and the reason adopting a couple of these into your Pi setup is even coherent: they were built to be lifted out one at a time.

The four failure modes

The README is organised around four ways agent-assisted development goes wrong. Each failure mode names a fix, and the fix is a skill (or a document). This is the spine of the whole repo — learn it as a four-item list and you can place any skill you meet later.[readme]

#1 — The agent didn't do what I want (misalignment)

The oldest failure in software: you thought the builder understood you; they didn't. Pocock quotes Pragmatic Programmer — "No-one knows exactly what they want."[pragprog] The fix is a grilling session: the agent interviews you, relentlessly, until the intent is pinned down before any code exists. Skills: grill-me (non-code), grill-with-docs (code + shared language). These are his most-used skills — meant to run every time you make a change.

#2 — The agent is way too verbose (no shared language)

Dropped cold into a project, an agent uses 20 words where 1 would do because it hasn't learned the project's jargon. The fix is a shared language — Evans' ubiquitous language from DDD[ddd] — captured in a CONTEXT.md. "There's a problem when a lesson inside a section of a course is made real" collapses to "there's a problem with the materialization cascade." Fewer tokens, consistent naming, easier navigation. Built into grill-with-docs and domain-modeling.

#3 — The code doesn't work (no feedback loops)

Even aligned, the agent flies blind without feedback on how its code actually runs. The fix is the usual tranche — types, browser access, tests — and above all a red-green-refactor loop: write the failing test first, then make it pass. "The rate of feedback is your speed limit."[pragprog] Skills: tdd, and diagnosing-bugs for hard bugs.

#4 — We built a ball of mud (no design)

Agents accelerate coding — so they also accelerate entropy. The fix is caring about design every day: Ousterhout's deep modules[aposd] (lots of behaviour behind a small interface) and Beck's "invest in design every day."[xp] Skills: to-spec quizzes you on which modules you're touching; improve-codebase-architecture rescues a codebase already turning to mud.

Notice the pattern: every fix is grounded in a book, not a vibe. The repo's tagline is "Skills For Real Engineers" — the claim is that agent-era engineering rewards the same fundamentals (alignment, shared language, feedback, design), just under more pressure because the code arrives faster.

Check yourself

What is the core design bet that separates this repo from GSD / BMAD / Spec-Kit?

The frameworks own the process and cost you control. Pocock keeps skills small, adaptable, and composable — you wire them together and stay at the wheel.

Which failure mode does a shared-language CONTEXT.md primarily target?

Verbosity (#2) comes from missing shared language. A CONTEXT.md gives the agent a ubiquitous language so one term replaces a paragraph.

Which pairing of failure mode → fix is correct?

Ball of mud (#4) is fixed by caring about design — deep modules, surfaced by to-spec and rescued by improve-codebase-architecture.

Primary source

Read the repo README top to bottom once — specifically the "Why These Skills Exist" section. It is the four failure modes in the author's own words, with the book quotes inline. Everything after this lesson hangs off that section.[readme]

Ask me anything. Some good follow-ups from here: "Which of the four do I hit most often in my own Pi work?" · "Show me a real grill-with-docs run" · "How is this different from just writing a good AGENTS.md?" Or say next and we'll walk the engineering flow end-to-end (grill → spec → tickets → implement → review) in Lesson 02.