In my recent attempt at a definition of spec-driven development, I identified two degrees of freedom that characterize a form of SDD: its abstraction level and its overall level of human involvement.
Since I am currently thinking about defining my own SDD method, I considered where I wanted to place it on both these axes. While I found it easy to name the intended abstraction level, I rather struggled to express the desired overall level of human involvement. The problem is that the definition itself only names the two extremes ("fully manual" and "fully autonomous") on this axis. Everything in between has received a passing mention at most.
This two-part post fills that gap and characterizes various overall levels of human involvement between these two endpoints.
In this first part, I will define levels of human authorship for a single artifact. In part 2, I will combine them into overall levels of human involvement.
The approach
As outlined in a previous post, every SDD method produces a chain of artifacts and transitions between them from intent to requirements, to spec, to design, to source code, to binary, to execution. Of these, my definition of SDD mandates that the translation to source code be fully autonomous. Since in practice all steps that come afterward (source code to binary to execution) require very little or no human involvement at all, what really matters are the first three steps in the chain from intent to design. Manual code changes, which my definition allows, do not substantially affect this reasoning, since the spec and the design, not the code, remain what defines the deliverable.
Each of these three steps produces a text-based artifact. The idea is to measure the level of human authorship for each of the three artifacts individually. Since some artifacts can contain both natural language (prose) and formal language (code), the approach must work equally well for both.
As before, the requirement-level key words follow RFC 2119 and RFC 8174. Furthermore, the term classic is used here in the sense of pre-AI.
How to measure authorship
The idea is to root each level in two measurements: the significance of a contribution (what aspect of the artifact it touches) and its impact (how deeply it shapes that aspect).
For the significance, we need to consider the different layers of any text-based artifact:
| Layer | Domain | Examples |
|---|---|---|
| Format | Appearance | character encoding, file type, layout (orientation, margins, columns, spacing, alignment, headings, paragraphs, fonts, colors) |
| Language | Expression | spelling, syntax, grammar |
| Style | Aesthetics | wording, phrasing, tone, conventions, standards, best practices |
| Content | Substance | facts, data, ideas, arguments, logic, structure |
The layers are listed in order of increasing significance. Fixing a syntax error has hardly any bearing on the overall result, in contrast to fixing a logical error. Furthermore, for the purpose of SDD and technical writing in general, contributions to the format layer are considered insignificant. In today's world, the use of text editors, code formatters, and comparable tools has no impact on the level of human authorship. Therefore, only the three most significant layers (language, style, and content) will be considered from here on.
The impact is reflected in the role each side, humans and machines, plays on each layer of the artifact. The roles are defined in terms of actual influence and ordered by depth of impact. Each side holds exactly one role per layer: the highest one any of its contributions to that layer reached over the entire history of the artifact. From lowest to highest:
| Role | Description |
|---|---|
| Bystander | Makes no contribution to the artifact and has either no or at most an organizational influence on the artifact or its development. In the latter case, triggers, supports, or calls for a contribution by the other side without prescribing what to contribute or how to contribute it. |
| Expert | Informs the other side about facts and figures without being influenced by either the artifact itself or the intent to create or edit it. Does not edit the artifact. Experts influence the artifact only in an indirect and untargeted manner since their contributions are unrelated to the artifact and they are possibly even unaware of it. |
| Editor | Reviews, advises on, and revises (corrects, cleans up, restructures, converts, translates) the artifact, but does not make substantial or original contributions. |
| Author | Makes substantial contributions: new and original work that cannot be derived from the artifact and its input. |
A contribution counts no matter how it reaches the artifact. A side that supplies new ideas in any form (a prompt, a chat reply, a review comment) is an author of the content, even if the other side does all the writing and thereby authors the language and style. A contribution is substantial if it cannot be derived from what is already there, meaning the artifact and its input. Fixing a bug restores what the spec already requires. Adding rate limiting introduces something new, however small the change.
Not everything that shapes an artifact is a contribution to it, however. Input sets the stage: it is what the artifact needs in order to exist meaningfully. In the regular case of SDD, that is the intent for the requirements, the requirements for the spec, and the spec for the design. Contributions then put on the play. Input is not a contribution and earns its source no role on the artifact.
The history of an artifact includes contributions that were later deleted, but not rejected proposals, which count at most as advice. The one way to remove a contribution from it is a rollback in the strict sense of version control: if the artifact is restored to an earlier version, everything made after that version is gone, and the history continues from there.
For a deeper understanding of these roles, here are examples of the impact of every role on each of the three layers.
| Language | Style | Content | |
|---|---|---|---|
| Bystander | Trigger a spelling check. | Remind an artifact author that a style review is due. | Provide project or knowledge management functionality (mind maps, to-do lists, wikis, Kanban boards) used by an artifact author to organize ideas and plans regarding the artifact. |
| Expert | Publish an English grammar book which is read by an artifact author. | Run a classic website about coding conventions which is found via classic web search and consulted by an artifact author. | Write a blog post about a topic relevant to the artifact which is taken into account by an artifact author. |
| Editor | Correct spelling, grammar, and syntax errors. | Rewrite a sentence or paragraph to sound more convincing. | Conduct a code review and point out a severe logical flaw. |
| Author | Write only in a controlled natural language such as Simplified Technical English. | Rewrite the artifact so that a ten-year-old can understand it. | Write a new paragraph or chapter from scratch, or supply its ideas for the other side to write down. |
Levels of human authorship (artifact levels)
With this, I suggest distinguishing between the following six levels of human authorship of a text-based artifact. An artifact is rated as a whole, however many files it spans. Where that is too coarse, the deliverable can be split into smaller deliverables with artifacts of their own. The tooling listed for each level is typical, not defining. What counts is how a tool is used, not which tool it is.
The levels are named after the contribution of the machine because historically full human authorship was the norm. Each level is defined by exact conditions on the roles, so every artifact meets exactly one of them. Since naturally all layers always exist in every artifact and as such have an author, the lack of an author on one side forces the author role onto the other side.
Level 5: Machine-free
Machines MUST be at most editors of the language. Machines MUST be at most experts on the style and content. It follows that humans MUST be authors of the language, style, and content.
A machine ensures the correctness of the language. It fixes violations of the rules but does not apply improvements. It does not change anything that is already valid.
Humans are free to learn from anything that already exists, including books or articles created by or with the help of machines, since these were not made for the artifact. The same goes for what they took from earlier exchanges with machines (discussions, web search AI summaries). Once they intend to create the artifact, however, any such exchange is ruled out. Classic web search remains allowed.
Typical tooling: spell checkers, and compilers or interpreters reporting syntax errors.
Level 4: Machine-polished
Machines MUST be at most editors of the language. Machines MUST be editors of the style. Machines MUST be at most experts on the content. It follows that humans MUST be authors of the language, style, and content.
A machine rephrases a sentence, changes the tone, translates the artifact, or enforces a coding standard, but it does not apply any semantic changes.
Typical tooling: writing assistants, linters, and classic autocomplete.
Level 3: Machine-assisted
Machines MUST be at most editors of the language and the style. Machines MUST be editors of the content. It follows that humans MUST be authors of the language, style, and content.
A machine corrects a paragraph or fixes a bug, but it does not add a new idea.
Typical tooling: AI assistants.
Level 2: Machine-coauthored
Machines MUST be authors of at least one of the language, the style, or the content. Humans MUST be authors of at least one of the language, the style, or the content.
This is shared authorship. Either side may take the initiative, and either side may revise what the other one wrote. The shares do not need to be equal: a single new idea from each side is enough.
Typical tooling: AI agents working on the same artifact as a human, side by side.
Level 1: Machine-authored
Humans MUST be at most editors of the language and the style. Humans MUST be editors of the content. It follows that machines MUST be authors of the language, style, and content.
A machine creates a full document or program. Humans review it, give feedback, and either revise what the machine wrote or approve it, but they do not add anything new.
Typical tooling: AI coding agents executing a task and asking for human review (in a pull request, for example).
Level 0: Machine-only
Humans MUST be at most editors of the language and the style. Humans MUST be at most experts on the content. It follows that machines MUST be authors of the language, style, and content.
A machine creates a full document or program without any human intervention beyond a launch prompt that starts the process and at most passes its input to it.
Typical tooling: AI agents in an automated pipeline.
Summary
The level definitions can be summed up in the following decision tree:
A) Are humans authors of at least one of language, style, or content?
Yes -> B
No -> E
B) Are machines authors of at least one of language, style, or content?
Yes -> Machine-coauthored
No -> C
C) Are machines editors of content?
Yes -> Machine-assisted
No -> D
D) Are machines editors of style?
Yes -> Machine-polished
No -> Machine-free
E) Are humans editors of content?
Yes -> Machine-authored
No -> Machine-only
Remember that the role each side holds is determined by the highest impact of any contribution over the entire history of the artifact. Therefore, apart from a rollback, roles can only move upward toward author, and with this, artifact levels can only move toward machine-coauthored, but never away from it.
Where this post stands
Now that we have clearly defined levels at our disposal, they deserve to be applied at least once, so here is this post.
I wrote the first draft myself, so the start was machine-free. Then a machine reviewed it, flagged issues, and proposed fixes, which makes it machine-assisted. The proposed fixes led to an intense discussion that ended in the decision to have separate artifact and method levels. At that point I asked the machine to restructure the entire post and to propose level names and aggregation rules. This brought us to machine-coauthored, which, as pointed out above, cannot change anymore short of rolling back everything since. The restructuring went only moderately well and was followed by more rewrites and reviews than I am willing to publicly admit to.
The announcements on LinkedIn, X.com, and daily.dev will be machine-authored as usual: I tell the machine that it is time to generate them, the machine writes them, and I review them, occasionally demanding a rewrite to try a different approach.
In part 2, I will combine the levels of human authorship of the three artifacts into one overall level of human involvement and finally put a name to my own SDD method.
Top comments (0)