On this page

Guidedog / Documentation 0.2.0

Work on a discussion

A GDS explains one decision. Start with the problem and the proposed result. State the assumptions. Give a worked example. Name the alternatives. Keep the implementation status separate from the proposal.

Create and inspect

guidedog gds new "Cache policy" --author="Ada" --labels=build
guidedog gds show cache-policy
guidedog gds list --state=prediscussion

The draft has an XXXXX number. Its filename ends in .rst. Metadata occupies the first field list. Authors and labels are JSON arrays. Dates are real ISO calendar dates. Keep the title and the explanation in the record.

:gds-number: XXXXX
:gds-title: Cache policy
:gds-state: prediscussion
:gds-type: Standards Track
:gds-authors: ["Ada"]
:gds-created: 2026-10-01
:gds-updated: 2026-10-01
:gds-discussion: Local review
:gds-labels: ["build"]

Cache policy
============

Abstract
--------

State the decision and its observable result.

A record needs an Abstract and References section. Use RST tables, Graphviz diagrams, and math directives where they clarify the reasoning. Do not hide normative prose in a typesetting include.

Review and promote

guidedog gds check
guidedog gds promote cache-policy --dry-run
guidedog gds promote cache-policy

Promotion assigns a permanent number and opens discussion. It does not accept the design. Numbered records are not renumbered or reused. The CLI updates the registry and reading order in the same recoverable transaction. Review prose links after a filename changes; promotion does not rewrite them.

Fig. 1 A number identifies a record; a state expresses its review result.

Record a decision

guidedog gds state 4 --to=accepted --reason="Review converged"
guidedog gds state 4 --to=committed --reason="Implemented" --evidence="Tests and review"

A committed state requires evidence. The source history is not evidence by itself. Do not claim another person’s approval. The maintainer owns the state decision.

Publish and recover

guidedog gds index
guidedog gds build --target=both
guidedog gds build guidedoc-odin --target=pdf
guidedog gds recover --rollback

HTML builds the whole discussion site. A selector limits separate PDFs. A selected PDF preview uses _build/selected/<artifact>/pdf. It leaves the complete catalog in _build/pdf intact. The project outputs live in _build/html and _build/pdf. An interrupted metadata edit needs explicit rollback. Recovery refuses a later edit that conflicts with its journal. Inspect the conflict before retrying.

Read The Guidedog Discussion Process for the process contract. Read Guidedog: CLI and documentation toolchain for the CLI contract.