Acceptance criteria as portable knowledge
Most criteria die with the ticket that carried them. Treating them as concepts with a path, rather than a text field in a tracker, changes what they can do.
Go and look at a ticket your team closed nine months ago. Not a recent one, an old one, from a project that shipped and moved on.
The acceptance criteria are probably still there, in a field, under the description. Read them. Three things will likely be true. First, they describe a state of the world that may or may not still hold. Second, nothing has ever checked whether it still holds. Third, the rule they encode (“a user with an expired card gets a fourteen day grace period, not seven”) is almost certainly still live in the product, and almost certainly written down nowhere else.
That is the situation I want to poke at. The most precise statements a team ever writes about how its software should behave are filed in the least durable place available: a text field, on a work item, in a tracker, organised by when the work happened rather than by what the software does.
Criteria are knowledge wearing a project management costume
Acceptance criteria exist in the tracker for a historical reason: they were an instruction to a developer, and instructions are scoped to tasks. Once the task is done, the instruction has served its purpose, and the artefact that carried it becomes an archive entry.
But look at what a good criterion actually contains. “Given a subscription whose payment has failed three times, when the nightly job runs, then the account moves to suspended and a notification is sent.” That is not an instruction. That is a statement about how the system behaves, permanently, until somebody deliberately changes it. It is exactly as much a piece of durable knowledge as the definition of churn or the description of the events table.
Filing it under a ticket is like filing the schema of your database under the migration that created it. Technically the information is there. Practically nobody will ever find it, because nobody searches by “what were we working on in March.”
Criteria as a ticket field
- Organised by when work happened
- Dies when the ticket closes
- Rewritten from scratch next time
- Contradictions across tickets are invisible
- Lives inside one vendor's database
Criteria as a concept file
- Organised by what the software does
- Outlives the work that produced it
- Amended, with a diff and a reviewer
- Two rules in one file, contradiction visible
- Lives in a folder anyone can read
The Open Knowledge Format’s shape fits this unusually well, which is why it is worth an article. One concept per file, path as identity, links between concepts. A behavioural rule is a concept. behaviour/subscription-suspension.md is a path that will still make sense in three years, in a way that PROJ-4471 will not.
What changes when the rule has a path
Three things, and they compound.
A ticket can reference instead of restating. When the rule lives at a path, a work item can link to it. The ticket says what is changing; the concept says what is true. This kills the most common source of contradiction in a mature backlog, which is that fourteen different tickets have each restated the grace period rule slightly differently over four years, and the most recent restatement is not necessarily the correct one, and nobody can tell which is which.
Changes to behaviour become diffs. If the grace period moves from fourteen days to seven, that is a one-line change to a file, in a pull request, with a reviewer and a date and a reason in the commit message. Compare that to the current situation, where the change is expressed as a new ticket whose criteria happen to say seven, and the old ticket still says fourteen, and both remain in the system as equally official statements forever.
Agents can read the rule without being handed it. This is the part that matters for the ADLC. When an agent picks up work adjacent to subscriptions, it can find the behavioural concepts for subscriptions by navigating the directory, and it will read the current, reviewed statement of the rule rather than whatever prose was pasted into this particular ticket by whoever wrote it at 4pm on a Friday.
The uncomfortable question this raises
If criteria become durable documents, something has to answer the question that trackers never had to answer: is this still true?
A ticket field gets a pass on this because everyone tacitly understands it as a historical record. Nobody expects a closed ticket to describe current behaviour. A concept file at behaviour/subscription-suspension.md makes exactly the opposite claim. Its whole value proposition is that it describes how the system behaves now.
That is a much stronger claim, and a knowledge base full of unverified strong claims is the failure mode this series keeps returning to. A wrong criterion in a closed ticket is inert. A wrong criterion in a current behavioural concept is read by an agent and turned into code.
There are only three honest ways to handle this, and it is worth naming all three because teams often pretend there is a fourth.
Review cadence. Somebody reads the file periodically and confirms it. This is what most documentation processes claim to do and it does not work, because the review is unrewarding, unmeasured and easily faked with a date bump.
Derivation. The document is generated from something that cannot lie, typically the code or the tests. This works beautifully where it applies and applies to less than people hope, because the interesting criteria are precisely the ones that are not obvious from the implementation.
Verification. The claim in the document is checked against reality by something automated, and the check runs on a schedule that is not human discipline. A criterion that maps to a test is verified every build. A criterion that maps to nothing is unverified and should be visibly marked as such.
Verified by a test
The strongest state. The document and the software fail together, which is exactly what you want.
Verified against the diff
Checked when the relevant code changes. Weaker, but it catches the moment behaviour and rule part company.
Reviewed by a person
Honest about being a human judgement. Decays at the speed of attention, which is fast.
Asserted and unchecked
The dangerous quadrant. Reads exactly like the other three to anything consuming it.
That bottom-right cell is why gating matters. GroundTruth’s argument about “done” is that a criterion which cannot be evaluated against the actual change is not really a criterion, it is a hope with a checkbox. The same logic applies once criteria become durable knowledge: a behavioural document with no verification path is a hope with a file path, and the file path makes it more persuasive rather than less.
Portability is the underrated part
There is a second argument for pulling criteria out of the tracker, and it has nothing to do with agents.
Your acceptance criteria are, collectively, one of the most valuable and least portable assets your organisation owns. They encode thousands of small decisions about how the product should behave, most of which were argued over, some of which were expensive to learn. They live in a vendor’s database, in that vendor’s field structure, exportable as CSV in a way that loses every relationship, and they are not really movable.
Teams discover this during a tracker migration. The tickets come across. The criteria come across as text. The links, the history, the context and the ordering do not, and after the migration nobody can find anything, so effectively the corpus is gone even though the rows are present.
A directory of markdown files does not have this problem, because there is nothing to migrate. This is the plainest version of the vendor-neutrality argument: no licence, no API key, no platform. If your knowledge is a folder, changing tools is a change of tools, not a change of substrate. Trackers will keep changing. Agents will definitely keep changing, faster than trackers. The behavioural knowledge should outlast both, and it can only do that if it never lived inside either.
Where this breaks down
Not all criteria are durable, and treating them as if they are creates noise. “The button should be blue in this release because marketing asked” is a genuine acceptance criterion and genuinely not durable knowledge. If every criterion becomes a concept file you will build an enormous directory of one-off statements, and the signal will drown. The rule I would apply: promote a criterion to a concept only when it states something that should still be true after the work is done. Most criteria on a given ticket fail that test, and that is fine.
Duplication between tracker and knowledge base is worse than either alone. The moment the rule exists in both places, they will diverge, and now you have two authorities. Doing this properly means the ticket links rather than restates, and getting a team to stop pasting criteria into tickets is a genuinely hard behavioural change that no format will accomplish for you.
The maintenance cost is real and lands on a team that is already behind. Every behavioural concept is a document somebody has to keep true. If the answer to “who owns this” is nobody, do not create it. A hundred well-maintained behavioural concepts beat a thousand aspirational ones, and the thousand is what you get by default.
Stale behavioural knowledge is worse than none, and this is the sharpest instance of that. A stale metric definition produces a wrong number that somebody may query. A stale behavioural rule gets read by an agent and implemented as code, confidently, with a citation to an internal document that makes the reviewer trust it more. If you are not going to verify these, do not elevate them from ticket fields, because the ticket field at least carries an implicit “this was true in March.”
The format is v0.1 and says nothing about any of this. There is no notion of verification state, no supersession, no conflict resolution. Everything in this article about verified versus asserted is a convention you would have to invent and enforce yourself. Do not read the spec as offering more than it does.
The takeaway
Acceptance criteria are behavioural knowledge that happens to have been born inside a project management tool. The ones that state something durable should live where durable things live: one rule, one file, one path, linkable from the tickets that change it rather than restated in each of them.
But promoting a criterion from ticket field to concept file raises the claim it makes about currency, and a claim about currency without a verification path is just confident wrongness with better filing. Promote the durable ones, verify what you can, and mark plainly what you cannot.
The next piece extends the same argument up a level, to the documents that start projects rather than end them: why your PRD and your ERD are knowledge that was mis-filed as documents, and what changes when you stop treating them as deliverables.