By the beginning of August, AIDD Skeleton had its basic shape.
There were five places for project information:
plans/
etc/
workbench/
references/
products/
The first problem had been structural.
When development happens through conversations with AI, where should requirements go? Where should unfinished investigations go? Where should implementation live?
Giving each responsibility a place helped.
But some of the problems I mentioned in the first article had already hinted that structure alone would not be enough.
TRACEABILITY.md had started growing too easily.
The source of truth could disagree with the implementation — and sometimes the source of truth itself was the thing that needed correction.
At the time, these looked like separate early problems.
They weren't.
They were the first signs of a much deeper question:
It wasn't enough to decide where documentation belonged. I also had to decide what that documentation was allowed to mean.
The first warning was documentation that could grow forever
In the first article, I mentioned that the first pull request in AIDD Skeleton was about preventing TRACEABILITY.md from growing without bound.
Prevent TRACEABILITY.md from growing without bound — August 1, 2026
At the time, I treated it mostly as a local documentation problem.
Traceability was useful because it connected requirements, design, implementation, and verification.
But it was also an obvious place to keep adding more information.
More implementation units.
More tests.
More verification records.
More relationships.
More historical context.
Each addition could be justified.
Together, they could turn one useful document into an ever-growing index of the entire project.
What became clear later was that TRACEABILITY.md was not a special case.
The same pattern could happen everywhere.
A status document could start carrying implementation history.
A testing document could accumulate execution results.
A design document could absorb facts discovered from the current code.
An investigation could eventually look like a project decision simply because nobody had removed it.
The repository did not just need rules about where documents belonged.
It needed rules about what those documents were allowed to mean.
The source of truth could be wrong too
Another event from the first stage of the project became more important in hindsight.
If the implementation disagreed with the documentation, the obvious reaction was:
The code is wrong. Make it match the source of truth.
But that assumes the source of truth is actually correct.
So AIDD Skeleton introduced a different order of diagnosis:
- Check whether the source of truth is complete, current, and internally consistent.
- Then check whether the implementation conforms to it.
- Then check whether verification actually demonstrates that conformity.
Review sources of truth before implementation — August 1, 2026
At first, this looked like a rule for resolving documentation drift.
Later, I realized it implied something much broader.
Documentation was not automatically trustworthy because it lived in the right directory.
That changed the questions I was asking.
Not:
Where should I put this file?
But:
Is this actually an adopted decision?
Is this describing what the system should be, or what it happens to be today?
Is this a requirement, a design decision, an implementation observation, or evidence from one execution?
Those distinctions turned out to matter much more than the directory names.
plans/ needed a much stricter meaning
The largest early ambiguity was inside plans/.
At first, it was tempting to keep both the current state and a proposed target state there.
That sounds useful.
You can see where the project is now and where it is supposed to go.
But it creates an authority problem.
Suppose a document says:
Current:
Authentication uses approach A.
Target:
Authentication will use approach B.
Has B been approved?
Is it still being discussed?
Can the AI begin migrating toward it?
What happens if another document still describes A as the intended design?
The distinction between describing a possible future and adopting that future as the project definition was too important to leave implicit.
By August 13, AIDD Skeleton made the boundary much clearer:
workbench/ -> candidate state, investigation, proposed change
plans/ -> adopted project definition
Clarify source-of-truth change handling — August 13, 2026
This meant a proposed design did not become authoritative just because someone had documented it carefully.
It remained in the workbench until it was actually adopted.
That rule solved more than a file-placement problem.
It separated two fundamentally different states of knowledge:
We are thinking about this.
and
The project has decided this.
For AI-driven development, that difference is enormous.
A human developer can often recognize that a beautifully written target design is still only a proposal.
An AI agent should not have to infer that from tone.
The repository needed to represent the distinction explicitly.
Then implementation knowledge started leaking back into design
Another problem appeared from the opposite direction.
Suppose an AI investigates an existing application.
It reads the code.
It discovers file paths, framework conventions, database structures, library behavior, deployment details, and internal APIs.
That information can be extremely useful.
But useful does not automatically mean normative.
If the current implementation is copied into a design document, the design gradually stops describing what the system must mean.
It starts describing how this particular version happens to be implemented.
Eventually, future implementations become constrained by yesterday's implementation details.
So another boundary had to become explicit:
Can the project still be reconstructed semantically from its normative documentation without access to the current implementation?
That question led to a much stronger separation between normative and non-normative information.
On August 20:
Tighten normative documentation boundaries — August 20, 2026
Requirements, design, and testing were increasingly treated as documents that could constrain future implementation.
Current implementation observations could still be valuable.
But they should not silently inherit that authority.
This was one of the points where I realized that "documentation" was too broad a category.
Two Markdown files could look almost identical while having completely different responsibilities.
One might define what future code must preserve.
The other might simply record something useful I learned today.
Treating both as equally authoritative was dangerous.
Testing had the same problem
Testing introduced another version of the same confusion.
A testing specification might say:
The system must reject an expired token.
That is a normative statement.
It defines what must be verified.
Now suppose I run the test today and record:
PHPUnit 12.3.1 passed this test on commit
abc123.
That is useful too.
But it is not the testing specification.
It is evidence from a particular execution.
The difference matters because one of them can remain valid while the other becomes stale.
The requirement to reject expired tokens may still be valid six months later.
The fact that one test passed six months ago does not prove that the current system still does.
Yet AI-generated project documentation can easily mix the two.
Testing intent, execution output, screenshots, logs, observations, and verification summaries can all look like "testing information."
So AIDD Skeleton began separating them explicitly.
On August 21:
Separate execution evidence from normative testing — August 21, 2026
Then the boundary was refined further:
Refine execution evidence boundaries — August 21, 2026
And the next day, active verification evidence was routed through the workbench instead of being allowed to quietly become permanent project truth:
Route verification evidence through workbench — August 22, 2026
Tighten verification evidence lifecycle — August 22, 2026
The underlying lesson was simple:
Evidence has a lifecycle.
A specification can remain valid.
An execution result can become stale.
A useful investigation can stop being useful.
A temporary artifact can deserve promotion into durable reference material.
Another can simply be deleted.
Keeping everything forever is not traceability.
Sometimes it is just accumulation.
I had been treating documentation as files
By this point, the original five-directory model still looked almost unchanged.
plans/
etc/
workbench/
references/
products/
But my understanding of what lived inside those directories had changed substantially.
At the beginning, I had mostly been asking:
Where should this go?
Now the questions looked more like:
Has this been adopted?
Does this constrain future implementation?
Is it an observation or a decision?
Is this testing intent or execution evidence?
How long is this evidence valid?
If this information is retained, why is it still useful?
If it is moved, what other documents still depend on it?
The repository structure had not become much more complicated.
The information model had.
And that was probably unavoidable.
The more development I delegated to AI, the less comfortable I became relying on distinctions that existed only in my head.
A human developer might look at a draft and intuitively understand:
"We're still discussing this."
An AI agent needs that state to be represented somewhere.
A human might see an old verification report and know:
"That was from before the refactor."
An AI agent needs enough provenance and lifecycle information not to mistake it for current proof.
A human might recognize that a design section merely describes the current framework implementation.
An AI agent may treat it as a requirement unless the repository tells it otherwise.
The goal was no longer simply to preserve information.
It was to preserve its meaning.
Less documentation became a feature
This also changed how I thought about documentation quality.
Previously, completeness often meant adding information.
Now I was increasingly interested in whether information deserved to exist in the durable project record at all.
Does this fact belong in the source of truth?
Does it only matter while we are investigating something?
Can it be derived from another authoritative source?
Has it become stale?
Does keeping it create another place that must be synchronized forever?
A documentation system can fail because information is missing.
It can also fail because information never leaves.
The goal was not maximum documentation.
The goal was minimum ambiguity.
That distinction became increasingly central to AIDD Skeleton.
And eventually it led to a much stranger problem.
I had spent weeks tightening the rules that told AI how to classify, retain, promote, and remove project information.
Those rules were becoming powerful enough to cause significant changes when applied to an existing repository.
Which raised an uncomfortable question:
How did I know the rules themselves were right?
It was no longer enough to inspect AIDD Skeleton and decide that the rules looked reasonable.
If the framework was supposed to govern real projects, eventually those rules would have to be tested against real projects too.
And if applying them produced a bad result, I would need to resist the easiest explanation:
"The project was wrong."
Sometimes the thing that needed debugging might be the framework itself.
That became the next stage of the project.
AIDD Skeleton is still evolving:
The first article in this development history covered how conversations with AI led to the initial five-part repository structure and the creation of workbench/.
This article covers what happened next: realizing that organizing documents was not enough. Their authority, lifecycle, and evidentiary scope also had to be controlled.
The next stage began when I started applying those rules to other repositories and asking a different question:
Can the framework itself fail the test?
AI disclosure: This article was written with AI assistance. The narrative was reconstructed from the AIDD Skeleton Git history and my development conversations, and the resulting account was reviewed against the repository history before publication.
Top comments (0)