Guidelines

A guideline is a standard of the owner that a review checks with proof. Code can look finished and still fail a standard, for example a query that works and does not scale. A guideline makes the reviewer give a verdict for each standard, and it makes the verdict show its proof.

What a guideline is

A guideline is a rule in a rule file with a Proof field:

### SC-2: A list is paged and bounded

- **Rule:** An endpoint that returns rows reads them a page at a time.
- **Severity:** blocker
- **Proof:** The file and line of the page size, and the key of the page.

The rule files of a repository (.desk/rules/) and the packs below hold guidelines. A guideline applies to a change when the paths of its rule file match a changed file.

The packs

Pack	Rules	Covers
scalability	SC-*	The target number of users (100000, set in the pack), indexes, paging, N+1, caches, queues, limits, stateless services, online migrations
modularity	MD-*	One reason to change, one direction of dependencies, boundaries, config from the environment
code-quality	CQ-*	No stub, no made-up data, no swallowed error, no workaround in place of the cause, no test that proves nothing

Add a pack to one repository with desk packs add scalability modularity code-quality. Edit the copied rule file to fit the repository, for example the target number of users.

To apply the packs to every repository under some folders, with no file in the repository, set guidelines in ~/.config/desk/policy.json:

{ "paths": ["~/code/example"], "guidelines": ["scalability", "modularity", "code-quality"] }

A rule file of the repository with the same name replaces the pack of the policy.

What a review does

1. The packet lists the guidelines that apply, in the section "Guidelines that apply".
2. The reviewer writes one row for each guideline in guidelines of findings.json: {"id": "SC-1", "status": "met|not_met|not_applicable", "evidence": "..."}.
3. A guideline with no row makes the verdict "Review incomplete".
4. A met row needs a file and a line in evidence (src/a.ts:12). A met row with no file and line becomes a finding at the severity of the guideline.
5. A not_met row becomes a finding at the severity of the guideline. It goes through the same human gate as every other finding.
6. A not_applicable row needs the reason in evidence.
7. When two profiles give a verdict on one guideline, the worse verdict stays.

The report has a section "Guidelines" with one line for each guideline.

Proof that a reader cannot produce alone

A model that reads code cannot prove scale. Two parts add proof that does not depend on the reviewer:

• Pattern checks. Each pack has regex checks (CHK-SC*, CHK-MD*, CHK-CQ*), for example SELECT *, a read of all rows, an index that locks a table, a stub, a skipped test, a swallowed error. They warn and do not block.
• PR evidence. The key pr.evidence of .desk/config.json lists sections that a PR body needs when the PR changes files that match paths. The scalability pack adds the section "Scale evidence" for migrations, queries and models. desk pr check and desk pr create refuse a PR that changes such a file and has no text in the section, or text with no number in it. Write the query plan, the index and the row count, or a load-test result.

Settings

Key	Where	Effect
guidelines	~/.config/desk/policy.json	Pack names that apply to every repository under paths
pr.evidence	.desk/config.json	Sections that a PR needs, by changed path
checks	.desk/config.json	Pattern checks; desk packs add copies those of a pack

desk doctor warns when no rule has a Proof field.