> For the complete documentation index, see [llms.txt](https://novusedge0.gitbook.io/docket-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://novusedge0.gitbook.io/docket-docs/everyday-use/recording.md). # Recording decisions Record a choice when you make it, while the reason is still clear. Add a claim when a statement matters to later work, or a question when you need to leave something open. You do not need to record every step of a conversation. Keep the things another person or agent would need to understand before continuing the work. ## Choose a record type | Use a… | When you want to say… | | ------------ | ------------------------------------------------------------ | | **Claim** | “This is a statement we should assess or check again later.” | | **Decision** | “This is the choice we are committing to, and here is why.” | | **Question** | “We still need an answer to this.” | The examples below form one small ledger. They assume you start with no records. If you use an existing ledger, substitute the IDs printed by your commands. ## Save a statement you are relying on Suppose you have checked the service configuration and confirmed that it uses Postgres: ```sh docket claim "The service already runs Postgres" \ --state accepted \ --evidence "terraform/db.tf" \ --scope "billing/**" ``` This creates `c1`. The evidence field points a later reader to the file you checked. Without `--state accepted`, a claim starts as `unassessed`. You can also record it as `disputed` or `rejected`. Docket stores your assessment; it does not check the evidence for you. ## Record the choice and its reason ```sh docket decision "Which database should billing use?" \ --choice "Postgres" \ --rationale "Use the database we already operate" \ --supports c1 \ --scope "billing/**" ``` This creates `d2`. The `--supports c1` link lets a reader follow the choice back to the claim behind it. You can record a decision without a support link when there is no earlier record to cite. For a choice that deserves more explanation, add `--alternative` for another option you considered or `--cost` for what would happen if the choice were wrong. Use `--decided-by` when you are recording a choice that someone else made. ## Leave a question, then answer it First, record the open question: ```sh docket question "Which database driver should billing use?" \ --scope "billing/**" ``` This creates `q3`. Later, link your choice to it: ```sh docket decision "Which database driver should billing use?" \ --choice "psycopg" \ --rationale "Use the driver already configured in the service" \ --answers q3 \ --scope "billing/**" ``` This creates `d4`, and `q3` now appears as `resolved`. A current accepted claim can also answer a question, which is useful when you needed a fact rather than a choice. An answer must still be current to resolve the question. A decision must also be adopted and have any required prerequisites available. The [relationship rules](/docket-docs/technical-reference/ledger.md#answers-and-supersession) explain the details. ## Change an earlier choice Add a new decision that names the one it replaces: ```sh docket decision "Which database driver should billing use?" \ --choice "asyncpg" \ --rationale "The billing worker now uses an async database interface" \ --supersedes d4 \ --answers q3 \ --scope "billing/**" ``` This creates `d5`. The old decision disappears from the default list, but `docket show d4` still shows it. The `--answers q3` link keeps the original question answered by your new choice. If you drop a commitment without choosing a replacement, record a revoked decision that supersedes it: ```sh docket decision "Which database driver should billing use?" \ --choice "asyncpg" \ --state revoked \ --supersedes d5 \ --rationale "Billing is moving out of this service" \ --scope "billing/**" ``` The previous commitment is now retired. With no current answer left, `q3` appears as open again. Use the same approach to revise a claim: write its new assessment and add `--supersedes` with the old claim's ID. A replacement must have the same record type as the record it retires. ## Make records easier to find Use `--scope` for a path or pattern such as `billing/**`. Repeat it if a record applies to several parts of the project. Write enough in `--rationale` for someone to understand the choice without the original conversation. Add `--revisit` when there is a clear reason to check it again, such as a dependency upgrade. `--pin` gives a record more weight in briefings. It does not guarantee inclusion, so a useful scope is still worth adding. For operational prerequisites, use `--depends-on` on a decision. These are different from the reasons recorded through `--supports`. See [Decision prerequisites](/docket-docs/technical-reference/ledger.md#decision-prerequisites) when you need them. Next, use [Reading your ledger](/docket-docs/everyday-use/reading.md) to find records and follow their history. The [command reference](/docket-docs/technical-reference/commands.md#recording) lists the recording flags. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://novusedge0.gitbook.io/docket-docs/everyday-use/recording.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.