The Decision Schema: The Missing Layer in AI-Assisted Software Development

The Real Bottleneck Is Knowing What Must Stay True

The real problem in software development is not delivering functionality once; it is preserving enough understanding of the product to keep changing it safely.

Software grows in more than lines of code. Every product accumulates parallel concerns: business rules, permissions, security, performance, tenant isolation, lifecycle states, integrations, defaults, architectural boundaries, and exceptions. A seemingly small requirement can intersect with several of them. The challenge is therefore not simply to implement the requested functionality, but to understand the larger behavioral space into which that functionality must fit.

We try to preserve this understanding in PRDs, specifications, ADRs, BDD scenarios, architecture documents, and code. These artifacts matter, but accumulating more documents does not recreate the integrated understanding held by someone who deeply knows the product. At sufficient scale, the documentation itself becomes another system that must be searched, reconciled, and interpreted. Contradictions appear, assumptions remain implicit, and the connection between one rule and another becomes increasingly difficult to see.

AI coding agents make this weakness much more consequential. An agent normally works within a bounded context: the requested change, selected files, relevant specifications, and whatever supporting information we provide. That is useful because giving an agent the entire history and architecture of a large product is neither practical nor a guarantee of better reasoning. It also creates tunnel vision. The agent can satisfy the local specification while remaining unaware of a constraint elsewhere in the product that the change must preserve.

Spec-driven development alone does not solve this. As specifications accumulate, humans and AI still have to determine which pieces matter for each change. Every change introduces another version of the same question: which domain concepts, technical elements, rules, behavioral dimensions, and existing cases are affected?

This is what makes long-lived software difficult to modify sustainably. The knowledge required to make one change safely is distributed across an increasingly large product, while both humans and AI can only reason about a fraction of it at once.

The problem is not missing documentation. The problem is that we have no canonical model of the product’s behavioral decision space telling us what every new change must preserve.

Hidden Constraints Turn Small Changes Into Large Risks

When the product’s behavioral decision space is not explicit, every change forces the team to rediscover part of the product before it can safely modify it.

That rediscovery creates cognitive load first. PMs, analysts, QAs, architects, and developers must reconstruct intent from specs, ADRs, tickets, code, tests, and conversations. The larger the product becomes, the more expensive that reconstruction gets because the relevant knowledge is not only distributed; it is also conditional. A rule may apply only for one role, one state, one screen, one API path, or one default. The team is not merely looking for information. It is trying to work out which combinations of information matter for this change.

Then come missed obligations. A requirement may look local while changing several dimensions of behavior at once. A new field may affect permissions, defaults, persistence, migration behavior, API representation, and visibility in another part of the product. If the team cannot systematically derive the required cases from the changed decision space, some of those cases will be absent from the specification. That gap eventually appears as rework, late QA findings, regressions, behavior that nobody intended, or defects that escape entirely.

Over time, the problem compounds into specification entropy. Defaults become explicit in one test scenario and implied in another. Two scenarios describe equivalent preconditions but assert incompatible outcomes. A business rule changes, but one old specification still reflects the previous behavior. The product may continue to work, yet the organization gradually loses confidence in which artifacts actually represent the current truth.

AI makes the consequences more severe because it can accelerate implementation without necessarily increasing understanding. An agent can produce a technically plausible change quickly while missing a constraint that sits outside its working context. That means faster delivery can also mean faster accumulation of hidden inconsistency. If the behavioral authority is weak, AI scales the weakness.

The long-term cost is not just more defects. It is the gradual loss of the organization’s ability to explain what the product is supposed to do, why it does it, and what must remain true when it changes.

Establish a Canonical Behavioral Authority

The solution is to stop treating product behavior as scattered documentation and start managing it as a canonical Decision Schema.

A Decision Schema is the product’s behavioral authority. The full authority snapshot contains:

• Canonical domain objects — the stable business concepts the product talks about.
• Technical elements — the screens, routes, fields, APIs, events, interfaces, and integrations where behavior appears.
• Business rules — the constraints defining what must and must not happen.
• Decision axes — named, enumerable, behavior-relevant dimensions of variation that can alter what the system allows, shows, persists, or forbids.
• Coverage obligations — the rule-valid behavioral cases the specification must account for.
• Specification evidence — BDD scenarios or other artifacts showing how those obligations are represented.

