With rules, workflow definitions, and execution hooks already governing AI output, what gap does SPDD actually fill — tighter coupling between prompt and code, versioning that prevents drift over time, or both?

Both, and they reinforce each other. Global rules and hooks are a valuable high-level safety net, but in day-to-day engineering they sit at a level of abstraction that leaves the actual generation step opaque. Here is how SPDD fills the gaps that high-level guardrails alone do not close:

• Finer-grained control over intent. High-level rules describe broad strategy and boundaries, but they leave the generated code as a black box. SPDD makes the problem-solving steps explicit through the REASONS Canvas — intent, design, execution, governance — so reviewers can reason about the plan before the code, and humans stay in the loop where it matters.
• Reusable intent assets. Ad hoc prompts are single-use. SPDD turns structured prompts into version-controlled artifacts that travel with the code, capturing business intent, design decisions, and constraints. That is what closes the loop between prompt and code over time and prevents the slow drift that happens when only the code is maintained.
• A framework for human learning. If we let the model produce code unsupervised, our own modelling and abstraction skills weaken over time. SPDD forces developers to reason about the problem alongside the tool, so domain knowledge and design judgement compound across iterations rather than being lost after each chat.

How does this differ from traditional instruction sets placed within projects/solutions using progressive disclosure?

The core difference is that SPDD treats the structured prompt as a maintained, version-controlled file:

• Fixed structure instead of free-text rules. Rather than feeding the model open-ended instructions, we use the REASONS Canvas — a fixed seven-part template covering intent, design, execution, and governance. The AI must plan inside that shape, which makes the plan readable and reviewable in a consistent way across the team.
• Intent before code. The commands clarify requirements, domain, and approach before generating anything — moving uncertainty to the left. Disagreements get resolved at the prompt level, where they are cheap to fix, instead of surfacing later in the code.
• Task breakdown via Operations. The canvas's O — Operations dimension decomposes the abstract strategy into concrete, testable implementation steps — down to method signatures and execution order. Reviewers check these steps before any code is written, so generation becomes a faithful translation of an already-agreed plan.
• Two-way sync, not handoff. Traditional in-project instructions and design docs go stale the moment the code moves on. In SPDD the prompt and the code are tied together: when business rules change, /spdd-prompt-update flows requirements → prompt → code; when the code is refactored, /spdd-sync flows code → prompt. The spec stays an accurate record of the current system rather than a historical snapshot.

Humans build the “why” behind decisions through discussions and accumulated context, not just the final code. Does SPDD close that loop with automated learning, or is the “why” still carried by humans?

It depends on what we mean by “closing the loop.” If the question is whether SPDD has a closed AI learning loop — where every chat silently teaches the model and the system gets smarter on its own — then honestly, not yet, and we are deliberate about that. openspdd runs as a semi-automated, human-led framework, and humans remain the gatekeepers for all core decisions.

But the “why” itself does not stay locked inside human heads or scattered chat logs. It is captured in the structured prompt as a first-class artifact:

• The Canvas encodes the rationale. R (Requirements with DoD), A (Approach), and the Step 3 analysis context explicitly record what we are solving, why, and which trade-offs we accepted — not just what to build.
• Version control makes it durable. Because prompts are committed alongside the code, the “why” travels with the system across people and time, instead of being lost when a chat window closes or a developer leaves the team.
• Two-way sync keeps it current./spdd-prompt-update flows requirements → prompt → code when intent changes; /spdd-sync flows code → prompt when implementation changes. The artifact stays an accurate record of the current system, not a historical snapshot.
• Each iteration starts from accumulated assets. The next enhancement begins with the existing Canvas as context, so domain knowledge and design decisions compound rather than getting rediscovered each cycle.

So the loop is closed by the workflow and the artifact, not by an autonomous learning mechanism. Reviewers shift from “spot the bug” to “check the intent” because the intent is now somewhere they can inspect. That is a human-led design by choice, and we think it is the right one for now — until automated verification at the asset layer matures enough to take on more of the load.

If two developers writing the same Canvas can produce different specs — and there is no formal definition of “good” — doesn't SPDD just push the variance problem up a layer rather than solve it?

