A guide to writing a rewrite rule, with every figure in it under test

[Rafael-SOWNet]

#746 tier 2 lists five major deliverables. Four exist — the rule registry, the rewrite graph with
pluggable extraction, the canonicalisation framework (#1105), the confluence and termination checker.
This is the fifth: the rule-authoring guide.

Docs/Contributing/WritingARule.md is the how. Whether a rule is allowed is a harder question
and a different document — SimplificationContract.md comes first, and the guide says so in its
opening line, because a rule written beautifully that holds only on the positive reals while claiming
to hold everywhere is a wrong answer with good spelling.

What it covers

• where a rule goes, and why not in a switch;
• the seven things a rule carries, as one annotated example;
• why the name is a sentence rather than an identifier — it is read aloud by
  DerivationPath.Explain(), so a-quotient-of-a-thing-by-itself-is-one-unless-it-is-zero is right
  and DivideByItself is not, with the reason rather than the rule;
• that the name, the identity and the rendered pattern are three different things, all worth
  having;
• the pattern language, and the two families it deliberately cannot build — binders, because
  DirectChildren renames the bound variable, and variable-arity nodes, because a pattern fixes an
  arity;
• what choosing a code replacement costs: a direction and an exact growth;
• that soundness is per rule, and the set grain says nothing because a set's tier is the minimum over
  its rules;
• when the order of two rules is yours to choose and when subsumption has already decided it;
• the ten tests that will check a new rule;
• and the whole of it once, on one rule.

Every count in it is under test

RuleAuthoringGuideTest, and the guide says so at the top.

A document that states a number goes stale silently, and a guide is the worst case: it is read by
somebody who does not yet know the code, and is therefore in no position to notice that "33 of the
322 rules have a pattern on both sides" stopped being true two releases ago.

Nine facts are held — the set and rule counts, the 293 distinct names and their four-to-sixteen-word
range, the 59 identities, the 44 buildable node types, the 33 two-sided rules and 32 directions, the
181 Sound against 141 conditional, the 268 at Unknown growth, and the 28 pairs ordered by
subsumption. The failure message names the claim and says which way to fix it:

WritingARule.md says how many rules are Sound is 181; it is 179.
Update the document, not this test.

Two more are not counts:

• the ten tests the guide sends a contributor to are checked to exist, by reflection over the
  test assembly. A guide that names a test which has since been renamed is worse than one that names
  none — the reader concludes the check does not exist, rather than that the document is old;
• the worked example at the end is looked up in the library and applied, so it cannot quietly
  become a rule that is not there.

One thing writing it found

The guide asserted that the single one-way two-sided rule is the Pythagorean identity — which is what
the surrounding documentation calls it — and the test matched on the name containing pythagorean.
The rule is called squared-sine-and-cosine-of-one-argument-sum-to-one. The prose is right; the
assertion was matching the prose rather than the rule, which is exactly the failure the rest of this
file exists to prevent. It now matches the rule.

Also indexes the guide in the contributing README, whose numbering had two entries at 10.

State

Full suite: 8988 passed, 14 skipped, 0 failed. No public API change; documentation and one test.

Part of #746 tier 2.