Structured-Immediate-Pushed Improvement (SPDD)

The REASONS Canvas

The REASONS Canvas is a construction for producing prompts. It forces
readability round necessities, area mannequin, resolution method, system
construction, activity decomposition, reusable norms, and safeguards. So the
LLM is guided by intent, not guesswork.

The REASONS Canvas is a seven-part construction that guides a immediate from
intent → design → execution → governance.

Summary elements (intent & design)

• R — Necessities: What downside are we fixing, and what’s DoD?
• E — Entities: Area entities and relationships.
• A — Method: The technique of how we’ll meet the necessities.
• S — Construction: The place the change matches within the system; elements and dependencies.

Particular elements (execution)

• O — Operations: Break the summary technique into concrete, testable implementation steps.

Frequent requirements elements (governance)

• N — Norms: Cross-cutting engineering norms (naming, observability, defensive coding, and many others.).
• S — Safeguards: Non-negotiable boundaries (invariants, efficiency limits, safety guidelines, and many others.).

The canvas aligns intent and limits earlier than code is generated, transferring uncertainty to the left.
As a result of the structured immediate captures the total specification, reviewers purpose a few single artifact as an alternative of scattered chat logs and partial diffs.
By following the identical construction, each immediate turns into governable in the identical manner.
And as area data and design choices accumulate in every immediate, they compound particular person experience throughout iterations and scale back variability throughout the group.

The SPDD workflow

The workflow brings prompts into the identical self-discipline as code: commit
historical past, evaluation, and high quality gates. It additionally enforces a easy however highly effective rule:

When actuality diverges, repair the immediate first — then replace the code.

Over time, this adjustments how groups work. Critiques transfer away from “spot
the bug” towards “examine the intent.” Rework turns into extra managed. And
profitable patterns naturally accumulate right into a reusable immediate library
that helps AI-First Software program Supply (AIFSD).

In case you’ve recognized about Spec-Pushed
Improvement,
you may acknowledge the identical start line: write the spec clearly first,
then let the mannequin implement. SPDD takes a unique angle. It treats
structured prompts as ruled, reusable, versioned group property (REASONS
+ workflow) that evolve alongside the code – an method that Birgitta
Böckeler categorizes as a spec-anchored method.

The objective of the SPDD workflow is to show enterprise enter → abstraction →
execution → validation → launch right into a “closed loop”—and to verify
immediate property and code evolve collectively, not individually.

SPDD workflow

The goal of this workflow is to anchor collaboration on the prompts, so
that builders and product house owners can keep away from repeated cycles of alignment.
The immediate units an express boundary for code era, lowering the
randomness of the LLM’s non-determinism, making it simpler to manipulate. By
treating the structured prompts as first-class artifacts in model
management, we flip profitable practices into reusable property, bettering
consistency and lowering reinvention.

In follow these steps are carried out by instructions offered
by openspdd, a command-line device that
implements the SPDD workflow. The desk under summarizes every
command.

The present system

The present system is a straightforward billing engine that calculates payments
for utilizing a large-language mannequin. It accepts a document that captures how
many tokens are utilized in a session and calculates a invoice.

The whole codebase for this preliminary model is
out there on GitHub.
The repository consists of the preliminary necessities story
and all of the SPDD artifacts used to generate it.
For brevity, we do not describe that preliminary era right here, nevertheless it follows basically the identical steps as that for the enhancement.
We deal with describing the enhancement as a result of most work on a system are enhancements.

The enhancement

Pushed by evolving enterprise necessities and direct person suggestions, we’re enhancing the billing engine to transition from a static pricing mannequin to a extra subtle,
versatile infrastructure. This replace goals to help various subscription methods and variable, model-specific pricing by the next key adjustments:

• API enhancement: replace the present POST /api/utilization
  endpoint to just accept a brand new, required modelId parameter
  (e.g., “fast-model”, “reasoning-model”).
• Mannequin-aware pricing: shift from a single international price to dynamic
  pricing, the place prices range relying on the precise AI mannequin
  invoked.
• Multi-plan billing logic: introduce distinct billing behaviors
  based mostly on the client’s subscription tier:
• Commonplace plan (optimized): retains the worldwide month-to-month quota,
  however any overage utilization is now calculated utilizing model-specific
  charges.
• Premium plan (new): operates with no quota restrict. It
  introduces cut up billing, the place immediate tokens and completion
  tokens are charged individually at totally different charges relying
  on the mannequin used.
• Architectural scalability: implement an extensible design sample
  (reminiscent of Technique or Manufacturing unit) to cleanly isolate the calculation
  formulation for various plans, guaranteeing the system can simply
  accommodate future pricing fashions.

Since this new part encompasses each enterprise necessities and technical particulars,
it’s sometimes accomplished collaboratively by a pairing session between a PO (or BA) and a developer.

