Specifications¶

Every non-trivial change to this module is written down before it is built. A spec captures the problem, the decisions taken, the options rejected and the open questions, so a later reader can see why the code looks the way it does, long after the conversation that produced it is gone.

The specs live in the project wiki. They are point-in-time decision records rather than living documentation, and keeping them in docs/ buries the documentation that is living. This page is the index; it does not carry the bodies.

How to read one¶

Each spec carries a status in its frontmatter, and that status is the single source of truth for where the decision stands:

Decisions are numbered (D1, D2, …) so reviews, merge requests and later specs can cite one precisely. A withdrawn decision keeps its number rather than being deleted, because "we proposed this and found it unnecessary" is worth as much as the decisions that survived.

Wiki pages are named specs/<NNNN>-<slug>, numbered in the order the decisions were taken. The number is the spec's handle. Cite "0005" rather than a title, which can be edited.

Where the older specs live¶

This module was extracted from go-tool-base, and the chat specs written before the extraction settled stayed there:

• Module extraction (the core/provider split this module is built on)
• Provider fallback
• Conversation persistence
• Multimodal input
• Stateless one-shot calls
• Provider-conformance suite

They stay there rather than being copied here. A spec belongs with the decision it records, and duplicating one only creates a second copy to drift. New specs for this module and its provider modules land in this project's wiki.

Provider-module specs live in this wiki too, not in the provider repos: the adapters are too tightly coupled to the core to reason about separately, which is the same reason all provider documentation lives on this site.