SpecItem

AI-written requirements don't fail on process. They fail on constraints.

A bank BA rebuilt a knowledge base around constraints instead of documents. First in a series.

When an AI drafts a requirements document, the expensive part isn't that it writes badly. It's that it writes something that reads as correct — consistent formatting, coherent logic, nothing a reviewer can point at. The problems surface later, and they aren't in the sentences. They're in the structure. A screen that should have been split wasn't. An interface that was never real-time got written as real-time. An option that was ruled out last quarter comes back in the next document.

I assumed it was prompting. I changed templates, added roles, fed it examples. Eventually I realized the problem wasn't the prompt. It was the knowledge base. I had been feeding it processes and documents. What it lacked was boundaries: what may change, what may not, and under which conditions those boundaries hold.

The conclusion first

AI doesn't lack process. It lacks constraints.

Models have seen process thousands of times and can produce a convincing one. What they don't know is where they must not invent: which states cannot be added, which interface cannot be real-time, which fields have never been allowed to change, which phrase means one thing to the business and something else in the system. AI is good at describing the world. What it lacks is knowing where the walls are, and what those walls were built on.

So I changed the organizing word of my knowledge base from "catalogue" to "constraint". That is not a wording change; it is a filter. Whether a piece of content deserves to be kept comes down to one question: does it constrain other requirements? Will it limit the design space of future work?

Constraints fail in two ways. Either the conditions under which they stop applying are left unwritten, so the constraint outlives its premise. Or the scope is left unwritten. This post is about the first.

An example: the premise is gone, the constraint is still running

The feature was maintenance announcements — the notices a bank pushes to users when a system goes down for maintenance. I told the AI: "Maintenance announcements don't need review, so put the Create button on the announcement list page and show it only to admins." It wrote exactly that: one page, shared by admins and end users.

Then the decision changed. Maintenance announcements now needed review. I handed the new requirement to the AI to update the SRS. It worked fast and carefully: a review step, an approval state, the transitions between them, all of it, all added to the same page.

Nothing looks wrong at first glance. Clean formatting, consistent logic, no objections in the review — until someone asked: if admins and end users share one page, who exactly is doing the review?

The mistake wasn't a missing feature. It was treating a conditional conclusion as an unconditional design. "Shared page" was never a constraint on its own. It held because there was no review. I had said both at once, the premise and the conclusion. The AI kept the conclusion half. The premise disappeared, the conclusion stayed, and it built a complete feature on a foundation that no longer existed.

It wasn't lazy, and it wasn't off-topic. It was executing a dead premise with great care. That is what makes this class of error expensive. Get the process wrong and you rewrite paragraphs. Get the structure wrong and you redo page splits, permission models, review flows. Constraints are not there to catch typos. They are there to prevent structural rework.

I also thought the shared page was fine at the time. This is not an AI-specific mistake. Everyone makes it. We remember what was decided; we rarely remember why. AI just makes the habit visible.

Now, whenever I write a constraint, I ask what premise it stands on. If I can't name one, I haven't finished thinking: the constraint is a snapshot of the current design, not a rule. My entries have a scope field, which says how far a constraint reaches. But scope is space, not time. Nobody knows, on the day it is written, when it will stop being true. I keep two states, active and retired, change the state when things move, and write the premise into the body. When a decision changes, I go back through the entries it touches.

The knowledge base has three layers now. Layer A holds facts and constraints and is indexed by default. Layer B holds decision records, is not indexed, and is read by ID when tracing something back. Layer C holds terms and system definitions, referenced from both sides and never copied. Business architecture and application architecture sit side by side in A, because system boundaries are themselves constraints. If the fact that an interface isn't real-time never enters the base, the AI can only invent it from the process description.

One test

To decide whether a conclusion belongs in layer A, ask one question: will it limit the design space of future requirements?

If yes, A. "Phone number, ID number, and name must never appear on the same form" shapes every form that touches personal data after it. If no, B. "Should this reminder be a popup or an SMS" — the next requirement may not remind anyone at all.

If there is only one rule, this is it. It answers both what deserves to be kept and what must not enter the base. Without it, a knowledge base fills up with chat logs.

What I'm not doing yet

The knowledge base is a knowledge base. It serves the writing, but "how to write an SRS" and "how to produce a first draft" are a separate workflow, and they don't belong in the base's rules. Mix them and the rule files become a mess, and the AI can't tell which rule applies.

Retrieval stays simple. There are few entries; reading every active, AI-readable entry is enough, and common business vocabulary goes straight into the entry text. At a few hundred entries I'll consider keyword or vector search. A rule I can't implement is better kept as a known limitation than written into the process.

One last thing

The question I keep for myself: if I handed this base to an AI today, could it name three things the system must not do? If not, it is still a filing cabinet.

Two more posts follow. One on the second way constraints fail — scope left undefined. One on why constraints get stored twice, which anyone who has built a knowledge base will recognize. After that: the three things AI is missing, why five-level category trees run out of room, what to do with Karpathy's LLM wiki, and a few problems I haven't solved.

← Notes requirements · knowledge-base · AI