Step 1: Create preliminary necessities

To kick off the method shortly, we will use the /spdd-story
command to generate a person story instantly based mostly on the enhancement. Usually, person tales are offered by the PO or BA.
Nevertheless, in our workflow, we will remodel tales of any kind right into a constant format and dimension.
So long as there’s shared alignment on the ultimate acceptance standards, this step might be carried out by a PO, BA, or developer, relying on the group’s versatile division of labor.

Instruction:

The AI analyzed the enhancement description and cut up it into two
person tales:

The auto-generated tales are detailed sufficient to function a baseline
for a proper challenge. For this walkthrough we consolidate them right into a
single simplified story so the instance stays self-contained.

Instruction:

Directions of this sort hardly ever produce similar textual content on each run —
fashions and sampling introduce small variations — so we nonetheless anticipate to
evaluation and tweak the output earlier than treating it as remaining. The mixed
story under is the model we refined for this walkthrough: a intentionally
simplified consolidation of the 2 preliminary tales.

Step 2: Make clear evaluation

Earlier than leaping into implementation, the developer critiques the person
story to construct a shared understanding of what it means in follow. If
there are apparent business-level points, that is the purpose to align with
the BA or PO. On this case the story is obvious sufficient, so we transfer
straight to breaking it down alongside three dimensions: core logic, scope
boundaries, and definition of achieved.

Core logic

One new required subject on the API: modelId. The shopper
now tells us which AI mannequin they used — that is the important thing that unlocks the
proper value.

• Commonplace Plan: Buyer has a month-to-month token quota. Utilization
  inside quota is free. Overage is charged at a model-specific price
  (e.g., fast-model $0.01/1K vs. reasoning-model $0.03/1K). Present
  quota logic stays; solely the speed lookup adjustments.
• Premium Plan: No quota. Each token is billed from the
  first one. Immediate tokens and completion tokens are charged individually,
  every at a model-specific price. Invoice = immediate cost + completion
  cost. This plan is solely new.
• Routing: The system determines the client’s plan and
  dispatches to the matching billing components. The design have to be simple to
  lengthen — Enterprise plans (Story 2) are subsequent.

Scope boundaries

We’re solely calculating the present invoice. We’re NOT constructing buyer
CRUD, NOT querying historic payments, NOT managing subscriptions, and NOT
including/eradicating fashions.

Definition of achieved

The next eventualities restate the story’s acceptance standards
with the implementation element the group must confirm. The fourth
merchandise (Response format) isn’t a brand new enterprise AC — it captures the
non-functional contract the developer provides to make the factors
testable end-to-end.

• Validation: Lacking modelId → HTTP 400.
  Unknown buyer → HTTP 404. Adverse tokens → HTTP 400. All
  current validations stay intact.
• Commonplace Plan billing: A buyer with a 100K quota and
  90K already used submits 30K tokens for fast-model ($0.01/1K).
  Anticipated outcome: 10K lined by quota, 20K overage, cost $0.20.
  The identical request with reasoning-model ($0.03/1K) yields $0.60 —
  similar quota logic, totally different price.
• Premium Plan billing: A buyer submits 10K immediate
  tokens + 20K completion tokens for reasoning-model (immediate $0.03/1K,
  completion $0.06/1K). Anticipated outcome: $0.30 + $1.20 = $1.50. No
  quota, no overage — immediate and completion are billed individually.
• Response format: HTTP 201 returning invoice ID, buyer ID,
  token counts, timestamp, modelId, and a plan-appropriate
  cost breakdown.

If all these eventualities move, we have conquered this story.

Step 3: Generate evaluation context

With the necessities and scope clarified, we use the
/spdd-analysis command. By feeding it the enterprise
necessities, we instruct the AI to generate a complete evaluation
context.

Instruction:

/spdd-analysis
@[User-story-1]Multi-Plan-Billing-Basis-&-Mannequin-Conscious-Pricing.md

Generated artifact: the preliminary evaluation context doc.

This command produces a strategic-level evaluation grounded in precise
codebase exploration. The output focuses solely on the “what” and
“why,” intentionally avoiding granular implementation particulars at this
stage. It sometimes covers:

• Area ideas: current vs. new, relationships, enterprise
  guidelines
• Strategic method: resolution course, design choices,
  trade-offs
• Dangers & gaps: ambiguities, edge instances, technical dangers,
  acceptance-criteria protection

Overview and refine the evaluation context

With our personal understanding of the enterprise necessities in thoughts, we
evaluation the generated evaluation doc—specializing in the areas
highlighted within the alignment talent. This evaluation serves
two functions: confirming that our understanding aligns with the AI’s
interpretation, and discovering edge instances or boundary eventualities the AI
may floor that we hadn’t thought of.

