Skip to content

Decision records get a current-design layer and a domain index #726

Closed

Description

@WaylandYang

docs/decisions/ holds 44 records (about 4,500 lines), flat and numbered in creation order. One topic is spread across many numbers (ontology: 0001, 0003, 0006–0012, 0036, 0044; time: 0019, 0022, 0024, 0031, 0045; governance: 0017, 0025–0028, 0043). Knowing what the current design is means reading the history, because later records revise earlier ones in part and the index status lines have grown into paragraphs. A file name says when a record was written, not what it is about or whether it still holds.

Proposal

docs/
  README.md        index by domain: current design and history; each record with date,
                   title and one status word (current, partly superseded, superseded);
                   a table from old numbers to new paths
  design/          current design, one file per domain, under 150 lines each:
                   what it does, why, links to the evidence, open questions
  decisions/       history, one subdirectory per domain, files named
                   YYYY-MM-DD-short-title.md, contents unchanged, original number in the header

Domains (to confirm after reading each record): ontology, extraction, identity, ledger and time, governance and review, rules and reasoning, sources and ingestion, lakehouse and actions, access and audit, interface, chat and MCP.

Conventions change with it: a design file changes when the design changes; a decision record records why, and is never rewritten (the existing revision-in-place rule). Code comments referencing numbers (about 40 sites) stay valid through the index table and are updated as touched.

Sequence

After #699, #710 and #724 settle, in one documentation PR. Every record is read before it is filed; titles alone misfile some (0014 is about access, not identity).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions