documentation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Documentation

Docs under `docs/`, protocol docs, mockups, and every `README.md` are part
of the spec. Keep them aligned with the behaviour of the implementation in
the same change. A doc is stale when it contradicts the code. A doc that is
silent on a detail is not stale. When a change removes or renames anything,
search `docs/`, `plans/`, and every `README.md` for its name; see the
`git-commit` skill. Mockups have their own rules in the `mockups` skill.

## The home of each kind of content

Each fact lives in one place. Other docs link to it.

| Content | Home |
| --- | --- |
| A requirement: observable behaviour at a boundary | The protocol doc |
| A decision in force, with the rejected alternative and the reason | The protocol doc, next to its requirement |
| Components, their responsibilities, and their boundaries | The architecture doc |
| Entry points into the code: files, types, functions | The crate or area `README.md`, under `### Key Code` |
| How the code works: mechanics, call order, module layout | The code and its doc comments |
| The design of one change, its dated decisions, and history | The plan under `plans/` |
| Cases and examples | The tests |
| An API surface, a schema, a type list | Generated reference |

## Workspace README

- A summary of the key features of the project, not a long list of every
  feature.
- User-facing interface documentation: CLI, API, and similar.
- Developer get-started steps.
- Key code jumping-in points.
- Links to the architecture doc, the protocol docs, and the `plans/`
  directory.

Read the `README.md` for the area you work on before you change it, and
update it with any new useful context in the same change.

## Rust crate READMEs

- Treat every crate `README.md` as user-facing documentation good enough to
  publish on crates.io.
- Start with a short statement of what the crate is for, where it fits in
  the workspace, and when a caller should depend on it.
- Document the public behaviour and integration boundary, not only internal
  implementation details.
- Include these sections, in this order: `## Responsibilities`,
  `## What This Crate Does`, `## Quick Start`, `## Development`,
  `### Key Code`, `### Related Docs`.
- `## Quick Start` includes example code or runnable commands, not only
  prose.
- `### Key Code` names the entry points: the files, types, and functions
  that a reader opens first, each with one sentence on what it does. This
  is the home of code references, so that protocol docs do not need them.
  Update it when an entry point moves or changes.
- `### Related Docs` links to the protocol docs and the architecture doc
  that the crate implements.
- For binary crates or user-facing tools, document the CLI or external
  interface, not only the internal architecture.
- Keep examples aligned with the real public API and current behaviour. Do
  not describe internals that callers cannot use directly.
- Keep crate READMEs concise and high-signal: main use cases and
  boundaries, not every file or minor feature.
- When a crate has important neighbouring crates, name them and explain the
  boundary so that ownership is clear.

## Docs (`docs/`)

- Docs stay aligned with the behaviour of the implementation. Fix a doc
  that contradicts the code in the same change.
- Docs are consistent with themselves: no conflicting statements.
- Docs may be nested in multiple directories.
- A gap in the requirements found during implementation is a decision
  when it passes the decision test in the `decisions-and-findings` skill.
  See "Protocol docs change with the behaviour" below.

## Architecture docs

An architecture doc describes the structure that no single piece of code
shows: the components of the system, the responsibility of each, the
boundaries between them, and the flow of data across the boundaries. It
lives under `docs/`, for example `docs/architecture.md` or
`docs/architecture/<area>.md`.

- Describe components and their responsibilities, not modules, files, or
  functions. Code-level structure goes stale on every refactor. A component
  boundary does not.
- Keep few architecture docs: one for the system, and one for a large area
  when the system doc passes the length target.
- Update an architecture doc when a component, a responsibility, or a
  boundary changes. A change inside a component needs no update.
- Apply the same length target as protocol docs.

## Generated reference

Reference content lists what exists: an API surface, a schema, a type list,
a command list. Hand-written reference drifts on every addition.

- When a generator exists, generate the reference from the code and commit
  the output. The `shared-types` skill gives the generators for types that
  cross between Rust and TypeScript, and utoipa gives the OpenAPI document
  for an HTTP API.
- Keep in prose only the semantics that a generator cannot express, such as
  idempotency, authorization, and ordering rules. These are requirements and
  belong in the protocol doc.
- Do not hand-edit generated output. Regenerate it in the same change as
  the code.

## Protocol docs (`docs/protocol`), the specs

A protocol doc holds the requirements and the decisions in force for one
area. A human reviews it before implementation starts. The post-push review
checks the behaviour of the code against it. Every change to a protocol doc
is therefore a change to a requirement or to a decision, and is worth a
review.

- A requirement states observable behaviour at a boundary: an interface, a
  wire format, a state transition, an error, a limit, or what a user sees.
  Write one requirement in each sentence.
- Apply this test to every sentence: could a different implementation

From futex-ai/skills, MIT.

More from futex-ai/skills