Structured-Immediate-Pushed Growth (SPDD)

The REASONS Canvas

The REASONS Canvas is a construction for producing prompts. It forces
readability round necessities, area mannequin, answer method, system
construction, job 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 suits within the system; parts 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 so on.).
• S — Safeguards: Non-negotiable boundaries (invariants, efficiency limits, safety guidelines, and so on.).

The canvas aligns intent and limits earlier than code is generated, shifting uncertainty to the left.
As a result of the structured immediate captures the complete specification, reviewers cause 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 means.
And as area information and design choices accumulate in every immediate, they compound particular person experience throughout iterations and scale back variability throughout the crew.

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. Evaluations transfer away from “spot
the bug” towards “test 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).

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

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

SPDD workflow

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

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

The present system

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

The whole codebase for this preliminary model is
accessible on GitHub.
The repository contains the preliminary necessities story
and all of the SPDD artifacts used to generate it.
For brevity, we do not describe that preliminary technology right here, but it surely follows primarily 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 consumer suggestions, we’re enhancing the billing engine to transition from a static pricing mannequin to a extra refined,
versatile infrastructure. This replace goals to help various subscription methods and variable, model-specific pricing via 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 world fee to dynamic
  pricing, the place prices fluctuate relying on the precise AI mannequin
  invoked.
• Multi-plan billing logic: introduce distinct billing behaviors
  primarily based on the client’s subscription tier:
• Customary 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 out a 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
  (similar to Technique or Manufacturing facility) to cleanly isolate the calculation
  formulation for various plans, making certain the system can simply
  accommodate future pricing fashions.

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

Step 1: Create preliminary necessities

To kick off the method rapidly, we will use the /spdd-story
command to generate a consumer story instantly primarily based on the enhancement. Usually, consumer tales are offered by the PO or BA.
Nevertheless, in our workflow, we will remodel tales of any type 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 crew’s versatile division of labor.

Instruction:

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

The auto-generated tales are detailed sufficient to function a baseline
for a proper venture. 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 count on to
evaluation and tweak the output earlier than treating it as ultimate. 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 opinions the consumer
story to construct a shared understanding of what it means in apply. 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 finished.

Core logic

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

• Customary Plan: Buyer has a month-to-month token quota. Utilization
  inside quota is free. Overage is charged at a model-specific fee
  (e.g., fast-model $0.01/1K vs. reasoning-model $0.03/1K). Current
  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 fee. Invoice = immediate cost + completion
  cost. This plan is totally 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 finished

The next situations restate the story’s acceptance standards
with the implementation element the crew must confirm. The fourth
merchandise (Response format) shouldn’t be 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. Damaging tokens → HTTP 400. All
  present validations stay intact.
• Customary Plan billing: A buyer with a 100K quota and
  90K already used submits 30K tokens for fast-model ($0.01/1K).
  Anticipated outcome: 10K coated by quota, 20K overage, cost $0.20.
  The identical request with reasoning-model ($0.03/1K) yields $0.60 —
  similar quota logic, totally different fee.
• 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 situations go, 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 totally on the “what” and
“why,” intentionally avoiding granular implementation particulars at this
stage. It sometimes covers:

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

Evaluation 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 circumstances or boundary situations 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 ideas established within the present system,
  particularly ISP and SRP.
• The validity of the proposed technique for including new fields.
• Figuring out edge circumstances not beforehand anticipated.
• Uncovering potential technical dangers.

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

Edge circumstances and dangers from the
evaluation doc

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

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

Determination: 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 via high-level technique throughout
the evaluation part—so when reviewing the structured immediate, we’re not
ranging from scratch. As a substitute, we’re inspecting 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 via into the architectural abstractions and implementation
specifics. That is intent alignment at a deeper degree—making certain that
earlier than any code is generated, the AI has successfully “simulated” the
whole answer inside our outlined framework. We get to evaluation from a
world perspective quite 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 ideas. Consequently, although the
generated content material is extremely advanced, there are remarkably few main
points. We will choose 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.

To date, now we have 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 technology
part.

Step 5: Generate code

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

Function verification

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

How spdd-api-test works

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

Instruction:

/spdd-api-test

Generated artifact: the API check script.

Guided by the outlined guidelines within the command, the AI generates a
script that formulates the required check situations utilizing curl instructions.
We will evaluation these AI-generated situations 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

Outcome: all purposeful checks handed efficiently.

API Check Outcomes

Code evaluation & ultimate changes

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

To keep up precision in our engineering practices, we categorize
these ultimate changes into two distinct sorts—primarily based 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.

For example, when persisting modelId within the invoice, we
at the moment permit this subject to be nullable. The underlying cause is the
want to take care of backward compatibility with historic knowledge, making
this workaround an inexpensive architectural choice.

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 remove 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
all the pieces 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 choice, replace the corresponding elements of the structured immediate.

The AI updates the structured immediate primarily based 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 primarily based 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 completely on the affected
codebase.

Up to date artifact: the up to date code.

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

1. Determine the mismatch: discover that the habits of
   modelId throughout persistence is inconsistent with the brand new
   enterprise requirement (it have to be obligatory 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
   fact, run /spdd-generate pointing to the up to date file.
   The AI mechanically performs focused diffs completely on the
   affected codebase, quite than regenerating all the pieces from
   scratch.

personal 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 check

As soon as all optimizing is full, restart the service and run the
API check script another time to make sure no core performance was
damaged in the course of the cleanup.

Outcome: all handed.

Regression Check Outcomes

Step 6: generate unit checks

Useful testing alone is inadequate for strong validation; it
acts primarily as an auxiliary test and isn’t factored into code
protection metrics. The ultimate sign-off on core logic requires
complete unit checks. At the moment, the SPDD workflow doesn’t have
devoted testing instructions finalized (these can be launched in
future iterations). As an interim answer, 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 means of 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 entire code diff for this enhancement on GitHub.

We have additionally ready a bonus enhancement function—Enterprise
Plan Quantity-Based mostly Tiered Billing. Should you’re interested by getting
some hands-on apply, 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 nicely it pays off by state of affairs, from extremely really helpful (5 stars) to not appropriate (1 star).

Commerce-offs to contemplate

Return on funding

Upfront funding