A Skeleton That Compiles Is Not a Feature

There’s a satisfying moment in a new project where the skeleton comes together: the folder layout mirrors the spec, the entrypoints are wired, the pipeline goes green, and every requirement has a place to live. It looks done. It is not done. A scaffold full of debug placeholders is the easy part of the work wearing the costume of the finished thing, and one of the more useful honesty checks I run on myself — and on status reports — is refusing to count a compiling skeleton as a feature.

Scaffolding is the cheap, satisfying part

Setting up structure is genuinely fast and genuinely pleasant. You get to make a lot of green checkmarks: the roles exist, the entrypoints resolve, the config is templated, the layout maps one-to-one onto the requirements list. That mapping is seductive because it makes the project look proportionally complete — every scope item has a corresponding file, so it feels like you’re most of the way there. But “there’s a place for this to go” and “this does the thing” are different states separated by most of the actual effort.

A clean skeleton that maps to every requirement is the most convincing not-done a project ever looks.

Placeholders pass checks and do nothing

The specific trap is that scaffolding often passes. A role whose task is a debug message runs fine. A config loop that iterates over an empty default applies nothing and reports success. A syntax check is happy because the structure is valid. So all your signals — it builds, it runs, the layout’s complete — light up green while the system does, functionally, nothing. The checks are confirming the scaffold is well-formed, not that the feature exists. If you read “passes” as “works,” the placeholder fools you exactly when you most want reassurance.

”The mechanism is there” is not “it’s implemented”

The sneakiest version is a mechanism that’s wired but inert. A configuration loop that would apply settings, with no settings defined yet — present, plausible, and a no-op. It’s easy to glance at that and tick the box, because the machinery is visibly in place. But scaffolded-and-empty is still empty. The honest status is “the mechanism exists; it isn’t doing anything yet,” and the gap between those two sentences is usually where the real work lives. I’ve learned to write the status that way on purpose, because “it’s scaffolded” and “it’s implemented” get conflated constantly, almost always in the optimistic direction.

Report the truth, especially to yourself

When I caught myself sitting on exactly this — a collection whose structure lined up perfectly with the spec but whose logic was all debug stubs — the valuable move was to say so plainly: the skeleton is done, none of the actual scope items are functionally implemented yet. That’s not a discouraging admission, it’s an accurate one, and accuracy is what lets you plan the rest. The alternative — counting the scaffold as progress — quietly front-loads a sense of completion that the project hasn’t earned, and the bill comes due later as “wait, why is none of this actually working?”

A couple of guards that keep me honest:

• Distinguish “has a home” from “does the work” in any status. A requirement with a file is addressed in layout, not in function.
• Don’t let green checks mean more than they do. Builds and syntax checks validate form; they say nothing about whether the behavior exists.
• Treat inert mechanisms as unimplemented. A loop over nothing, a handler that logs and returns — those are placeholders, and placeholders are todo items.

Scaffolding earns its keep — as a start

None of this is an argument against scaffolding. Standing up clean structure first is good practice; it gives the real work a place to land and surfaces the shape of the problem early. The discipline is just to label it correctly: the skeleton is the start of the work, not a slice of the deliverable. Build it, be glad it’s tidy, and then resist the urge to mark the feature done because its outline exists. It’s the same honesty I try to bring to remembering that a job running isn’t a job working and that you should stop extrapolating and build the rehearsal. If you’ve caught yourself mistaking a scaffold for a finish line, you’re in good company — say hi.