Honestly, that's a fair characterization of where we are today. The Canvas narrows the band of variance compared with free-form prompting, but it does not eliminate it. Two developers writing against the same requirement can still produce different Canvases, and the same developer can produce a thinner one on a different day. We don't yet have a crystallized, objective standard for what a “good” Canvas looks like.

What the framework relies on right now is a set of baseline criteria — structure, granularity, level of abstraction, and task breakdown — codified into the openspdd commands. Each command encodes a thinking strategy that pulls the output toward a consistent shape, which raises the floor for less experienced practitioners and gives reviewers a fixed thing to react to. That is a meaningful reduction in variance, but it is not the same as an external, automated check.

Closing that remaining gap is where governance needs to go next: automated verification at the asset layer (analysis, Canvas, prompt artifacts) so the framework itself catches the cases where a Canvas is structurally complete but substantively under-specified. Until that exists, the honest answer is that human judgement is still load-bearing.

How does SPDD hold up as you scale it across multi-project, multi-discipline, multi-domain work — and where does the real ceiling sit: in the AI's capability, or in how cleanly the problem itself can be bounded?

The limit is mostly on the problem side, not the model side. Even with a stronger model or a better learning loop, we would not recommend handing a massive, multi-project, cross-domain scope to the AI in one shot. What matters more is how clearly the problem is bounded and how much prior context the team has accumulated; raw model capability is rarely the bottleneck. Three reasons:

• Decomposition is required. Large or cross-domain scope is better broken into smaller, self-contained units that can be modelled accurately one at a time. Without this discipline, even a strong model loses coherence as the scope widens.
• Unclear boundaries cap the success rate. In “context black holes” — domains where business rules are unclear and boundaries are weak — SPDD's success rate drops because the model has nothing meaningful to constrain it. A more powerful AI does not fix this; it just fails more confidently.
• Decision assets help over time. End-to-end portfolio-scale work is not something we would hand off autonomously today. That changes once enough “decision assets” — historical context, architectural choices, normative patterns — have accumulated to raise the success rate to an acceptable level. Until then, the human-led, unit-by-unit approach is the default.

Is SPDD model-agnostic? Does accumulated prompting behave equivalently across Claude, GPT, and Gemini, or could a model change between iterations — switching providers, going local-offline vs remote-online, or a provider update altering reasoning behavior — introduce prompt drift or code divergence? Is the real artifact prompt-as-spec, or prompt + model configuration?

SPDD is intended to be model-agnostic, and we have applied it across model generations since the Claude 3.5 Sonnet era. The workflow does not depend on any single model. That said, raw capability still matters: stronger reasoning models simply produce better canvases.

From hands-on experience, for the heavy-lifting analysis and REASONS Canvas generation steps, Claude (especially Opus) tends to lead, followed by GPT Codex and Gemini 3.x Pro. Once intent is locked into a structured prompt, however, the next phase is largely instruction-following, so swapping to a slightly less capable model carries a manageable risk of intent drift. Viewed this way, the artifact is the spec; the model is the executor of that spec.

On local-offline vs remote-online: today we do not recommend local-offline LLMs for SPDD. The small models that fit on local hardware lack the capability needed for the analysis and canvas-generation steps, and deploying capable large models locally is rarely cost-effective.

So SPDD does not guarantee absolute determinism, and we do not claim it does. What it does is keep the randomness of the LLM's non-determinism within controllable bounds. Whether you treat the artifact as prompt-as-spec or prompt + model configuration is a strategic call tied to your cost, compute, and compliance constraints — and one teams should make consciously.

As LLM capabilities have advanced, has the SPDD method itself changed — or only how practical it is to apply?

The method hasn't fundamentally changed. The core loop is still the same: anchor everything on the structured prompt, and use it to progressively clarify intent.

What has changed is how much of that manual effort we can hand off to repeatable tooling on top of the LLM. As the models got better at following structured prompts and reasoning over richer context, we distilled each step of the workflow into a reusable thinking strategy — commands like /spdd-analysis, /spdd-reasons-canvas, /spdd-generate, and /spdd-sync. Three things came out of that:

• From template-driven to strategy-driven. Earlier on, SPDD relied heavily on solution templates: without a well-summarized template up front, output quality dropped, which made starting on a new domain difficult. Now each command encodes the thinking strategy itself, so even with no template the LLM can follow the strategy to produce a reasonable first cut. We refine from there, and once enough cases have gone through the same strategy, a template emerges as a byproduct — so the asset is built up by use rather than required before any work can start.
• Higher automation. Steps that used to be driven manually with ad hoc prompts are now invoked as commands, so the workflow runs with far less hand-holding.
• More stable outputs. Because each command encodes the same thinking strategy every time, the artifacts it produces — the analysis, the REASONS Canvas, the generated code — are far more consistent run to run, and therefore easier to govern and review.

As the human “lead”, how do you judge when additional prompt engineering is needed over the same portfolio scope?

I rely on three concrete triggers, and they map directly to the review steps in the SPDD workflow:

• Behavioral mismatches. During functional testing (typically with /spdd-api-test), I focus on system behavior rather than implementation detail. If the output deviates from the defined acceptance criteria, that's a signal the prompt didn't capture the intent precisely enough — a classic logic-correction case where we update the prompt first, then update the code.
• Overcomplicated logic. When reviewing critical code, if the AI has engineered a solution that is more elaborate than the problem warrants, the prompt's Approach or Operations section is usually under-specified. Tightening those constraints typically simplifies the next generation.
• Instruction failures. When the AI fails to follow explicit instructions or violates a Norm or Safeguard from the canvas, I treat it as a signal that the constraint needs to be made more prominent or unambiguous in the prompt itself, rather than fighting the same battle again in chat.

Why does SPDD's workflow have six steps instead of the simpler plan-then-code pattern? Couldn't intent just be confirmed once, in a single review after the plan is generated?

The short answer is cognitive load. Intent confirmation has to be distributed across the workflow, because compressing it into a single review after plan generation puts too much in front of the reviewer at once. In practice, people can't sustain that level of attention — they skim, defer, or approve by default — and intent drift becomes inevitable even when everything looks correct on paper.

The six steps exist so each checkpoint stays small enough to actually engage with:

• Step 1 shapes the raw idea into a user story (optionally with AI assistance), and Step 2 is where the human reviews and clarifies what that story actually means in business terms — anchoring on the right problem before any design work begins.
• Step 3 confirms the domain understanding, risks, and strategic direction — the “why” and “what”.
• Step 4 confirms the structured prompt — the design and operations — only after the analysis is agreed.
• Step 5 confirms behavior and code only after intent is locked.
• Step 6 generates unit tests last, once the implementation is stable.

By the time reviewers are looking at code, the requirements, domain model, and design have already been signed off, so attention can go to the decisions that matter at that stage. The point isn't more steps for their own sake; it's narrower decisions per step, so humans can stay in the loop.

SPDD runs API tests before code review but unit tests after — almost the inverse of TDD. Why is that sequence?

This sequencing was deliberate. Classic TDD uses tests to clarify behavior, protect against regressions, and shape design through fast feedback. SPDD still wants all three outcomes — it just distributes them differently across the workflow:

• API tests come first because generated code is cheap. There is little value in deeply reviewing code that may not even satisfy the intended business behavior. /spdd-api-test validates the “what” at the system boundary quickly, so we know we are reviewing something that actually works before investing the human review effort.
• Code review then focuses on what only humans can judge. Once the API tests pass, review concentrates on logic, architecture, trade-offs, and non-functional concerns — not on whether the basic behavior is right.
• Unit tests come last as a regression safety net. By the time we reach unit tests, intent has already been made explicit through the structured prompt, and the implementation has been stabilized through API validation and review. Generating unit tests at this point avoids rewriting them after major review-driven changes.

So tests are not less important in SPDD. The change is that intent is made explicit earlier — through the structured prompt — and tests can be applied at the stages where they create the most leverage.

