On this page
  1. Capability page
  2. Version design
  3. RFC
  4. Specification page
  5. Architecture page
  6. Research note
  7. Post

This page holds the skeleton of each kind of document. To start a document, copy the skeleton into a new file in both languages. The sentence under each heading says what belongs there; replace it. A section that does not apply stays, with one line saying why.

The metadata fields are defined in Documentation system.

Capability page

A capability page lives in product/. It describes one thing the product does, from the user’s side.

---
title: Name of the capability
status: draft
created: YYYY-MM-DD
---

One paragraph: what the capability is and whom it serves.

## Problem and evidence

What goes wrong today, with links to research and field notes.

## Scenarios

The numbered scenarios this capability serves.

## Behavior

Rules written as statements that can be checked. Each rule has an example.

## States

The states an object moves through, and what causes each move.

## Surfaces

What the user sees and does on each device.

## Out of scope

What this capability does not do.

## Depends on

The kernel capabilities it relies on, with links to architecture and specifications.

## Open questions

What is not yet decided.

Version design

A version design lives in versions/.

---
title: vX.Y
status: planning
created: YYYY-MM-DD
---

One sentence: the theme of this version.

## Scenarios

The scenarios that must hold after this version. They are also the acceptance script.

## In and out

What this version does, and what it deliberately leaves out.

## Changes to product design

Each change, with a link to the product page it changes.

## Technical work

The RFCs this version needs.

## Risks and open questions

What could go wrong, and what is not yet decided.

## Exit criteria

How we know the version is done.

## Retrospective

Written after shipping: what differed from the plan, and what was learned.

RFC

An RFC lives in rfcs/. The process is in RFC process.

---
title: Short name of the decision
rfc: 0
status: draft
created: YYYY-MM-DD
affects:
  - specs/example.md
---

## Summary

One paragraph: what is proposed.

## Motivation

The scenario this serves, the evidence, and what happens if nothing is done.

## Goals and non-goals

What the decision must achieve, and what it does not try to achieve.

## Prior art

What others do. Link to research; do not restate it.

## Proposal

The idea, the key invariants, and one or two examples. The exact text is in the affected pages.

## Alternatives considered

Each alternative, and why it was not chosen.

## Compatibility and migration

What existing behavior, data or documents are affected, and how they move.

## Security and privacy

What the decision exposes or protects.

## Drawbacks and risks

What this costs, and what could go wrong.

## Verification

How we will know it is correct.

## Open questions

Empty, or each question deferred with a reason, before acceptance.

## Implementation

The order of work, and the pages and files to read first.

Specification page

A specification page lives in specs/. It is written for someone implementing it outside the project. It uses the words “must”, “should” and “may” for requirements.

---
title: Name of the protocol, format or API
status: draft
created: YYYY-MM-DD
---

One paragraph: what this specifies and who implements it.

## Stability and version

Whether this is experimental or stable, and its version. Only stable parts carry a compatibility commitment.

## Problems with the status quo

What cannot be done today, or is done badly.

## Quick start

One example that can be run as written.

## Terms and invariants

The words this page uses, and what always holds.

## Format and semantics

The exact format, and what each part means.

## Detection and fallback

How a program finds out whether this is supported, and what happens where it is not.

## Relation to existing protocols

How this fits with what terminals and agents already use.

## Security considerations

What an attacker could do, and what limits it.

## Examples and test vectors

Inputs with their expected results.

## Known implementations

Programs that implement this.

Architecture page

An architecture page lives in architecture/.

---
title: Name of the component or mechanism
status: draft
created: YYYY-MM-DD
---

One paragraph: what this part does and where it sits.

## Compatibility policy

What must keep working, and what may break.

## Goals and non-goals

What this part must achieve, and what it does not try to achieve.

## Concepts and invariants

The objects involved, and what always holds.

## Execution traces

Step-by-step traces of the main paths, including the points where a crash can happen and how recovery proceeds.

## Interfaces and implementation

The interfaces this part offers, and how it is built.

## Open questions

What is not yet decided.

## Testing strategy

How correctness is checked.

## Required reading

The pages and files to read before working on this part, in order.

Research note

A research note lives in one of the folders of research/.

---
title: The question, or the subject
created: YYYY-MM-DD
as_of: YYYY-MM-DD
---

One paragraph: the question and the short answer.

## Findings

The facts. Each claim carries its reliability: official, vendor, or third party.

## What this means for cotty

The consequences for product or technical design.

## Sources

Links to everything used.

## Not covered

What was not looked at.

Post

A post lives in posts/.

---
title: The claim, or the subject
created: YYYY-MM-DD
---

One paragraph: the claim, and why it matters to cotty.

## The argument

One section for each step, named by what it says. A fact that has a date belongs in a research note, and the post links to it.

## What we take from this

What follows for cotty, with links to the state documents.

## References

Links to everything the post relies on.