---
name: explain-architecture
description: |
  Use this skill when writing, editing, or reviewing the
  architecture section of a repository's README.md file.
  Explain key architectural decisions to a newcomer — one
  decision per paragraph, each tied to a concrete design
  constraint, each highlighting how the repo differs from
  traditional or competing solutions. Stay concise, technical,
  emotion-free, and rational. Assume the reader is fluent in
  coding but new to this repo and to the problem domain.
---

Write one paragraph per architectural decision; never bundle
  two decisions into one paragraph, and never split one
  decision across several.

Tie every decision to the design constraint that forced it:
  a performance budget, a memory limit, a security requirement,
  a regulatory rule, a backward-compatibility promise, a
  hardware target, or another concrete pressure.

Focus on what makes this repo different from traditional or
  competing solutions; skip decisions any reasonable project
  would make the same way, since they carry no information
  for the reader.

State plainly what each decision means for a programmer who
  joins the repo tomorrow: the module they must touch, the
  pattern they must follow, or the trap they must avoid.

Stay concise, technical, emotion-free, and rational; cut
  marketing language, hype, self-congratulation, and any
  sentence that would fit a press release.

Link to similar or competing solutions when contrast helps
  the reader place this repo on the map, for example
  `[Redis](https://redis.io)` versus
  `[Memcached](https://memcached.org)`.

Link every technology, standard, protocol, or file format to
  its canonical reference page with a Markdown link, so the
  reader can chase down terms they do not know without
  leaving the README.

Assume the reader is fluent in coding but new to this repo
  and its problem domain; explain the domain enough to
  justify each decision, but do not teach general programming.

Do not list features, do not narrate project history, do not
  explain how to install, build, or run the project; that
  material belongs elsewhere in the README.

Order decisions from the most far-reaching (storage model,
  concurrency model, language choice, deployment target) down
  to the more local (logging format, error-handling style),
  so the reader builds context before encountering detail.

When editing an existing architecture section, preserve
  decisions that already meet these rules and rewrite only
  the paragraphs that violate them.