If hotfixes are rated a poor fit for SPDD, doesn't the highest-signal feedback from production — the bugs, edge cases, and failure modes that triggered the fix — permanently bypass the spec and never make it back into the methodology?

It would, if the workflow stopped at the fix. The 1-star rating in the fitness table is about the upfront fit during the incident itself: during a live production incident, system recovery has to come first, and stopping to write a Canvas is the wrong call. But governance is not skipped — it is deferred by one step. In practice we split hotfixes into two scenarios:

• Scenario A — context exists. If the bug falls inside an area already covered by a structured prompt, we use the AI to analyze the failure, identify the root cause, and then apply the standard SPDD loop in compressed form: update the prompt first, then update the code. This keeps the spec and the implementation in lockstep, and the fix becomes a permanent part of the governed asset.
• Scenario B — legacy or no prior context. For urgent fixes in code that was never brought under SPDD, the pragmatic move is to let the AI analyze the logs and fix the issue directly. The closing step is a deliberate post-mortem: synthesize the fix, the failure mode, and the relevant context into newly documented assets. That is where the governance loop closes for legacy code, and it is also how SPDD coverage organically grows over a codebase.

The key point is that production signal does feed back — but it requires an explicit, human-led documentation step rather than happening automatically. Skipping that step is what creates the spec/code delta the question describes; treating it as part of the workflow is what prevents it.

Have you considered having an agent do the prompt/spec review itself — not a human reviewing the Canvas, but an agent that reads the REASONS Canvas alongside the code diff and verifies alignment?

Yes — that is basically what the /spdd-code-review command already does. It reads the REASONS Canvas and the code diff together and flags where the code drifts from the stated intent, so you can hand the alignment check off to the command whenever you want.

The trade-off is what you give up by doing that. The command can check alignment, but there are two things humans bring to review that an agent cannot replace:

• Catching intent drift. An agent can check whether the code matches the Canvas, but only a human can tell whether the Canvas itself still matches the real business intent. Without that check, a fully agent-driven review can look correct on its own terms but still miss the real goal.
• Letting humans learn. Review is also where humans learn from the AI's choices — patterns, trade-offs, options they had not thought of. Cutting humans out speeds things up, but it blocks the long-term skill growth that SPDD is designed to protect.

So the command is there when you want to use it, but it is built to handle the mechanical part of review, not to take it over. For now, humans stay in the loop by design. Once enough decision rules build up to give us real confidence, we may shift more of the review to the agent step by step — but the part where humans learn from the AI is something we plan to keep.

What's next for SPDD — and how will the roadmap reduce its dependence on individual expertise?

Four directions are shaping how the practice will evolve, and they all pull the same way: less reliance on personal craftsmanship, more repeatable organization-level capability.

• More recurring workflows captured as commands. The pattern that started with /spdd-analysis, /spdd-reasons-canvas, and /spdd-generate is far from finished. As we encounter recurring patterns in real projects, we keep extracting them into new commands, so each successful workflow becomes reusable rather than knowledge held by individuals.
• Automated verification at the asset layer. We are exploring automated verification not at the code level but on the SPDD assets themselves — the analysis, the REASONS Canvas, and the prompt artifacts. The aim is to layer automated checks and, over time, some automated decision-making on top of these intent-layer assets, so the framework can catch gaps, inconsistencies, and routine calls that today depend entirely on human review.
• Progressively raising the automation ratio. SPDD itself is already a harness — just a semi-automated one, with humans in the loop on the decisions that matter. The direction is to raise the automation ratio inside that harness step by step, paced by what the AI can reliably handle in practice, so more of the workflow runs without hand-holding only as the model proves dependable on each kind of task.
• A memory mechanism for “decision memory”. The goal is to let historical decisions — past canvases, trade-offs, and accepted patterns — act as persistent context, so the agent can retrieve the right prior reasoning in a given situation rather than rediscovering it each time. Specifics will be shaped by practical feedback.

Together, these directions move SPDD from a method that rewards skilled practitioners to a system where the framework itself carries more of the weight.

All of this reflects our current understanding and experience, and is likely to be adjusted as we keep learning and practising.