Document Status Is Derived, Not Recorded

I opened a project documentation page in KotaPortal and saw a "Status: Active" banner at the top of the file. The last-updated date said six months ago. Meanwhile, the execution plan inside it had already been fully carried out, and the system architecture had changed completely. The documentation was lying.

My first reaction was to add stricter validation. I once tried building a small script that scanned file modification dates. If a file had not been touched for 30 days, the script would attach a "Needs Review" label. The result was the opposite of what I wanted. Developers got annoyed by false alarms, and they started editing whitespace in files just to reset the timer, without actually updating the content. Forcing humans to keep metadata in sync with reality is a recipe for failure.

The actual solution runs against that instinct. Instead of recording status on every page, document status should be derived automatically from the folder location, the document type, and events on the project management board.

The Four States of a Document Lifecycle

This mechanism splits the documentation lifecycle into four mutually exclusive states. The approach removes the possibility of a document lying about its state, because status derived from directory structure cannot go stale on its own.

The first state is truth. This category holds contract documents that change only through verbatim addenda. No status ever needs updating, because their nature is absolute and binding.

The input state holds research files, client intake notes, or a Product Requirements Document (PRD). Consumption of these documents is tracked through a backlink register, not through manually maintained status labels that writers easily forget.

The active directory holds the index, the log, and the schema that are maintained for the life of the project. Their status is inherently active because they sit in the core directory the team consults every day.

Finally, the frozen state holds executed plans, meeting notes, and superseded pages. Documents in this category are never edited. When a revision is needed, the system creates a new document with the next sequence number instead of overwriting the old file [2].

This status-derivation practice aligns with how Architectural Decision Records (ADR) are managed. An ADR captures a single decision together with its rationale, and the collection of ADRs in a project serves as its complete decision log [1]. When a decision is reversed, the old file is not removed. The system keeps it and marks it as superseded. ADR sequence numbers stay strictly monotonic and are never reused [2].

The split also supports the Diataxis framework, which divides documentation into four forms based on user needs: tutorials, how-to guides, reference, and explanation [3]. Each form has a different update cadence, so forcing one universal status column onto all of them only creates unnecessary friction.

Deriving Status in Practice

To apply this pattern, build a directory structure that physically mirrors the four states. Moving a file into the archive folder automatically changes its status to frozen. The folder becomes the real state machine, with no extra metadata column required.

The client intake protocol gets stricter under this pattern. New client data lands in a .docs/intake/YYYY-MM-DD-topic folder as immutable raw material. Normalizing that data then becomes a separate task on the project management board. The team never edits the raw files to reflect a status change. Instead, they create a new file in the active directory that references the raw material as its original source of truth.

Events on the project management board, such as moving a ticket to the "Done" column, automatically trigger updates in the active index, not in the frozen document itself. Current work status lives on the board, never inside a document.

Legacy folders stay where they are, frozen. Carelessly moving old files would break wiki links that have formed across the repository. Instead, the main index gets an annotation stating that those sections are in the frozen state, preserving navigation integrity without sacrificing historical accuracy.

Stopping manual status recording forces the team to think about information structure instead of filling in metadata forms. When the folder decides the state, documentation stops lying.

Sources

Architectural Decision Records (ADRs), accessed October 10, 2026.
Michael Nygard, Documenting Architecture Decisions, accessed October 10, 2026.
Diataxis: a systematic approach to technical documentation authoring, accessed October 10, 2026.