Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 30 additions & 65 deletions .claude/engineering-standards.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,65 +13,37 @@ everywhere else.

## 0. How the standard works with what these repositories already do

These rules come from decisions the owner has already made, and they shape how
the rest of this file is applied.

**Ask first when the request is unclear or consequential.** The owner's
standing instruction is to ask clear clarifying questions before running code
when a request is ambiguous, when it names no target, or when the work would be
hard to undo. When the request is clear and the step is reversible and low
risk, do the work instead of stopping at a plan (section 17).

**Deploys cost money, so changes are batched.** On 13 October 2026 the Netlify
team ran out of credits and all 35 of its sites went offline. Netlify charges
15 credits for every production deploy it publishes. A deploy preview, and a
build that is never published, cost nothing. So:

- Work on the session's development branch and push there. Open a pull
request only when the owner asks for one, and never merge without being
asked.
- Build all day and publish once. Do not merge on your own judgement: the
owner merges, and nothing goes live before 20:00 IST. Do not use Firecrawl
where curl or a web search will do; its credits are paid for.
- Every site on the Netlify team has auto-publishing locked except
democracybydesign.in, which must be able to take a photograph down at once.
A merge builds but goes live only at 20:00 IST, once a day, when the "Publish
locked sites" workflow in Democracy-by-Design (`tools/publish-locked.py`)
publishes the newest finished build of each locked site. The script reads
the locked set from Netlify, not from a list. Running that workflow by hand,
with a site name, publishes at once. A green build is therefore not a live
change; say which one you have verified.
- A workflow that commits to the production branch on a schedule makes a
build each time. On a locked site that build is free until the next publish
window; on democracybydesign.in, or on a site someone unlocks, every such
commit is a paid deploy.
- Dependabot runs monthly, groups its updates into one pull request per
ecosystem and opens at most two at a time. A weekly stream of pull requests
invites a weekly stream of merges.

**Hosting.** Porkbun is the registrar and nothing else; Netlify does hosting
and DNS (owner's rule, 12 October 2026). A few repositories also publish to
GitHub Pages, and their `CLAUDE.md` says so. Do not move a site between hosts
**Ask first when the request is unclear or consequential.** Ask clear
clarifying questions before running code when a request is ambiguous, names no
target, or would be hard to undo. When the request is clear and the step is
reversible and low risk, do the work instead of stopping at a plan (section 17).

**Deploys cost money, so changes are batched.** A production deploy can be a
paid event. Work on a development branch, open a pull request only when asked,
and never merge without being asked. Gather related changes into one merge
rather than several. A deploy preview, and a build that is never published, cost
nothing. A green build is not a live change; say which one you have verified.
A workflow that commits to the production branch on a schedule makes a build
each time, so check what that costs before adding another. Dependency updates
should arrive monthly, grouped, a few at a time.

**Hosting.** Keep the hosting a project has. Do not move a project between hosts
unless asked.

**Writing.** Everything a reader sees, including README files, documentation,
commit messages, issue text and the reports to the owner, follows the owner's
writing rules: plain full sentences with facts and sources; no em dashes; no
"X, not Y" or "not only... but also" constructions; no stock vocabulary
(robust, leverage, seamless, crucial, delve and the rest of the owner's list);
sentence-case headings; no emoji; no bold leads. Several repositories enforce
part of this in CI (`check-copy-tells.py`, `check_writing.py`, `BANNED` lists).
A check passing does not mean the prose is right.
commit messages, issue text and reports, uses plain full sentences with facts
and sources; no em dashes; no "X, not Y" or "not only... but also"
constructions; no stock vocabulary; sentence-case headings; no emoji; no bold
leads. Several repositories enforce part of this in CI. A check passing does not
mean the prose is right.

**Websites talk about their subject, never about themselves.** No page tells a
reader how it was built or researched ("read twice", "the build fails unless",
"generated by"). That belongs in `CLAUDE.md` and the research files (owner's
rule for every website, 14 October 2026).
"generated by"). That belongs in `CLAUDE.md` and the research files.

**Numbers.** Never restate a count copied from another repository, a partial
read, or prose that nothing checks. Take it from the source at build time, pin
it with a check, or stop stating it. Every repository that drifted did so this
way.
it with a check, or stop stating it.

**Checks must be able to fail.** No `|| true`, `|| echo`, `2>/dev/null` hiding
the reason, or `fail: false` on a gate. A long job that talks to third-party
Expand All @@ -84,19 +56,12 @@ the commit says it was.
opacity, a control no keyboard reaches, a row wider than a phone, and an
`element.hidden` overridden by a `display` rule. After any change to colour,
layout or the header, measure in a browser: axe at 390x844 and 1280x900 in both
colour schemes, and `scrollWidth` against `clientWidth`. Chromium is installed
in the cloud sandbox; it reaches localhost and not the internet, so stub CDN
scripts by route.

**Privacy and law.** Most of these repositories are public. Fourteen were
private on 2026-10-19: Chromalie, Democracy-by-Design, INDIA-DATA,
IdealogWorks, WhoGaveTheOrder, WomenOnRecord, allthegoodstuff,
impactmojo-field-notes-pro, impactmojo-workshop-pro, makeitpop,
phototales-studio, pika-woodcraft, pinpointventures and storywell. A private
repository can be made public with one click, and everything in its history
goes with it, so treat every one as public: never commit a secret, a
personal email address that is not already the published contact, or
row-level personal data (names, EPIC numbers, phone numbers). No survivor or
colour schemes, and `scrollWidth` against `clientWidth`.

**Privacy and law.** Treat every repository as public: a private repository can
be made public with one click and its whole history goes with it. Never commit a
secret, a personal email address that is not already the published contact, or
row-level personal data (names, ID numbers, phone numbers). No survivor or
private person is named on a page. A licence, a privacy claim or a compliance
claim that needs a decision goes to the owner; record it as outstanding rather
than inventing it.
Expand Down Expand Up @@ -316,8 +281,8 @@ Never say a feature was tested when it was read or inferred.
The cloud session clones each repository shallow. A script that reads git
history (a change log, a feed, a "last updated" date) either refuses to run or
writes a different answer from CI, and a refusal can look like a clean diff.
Run `git fetch --unshallow` before trusting it. WhoGaveTheOrder's `build.js`
refused, and the empty diff was briefly read as a pass (2026-10-19).
Run `git fetch --unshallow` before trusting it. A script that refuses can leave
an empty diff, and an empty diff is not a pass.

## 7. CI/CD and dependencies

Expand Down
Loading