On this particular occasion, the evaluation targeted on a number of vital
areas:

• Whether or not the Technique Sample was appropriately thought of.
• Adherence to the OOP rules established within the current system,
  particularly ISP and SRP.
• The validity of the proposed technique for including new fields.
• Figuring out edge instances not beforehand anticipated.
• Uncovering potential technical dangers.

Upon finishing the evaluation, the AI’s evaluation largely aligned with
our architectural intent; in truth, its concerns have been much more
complete than ours in sure areas.

Edge instances and dangers from the
evaluation doc

To be clear, at this stage we solely possess a high-level
conceptual alignment. Whereas we will shortly envision the implementation
for areas the place we have now prior expertise, we can not fully map out
all of the granular technical particulars for the unfamiliar elements proper
now.

Nevertheless, that’s completely high quality. The overarching course is aligned.
We will proceed to the following step: observing how the AI “simulates” the
concrete implementation particulars inside our established framework and
context. As soon as we have now these tangible particulars, we will uncover deeper,
hidden points and make knowledgeable trade-offs based mostly on the precise
situation—adopting the approaches the place the advantages outweigh the
drawbacks, and discarding the remainder.

Resolution: settle for the evaluation as-is and proceed.

Step 4: Generate structured immediate

Instruction:

/spdd-reasons-canvas
@GGQPA-001-202603191100-[Analysis]-multi-plan-billing-model-aware-pricing.md

Generated artifact: the preliminary structured immediate.

By this level, we have already gone by high-level technique throughout
the evaluation part—so when reviewing the structured immediate, we’re not
ranging from scratch. As a substitute, we’re analyzing how the AI has
translated our shared understanding into the REASONS Canvas construction:
from technique to abstraction to concrete particulars.

Consider it as a development: the evaluation part gave us strategic
readability; now we’re checking whether or not that readability has been faithfully
carried by into the architectural abstractions and implementation
specifics. That is intent alignment at a deeper degree—guaranteeing that
earlier than any code is generated, the AI has successfully “simulated” the
whole resolution inside our outlined framework. We get to evaluation from a
international perspective slightly than getting misplaced in particulars from the
begin.

Focus the evaluation on the areas highlighted within the abstraction-first talent. On this case,
this foundational context is already embedded within the codebase and the earlier
structured immediate. Consequently, when producing the structured
immediate for this iteration, the AI naturally elements in these
architectural tips and OO rules. In consequence, though the
generated content material is extremely advanced, there are remarkably few main
points. We will decide to proceed with producing the code utilizing this
structured immediate first, after which conduct a deeper evaluation to determine
any potential code-level anomalies later.

Up to now, we have now reached a robust consensus on the intent degree,
clarifying each the core downside and the decision path. Whereas there
could also be slight omissions within the particulars, this isn’t a priority; having
aligned on the general scope with the AI makes native optimizations
extremely controllable. Now, we transition into the code era
part.

Step 5: Generate code

This step is extra concerned as we’re producing the product code,
checks, and our critiques have two different outcomes.

Characteristic verification

Throughout function validation, the SPDD workflow gives the
/spdd-api-test command to generate useful testing
scripts.

How spdd-api-test works

This command extracts API endpoint info from the code
implementation or acceptance standards and generates a cURL-based
take a look at script. The script features a structured test-case desk
overlaying regular eventualities, boundary situations, and error
eventualities. When executed, it outputs expected-vs-actual comparability
outcomes.

Instruction:

/spdd-api-test

Generated artifact: the API take a look at script.

Guided by the outlined guidelines within the command, the AI generates a
script that formulates the required take a look at eventualities utilizing curl instructions.
We will evaluation these AI-generated eventualities within the “TEST CASE OVERVIEW”
part of the script.

Generated API Check Script

Execution: as soon as the script is generated, run it:

sh scripts/test-api.sh

End result: all useful checks handed efficiently.

API Check Outcomes

Code evaluation & remaining changes

Due to the rigorous intent alignment within the first a number of steps, the
heavy lifting is already achieved. At this stage, the remaining points are
normally minor logic discrepancies or surface-level code smells.

To keep up precision in our engineering practices, we categorize
these remaining changes into two distinct varieties—based mostly on whether or not they
change the system’s observable habits—and deal with them utilizing
totally different methods throughout the SPDD workflow:

Two responses to code evaluation adjustments

Logic corrections (habits adjustments)

Technique: replace the immediate first, then generate code. For points
associated to enterprise guidelines or logic mismatches (which inherently change
the observable habits of the software program), at all times replace the structured
immediate to lock within the appropriate intent earlier than touching the code. That is
an replace or bug repair, not a refactoring.

