Different Projects, Different Doc Sets

I used to think a comprehensive documentation system was the safest starting point. If one file reduced confusion, perhaps ten files would reduce even more. If a small project benefited from a plan, a larger plan might make it stronger.

That logic works until the documentation begins competing with the work.

Too little context creates one kind of failure. A coding agent has to infer the goal, the current state, the permitted change surface, or what “done” means. It may produce technically valid work that belongs to a different project than the one I intended.

Too much active context creates another kind. The agent finds several plans, several summaries, a folder of old checkpoints, and three documents that each sound current. It spends attention reconstructing history instead of completing the assignment. Worse, it may follow the most detailed document rather than the one that still holds authority.

I have experienced both ends of that spectrum. The lesson was not that heavy documentation is bad or that small projects should run on a prompt alone. The lesson was that documentation needs to match the conditions of the work.

A contained visual repair and a production data migration should not carry the same controls. A one-page experiment and a multi-stage product should not begin with the same folder tree. A security investigation may need exact checkpoints, evidence, independent review, and rollback planning; after the investigation closes, keeping all of those controls in the active path may create new drag.

Different projects need different doc sets. Different parts of the same project may need different doc sets too.

The goal is not the least documentation possible. It is the smallest sufficient documentation system: enough structure to protect the work, but no more structure than the work has earned.

“Doc set” is ordinary shorthand for a documentation set. I do not claim to have invented the term. Within my own work, however, I use Dowanski Method Doc Set for a more specific operating model:

The distinction matters. A collection of documents is not automatically a system.

A useful doc set should answer nine questions:

Those answers do not always require nine files. A small project may combine several responsibilities in one clear record. A growing project may need to separate them because purpose, architecture, current state, execution, and release change at different speeds.

This is where a doc set differs from ordinary project notes. Notes help us remember. A doc set also routes action. It tells the next person or agent where to begin, which facts are current, which boundaries are binding, which evidence is expected, and when to return control to a human.

It supports autonomous workflows, but “autonomous” does not mean unsupervised or unaccountable. It means an agent can complete a bounded assignment without requiring constant direction because the assignment, authority, stopping conditions, and verification criteria are already legible.

The easiest way to overbuild documentation is to start by copying a folder tree from the last successful project.

That tree carries invisible assumptions. It may assume several contributors, a production environment, a security boundary, a design approval process, or a release system that the new project does not have. Files that were valuable in one environment become empty ceremony in another.

I begin instead with responsibilities.

Every project needs an orientation: what it is, why it exists, its present maturity, and where to start. Every active project needs a compact statement of current truth. Every executable assignment needs a boundary, an expected outcome, and a way to verify it. Important decisions need a durable home. Known future obligations need somewhere to live without pretending they are active.

Only after those responsibilities are understood do filenames become useful.

In a typical repository, the foundation may include:

These names are not sacred. Their responsibilities are.

For example, a small PROJECT.md can contain the brief, current state, decisions, and Now / Next / Debt without losing clarity. As the project grows, those responsibilities may deserve separate files because they change at different rates. The point is not to reach the larger tree. The point is to preserve a clear operating surface.

This also changes how I think about the README. A README is not the entire memory of the project. It is the front door. GitHub describes it similarly: the place where a visitor can understand what a project does, why it is useful, how to begin, where to get help, and who maintains it.^[1] The deeper operating system should be linked from that door rather than poured into it.

Some projects remain understandable from one main set of documents. Others develop areas that need their own coordination boundary.

I think of that change as a Documentation Fractal. The same operating logic repeats at smaller scales, but the complete parent system is not copied into every child.

The model has three levels:

The Main Set governs the complete project. It owns project purpose, global current truth, durable architecture, project-wide authority, major decisions, the active documentation route, material debt, and release posture.

A Workstream Set governs one independently coordinated body of work: a feature family, migration, audit, security review, design program, recovery effort, or release. It inherits the parent’s authority and may narrow it. It may not quietly broaden it.

A Work Packet is the smallest executable fractal. It governs one coherent outcome and contains only the context required to deliver and verify that outcome.

The word “smallest” is about responsibility, not difficulty. A complicated interface and its tests may still belong in one packet if they form one result under one authority and one review gate. Splitting each action into its own file would make the paperwork more atomic while making the outcome less coherent.

I create a Workstream Set when the work has a real independent boundary. One of these conditions may be enough:

When none of those hard boundaries exists, I look for a cluster of supporting signals: several dependent packets, a distinct multi-stage outcome, durable interfaces, separate research or evidence, several sessions of work, or a separate human review package.

If those signals are not present, I keep the work in one packet. A feature name alone does not earn a folder.

This is what keeps the fractal from becoming a maze. Every child must reduce coordination cost more than it adds.

