Contributing to the Backend Handbook

This handbook is for human readers — new hires, on-call engineers, reviewers. It is written in prose, with motivation and examples, and assumes you can ask questions. If you find a chapter unclear, fix it.

How to propose a change

Branch from main. Use a descriptive branch name such as docs/clarify-actions-naming or docs/add-rental-domain-glossary.
Make your edit. Keep the chapter scoped to one topic — splitting an oversized chapter is usually a better move than appending.
Update the last_reviewed frontmatter at the top of every file you touch to today's UTC date.
Open a PR against main. At least one reviewer must approve before merge.
Squash-merge on approval. Commit subject follows Conventional Commits — usually docs(<section>): <change>.

Tone

Lead with motivation. A chapter that opens with rules is a chapter that gets skimmed. Open with why the pattern exists, then state the rule.
Narrative over imperative. "Wrap multi-statement writes in a transaction so a partial failure can't leave orphan rows" reads better than "MUST use DB::transaction".
Severity uses the shared icon set, never emojis or custom colours. Critical = :icon{name="i-lucide-shield-x" class="text-red-500 ..."}. Warning = i-lucide-shield-alert + text-amber-500. Suggestion = i-lucide-shield-check + text-emerald-500. Copy from an existing chapter so the class string stays consistent.
Longer examples are fine. Where a rule card shows a five-line snippet, the handbook can show a fifteen-line snippet with surrounding context. Readers benefit from seeing the shape of a realistic file.
Cross-link liberally. When you mention a related concept, link to its chapter. The handbook is a graph, not a list.
English only. The application has Arabic translations; the handbook does not. Keep terminology consistent with the codebase even when that means Arabic loanwords or product names.
No emojis in headings. Body prose may use a small number of emoji for emphasis, but #, ##, and ### lines stay plain text.

Frontmatter

Every chapter starts with:

---
last_reviewed: YYYY-MM-DD
---

Use today's UTC date when you make a substantive edit. Pure typo fixes do not need a date bump.

Diagrams

Inline Mermaid renders natively on GitHub — use it for sequence diagrams, swim lanes, and simple flows. For diagrams Mermaid cannot express, export an SVG or PNG into diagrams/ and reference it from the chapter with a relative image tag.

Relationship to the `.claude/skills/winch/` rules

The backend repository ships a sibling set of AI-facing rule cards at winchsa/backend/.claude/skills/winch/. Those files exist to brief Claude Code during automated tasks — they are terse, imperative, and use severity emojis the reviewer agent depends on.

This handbook and those rules evolve independently (call this Option A). There is no auto-sync between the two. The trade-off is intentional:

The skill files are optimised for an AI assistant doing one task at a time — they need to be scannable in a few seconds.
The handbook is optimised for a human learning a system — it needs narrative, motivation, and longer examples.

What this means in practice:

When you change a rule in code, also update the matching handbook chapter in a separate PR. The skill file gets the rule; the handbook gets the rule plus the rationale and an extended example.
When a chapter is updated here, no change is needed in the skill files unless the underlying rule changed too.
A reviewer noticing drift between the two should open a PR to whichever side is out of date.