They become part of an explicit structure that can be checked, compared, and maintained over time.

Switching a Light Bulb

The first step is to extract the decision axes. The Light bulb state axis has the values Light and Dark. The Switch state axis has the values Off and On.

The values on the Light bulb axis come from the business objects glossary. The values on the Switch axis come from the technical elements glossary. The valid and invalid outcomes come from the key business rules.

The axes define what can vary. The rules define what must hold. Together, they form a decision structure: a coordinate system of possible behavior. Some coordinates are valid. Some are invalid. Some require default behavior. Some apply only inside a declared scope.

The next step is to derive coverage obligations. A coverage obligation is not every possible coordinate in the decision structure. It is a minimal, rule-valid coordinate together with the observable behavior the specification must define. The full grid has four cells, but only two valid behavior obligations: Off/Dark and On/Light. The other two cells are invalid states, not additional positive obligations.

Axes define what can vary. Rules define what must hold. Obligations define what must be exemplified. Scenarios show how the obligation is exemplified. A BDD scenario is one concrete assignment of values to the axes; it occupies a cell in the decision structure.

• Axes are columns.
• Obligations are cells that should exist.
• Scenarios are cells that do exist.

This gives PMs and QA engineers a practical completeness question: given the axes and rules introduced by the change, which required cells must exist in the BDD suite? If a required cell has no scenario, the spec is incomplete. If two scenarios occupy equivalent preconditions but assert incompatible outcomes, the spec is contradictory. If a default is implied in one place and explicit in another, the spec is drifting.

Each coverage obligation should normally be surrounded by three kinds of scenarios. A positive scenario proves the expected behavior. A negative scenario rejects forbidden behavior near that obligation. An edge-case scenario shows the nearest relevant boundary, transition, omission, default, or state change. For example, Off/Dark should include the positive dark outcome, reject the invalid light outcome, and cover the transition from on to off.

In a real product there may be tens or hundreds of axes: role, state, operation, tenant, channel, permission, lifecycle stage, migration status, default origin, persistence boundary, and integration state. Humans can define intent, approve rules, and decide trade-offs, but continuously reasoning across that n-dimensional space does not scale manually.

That is the job AI uniquely enables.

AI can maintain the Decision Schema as a living authority: compare a new change request against the baseline, identify the behavioral delta, derive affected obligations, map them against existing specification evidence, and expose gaps or contradictions. The important point is not how the agents are implemented. The important point is that AI makes it practical to operate a behavioral model whose complexity would otherwise overwhelm manual reasoning.

Humans own product intent. The Decision Schema makes that intent explicit. AI makes the resulting behavioral space manageable.

AI Can Change Software Without Losing the Bigger Picture

Once the Decision Schema becomes the canonical behavioral authority, software change stops being a search through scattered context and becomes a controlled update to an explicit model.

PMs and analysts can describe a requirement in terms of the product behavior it changes. QAs can see which obligations must be represented. Architects can reason about which technical elements and constraints are affected. Developers and AI agents can work from a bounded delta instead of trying to reconstruct the whole product from documents, code, tickets, and memory.

Instead of asking an agent to absorb an entire product and infer what matters, you give it structured behavioral knowledge and ask it to reason about a bounded delta. Without a Decision Schema, AI is just another participant trying to infer hidden constraints from incomplete context. With one, AI can reason over explicit concepts, rules, axes, and obligations. It can identify what changed, what must still hold, and where the current specification is incomplete or contradictory.

The trade-off is that the Decision Schema has to be maintained as real authority. If teams treat it as another optional document, it will decay like every other artifact. The baseline must reflect approved behavior, change requests must be evaluated against it, and accepted deltas must eventually become part of the new authority. That discipline is the price of making product knowledge durable.

The real dividing line will not be between teams that use AI and teams that do not. It will be between teams that have made product behavior explicit enough for humans and AI to reason about and teams that still manage change through memory and guesswork.

Next Step

Before you give AI more autonomy, stop asking AI to infer your product from scattered context. Build the Decision Schema, make it authoritative, and use the next change request to test whether your team can actually calculate what must stay true.

Pick one product area, establish its Decision Schema as the source of behavioral truth, and do not approve the next change until its affected obligations are explicit.