My broader working process is QDI:

Questions establish what we are actually trying to do. Documentation turns the answers into a stable blueprint. Implementation proceeds from that agreement.

In the Complete starter, QDI is the entrance. The initial questions open the conversation; relevant follow-ups and bounded research develop the blueprint. The human reviews that understanding before a separate handoff turns it into one documentation foundation. Finishing the questions is not permission to begin the build.

The v0.3.0 edition makes that conversation adaptive. You can ask the agent to guide you, work alongside you, take the research and planning lead, or challenge an existing plan. Thirty-three anchors track coverage in the background; they are not a survey you have to complete aloud. The agent builds on known answers and proposes a Light Scan, Standard Research, or Deep Research only when it can resolve a meaningful uncertainty. An agreed research sidequest has a boundary and a return point. It does not authorize a build.

The same sequence can repeat inside the documentation fractal.

At the Main Set, questions establish the project’s purpose, desired destination, environment, constraints, people, and definition of success. Documentation turns that understanding into the brief, architecture, boundaries, plan, and route.

At the Workstream Set, questions resolve the workstream’s dependencies, risks, interfaces, and relationship to the parent. Documentation creates its local sequence and acceptance boundary.

At the Work Packet, questions remove the smallest uncertainties that would otherwise force an agent to guess. Documentation defines the executable contract. Implementation produces the result.

QDI begins the work, but implementation does not finish it. The accountable cycle is:

Verification tests the claim. Review determines whether the result is accepted. Return updates the parent’s current truth, decisions, or debt without copying the entire child record upward.

That last move is easy to miss. Without it, every workstream knows what it did, but the project no longer knows what it has become.

I use three Documentation Weights: Light, Standard, and Governed.

They are not levels of professionalism. They describe how much explicit control the project currently needs.

Light is appropriate when one owner is pursuing one coherent outcome, the work is low consequence and reversible, dependencies are limited, and local evidence is enough.

Its active structure can remain compact:

The combined PROJECT.md keeps stable intent, current truth, decisions, and Now / Next / Debt visible without creating mostly empty files.

Light is not prompt-only development. It still answers the nine operating questions. It simply combines responsibilities that do not yet need separate maintenance.

Standard is my default for a project expected to grow. It fits multi-stage products, design-to-implementation work, client workflows, growing websites, and development that continues across multiple sessions or contributors.

Standard begins with one direct Work Packet. If the work earns an independent coordination boundary, the accepted workstream replaces that direct route. Future work stays in the plan until it is authorized.

Standard can add architecture, interfaces, source registers, release notes, evidence registers, or design reviews when a real responsibility earns them. It should not add them because they appear in a more comprehensive kit.

Governed is for consequential, multi-boundary, difficult-to-reverse, or recovery-sensitive work.

Identity and authorization, billing, production migrations, sensitive data, security remediation, incidents, uncertain source truth, destructive actions, and independently verified releases can all justify Governed weight.

At this weight, architecture, interfaces, release controls, workstream contracts, packet indexes, evidence registers, explicit owner review, and closeout may need separate homes. The structure is larger because the cost of ambiguity is larger.

But Governed is not the destination of a mature project. It is an earned profile or a temporary escalation. Once a risky migration or recovery effort closes, the project should return its durable conclusions to the Main Set, freeze the necessary evidence, archive the workstream, and reduce the active route.

A project can also mix weights. Its ordinary product work may remain Standard while one security-sensitive workstream temporarily operates as Governed. The heavier child protects the risky boundary without forcing the entire project to live under emergency controls.

One of the most important changes in my practice was moving from accumulating context to routing context.

A flat index can prove that files exist. It does not tell a human or agent which ones matter now.

I use an Active Reading Path: the smallest ordered route necessary for the current task. In a Standard project, an implementation route might be:

The complete Main Set is not mandatory reading for every assignment. The archive is not background reading. A closed design review is not loaded into a database repair unless it directly governs the change.

This approach aligns with the role now commonly assigned to AGENTS.md: a predictable place for agent-specific guidance that complements, rather than replaces, the human README.^[2] OpenAI has described a similar practical lesson from its own agent-first engineering: give the agent a map rather than a massive instruction manual, keep the instruction surface short, and route into deeper sources of truth.^[3]

My extension of that idea is to make the route task-aware and authority-aware. The router should say:

This reduces irrelevant context, but it also improves human resumption. After a week away from the project, I should not have to remember which of twelve files was important. The system should tell me.

Documentation can describe permission. It cannot grant permission that the real environment does not provide.

An instruction saying “deploy to production” is not deployment authority. A file claiming that a migration passed is not proof that it ran against the intended database. A screenshot can prove visible appearance, but it cannot by itself prove tenant isolation or backend behavior.

