# Templates

Address: https://nowa.im/cotty/handbook/templates/  
Status: Draft  
Created: 2026-11-22

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](https://nowa.im/cotty/handbook/documentation/#metadata).

## Capability page

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

```markdown
---
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/`.

```markdown
---
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](https://nowa.im/cotty/handbook/rfc-process/).

```markdown
---
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.

```markdown
---
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/`.

```markdown
---
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/`.

```markdown
---
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/`.

```markdown
---
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.
```