As an example, when persisting modelId within the invoice, we
at present enable this subject to be nullable. The underlying purpose is the
want to keep up backward compatibility with historic information, making
this workaround an affordable architectural resolution.

Immediate wants replace

Nevertheless, there’s an alternate. If the enterprise stakeholders can
verify what the modelId worth needs to be previous to this
change, we will unify the system’s habits and get rid of this potential
technical debt. Let’s assume that, after confirming with the enterprise,
the modelId for all historic payments needs to be set to
fast-model.

With this clear intent, we work together with the AI:

How spdd-prompt-update works

This command incrementally updates the present Canvas. It
modifies solely the sections affected by the change and preserves
every part else. Based mostly on the kind of change — new requirement,
architectural adjustment, or constraint change — it mechanically
determines which REASONS dimensions want updating.

This differs from /spdd-sync: sync flows from
code to spec when code has modified; prompt-update flows from
necessities to spec when necessities have modified.

Instruction:

/spdd-prompt-update @GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md

model_id is a required subject, and its default worth is fast-model.
Based mostly on this resolution, replace the corresponding elements of the structured immediate.

The AI updates the structured immediate based mostly on this instruction.

Up to date artifact: the up to date structured immediate.

As soon as confirmed, use the /spdd-generate command to
replace the corresponding code based mostly on the newly up to date structured
immediate:

/spdd-generate
@GGQPA-001-202603191105-[Feat]-multi-plan-billing-model-aware-pricing.md

The AI, guided by the principles outlined throughout the
/spdd-generate command, comprehends the required adjustments
and performs focused updates solely on the affected
codebase.

Up to date artifact: the up to date code.

It is very important be aware that we don’t regenerate your complete
codebase. We proceed utilizing the present structured immediate and the AI
handles focused diffs:

1. Establish the mismatch: discover that the habits of
   modelId throughout persistence is inconsistent with the brand new
   enterprise requirement (it have to be necessary with a default).
2. Goal the immediate snippet: copy the precise part from the
   structured immediate that defines the outdated logic.
3. Replace the immediate: paste the extracted snippet into the chat
   alongside the revised enterprise rule, instructing the AI to replace
   the structured immediate first.
4. Generate focused code updates: as soon as the immediate displays the brand new
   reality, run /spdd-generate pointing to the up to date file.
   The AI mechanically performs focused diffs solely on the
   affected codebase, slightly than regenerating every part from
   scratch.

non-public int calculateRemainingQuota(String customerId, PricingPlan plan) {
        if (plan.getMonthlyQuota() == null || plan.getMonthlyQuota() == 0) {
            return 0;
        }

        LocalDate currentDate = LocalDate.now(ZoneOffset.UTC);
        LocalDateTime monthStart = currentDate.withDayOfMonth(1).atStartOfDay();
        LocalDateTime monthEnd = currentDate.plusMonths(1).withDayOfMonth(1).atStartOfDay();

        Integer currentMonthUsage = billRepository.sumIncludedTokensUsedForMonth(customerId, monthStart, monthEnd);
        return plan.getMonthlyQuota() - currentMonthUsage;
    }

Regression take a look at

As soon as all optimizing is full, restart the service and run the
API take a look at script yet one more time to make sure no core performance was
damaged throughout the cleanup.

End result: all handed.

Regression Check Outcomes

Step 6: generate unit checks

Useful testing alone is inadequate for sturdy validation; it
acts primarily as an auxiliary examine and isn’t factored into code
protection metrics. The ultimate sign-off on core logic requires
complete unit checks. At present, the SPDD workflow doesn’t have
devoted testing instructions finalized (these might be launched in
future iterations). As an interim resolution, we make the most of a
template-driven method to generate structured prompts for unit
testing.

What this instance delivered

This marks the conclusion of a whole SPDD workflow. By this
standardized course of, we efficiently delivered the next key
outcomes:

1. A enterprise logic implementation with exceptionally excessive intent
   alignment (~99%).
2. Full engineering transparency, together with a transparent
   understanding of the implementation path, technical choices, and
   accepted trade-offs.
3. A structured immediate asset tightly synchronized with the present
   codebase, laying a strong basis for future iterations.
4. Compounding human experience, fostering a steady accumulation
   of developer expertise and psychological fashions as we iterate
   collaboratively with the AI.

View the whole code diff for this enhancement on GitHub.

We have additionally ready a bonus enhancement function—Enterprise
Plan Quantity-Based mostly Tiered Billing. In case you’re eager about getting
some hands-on follow, we extremely encourage you to sort out it utilizing the
SPDD workflow outlined above.

Health evaluation

SPDD is an engineering funding. The desk under charges how properly it pays off by situation, from extremely advisable (5 stars) to not appropriate (1 star).

Commerce-offs to think about

Return on funding

Upfront funding