For that reason, every Work Packet should state:

I also separate four kinds of status that are often collapsed into one word:

This allows a project to say something honest and precise:

That sentence is more useful than “complete.” It tells the next person what may happen and what may not.

Evidence is selected before implementation where possible. The test must match the claim: source inspection for implementation, automated tests for behavior, browser review for responsive layout, provider state for deployment, and live checks for production behavior.

The agent can gather and present the proof. Human accountability remains where the project places it.

Documentation debt does not come only from missing files. It also comes from files that survived longer than their authority.

The most damaging document is often not obviously wrong. It is an accurate record of a past state that still looks current.

I use One Canonical Home for each active fact. Other records may link to that home or preserve a frozen snapshot, but they should not compete with it.

When the truth changes:

Not every edit deserves an archive. Git is usually the better home for routine change history. An archive is a curated historical access layer, not a second live doc set. A backup protects recoverability. An evidence store protects proof. Those are different responsibilities even when one artifact helps with more than one.

Closed Work Packets also remain closed. If new work appears later, I create a successor packet and link the earlier result as evidence. Reopening an accepted record changes the past and weakens every downstream decision that relied on it.

The active system should become easier to read after work closes. I call this current-state recompression: return the accepted result, durable decision, and surviving debt to the parent; then remove the completed execution route from everyday navigation.

The practical skill is not creating documentation. It is managing its weight.

Add structure when consequence, uncertainty, coordination, or proof burden increases. Useful triggers include:

Remove or archive structure when:

That last signal deserves immediate attention. If the route cannot identify its own authority, the documentation system is already failing its primary job.

I sometimes describe this as knowing when to trim the fat and when to add it. The metaphor is imperfect, but the judgment is real. Too little structure can starve a project of context. Too much can slow every decision and hide the work behind maintenance.

Documentation Weight should move with the project. Escalation needs a reason and an exit condition. Reduction needs verification that the smaller route still protects what the project learned.

I would begin with the conversation, not by activating the heaviest foundation. The Complete starter supports that beginning: QDI is active, while the DM foundations wait for accepted context and a separate handoff.

Define the desired outcome, the people involved, the present reality, the constraints, the non-goals, and what success would make observable.

Ask what can go wrong, what is difficult to reverse, which external systems or people are involved, where authority transfers, and what proof will be needed.

Review the resulting blueprint, remaining uncertainty, and cleanup before authorizing the handoff. Discovery depth and Documentation Weight are separate decisions; a thorough conversation can still lead to a small implementation.

Use Light only when the work is genuinely focused, reversible, and locally verifiable. Use Standard for a project expected to grow. Use Governed when a hard trust, release, recovery, or consequence boundary requires it.

Accept the destination and authorize documentation setup before adapting the foundation. That permission covers the documents, not the build.

Give the project one orientation, one active router, one home for current truth, one decision memory, and one place for Now / Next / Debt. Combine responsibilities when separation would create empty paperwork.

Tell both the human and the agent exactly where to start and how to reach the current Work Packet. Do not make the entire documentation corpus required reading.

Give it one outcome, starting evidence, questions, scope, non-goals, authority, dependencies, execution plan, verification criteria, stop conditions, and closeout requirement.

Review the adapted route and first Work Packet, then obtain explicit implementation approval before the agent begins the build.

If independent authority, release, recovery, handoff, or coordination appears, create a Workstream Set. Otherwise, keep the work close to the Main Set.

Match evidence to the claim. Record the human decision where required. Return the accepted truth and remaining debt to the parent.

Freeze the completed packet, create a successor for later work, and remove stale execution records from the active path.

Ask whether the current documentation is still the smallest system capable of protecting the work.

That question repeats for the life of the project.

The Dowanski Method is intentionally opinionated, but it is not a claim that every team should use my exact filenames or that documentation can prevent every failure.

It is a working framework developed through direct experience designing, building, auditing, operating, and repairing human-led, agent-assisted projects. The named contribution is the assembled operating model: Documentation Weights, the Main Set → Workstream Set → Work Packet hierarchy, routed context, evidence- aware status, bounded authority, and deliberate escalation and reduction.

Several parts of the system use established practices and ordinary technical language. That is a strength. A method becomes usable when it works with the surrounding ecosystem rather than renaming everything it touches.

The companion DM Library makes the framework inspectable. The Complete starter joins QDI discovery to an accepted handoff and one tailored DM foundation. Light, Standard, and Governed remain available for different conditions; downloading all three does not make all three active. The source is open to inspection, and the files remain starting points—not invisible authority.

The deeper value is not the ZIP file. It is the habit behind it:

Different projects need different doc sets because different projects carry different consequences, relationships, and unknowns. The method should respect that difference.