From 747d19e324ee0c533a67b7aea3dd086acf3ecabd Mon Sep 17 00:00:00 2001
From: Jon Gjengset <jon.gjengset@helsing.ai>
Date: Fri, 14 Aug 2026 16:41:04 +0200
Subject: [PATCH] test: replace fixture prose with field placeholders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every test fixture used to carry its own invented Y-Statement — "Store
timestamps as UTC", "Retry with exponential backoff", and so on. The
parser doesn't care what the words say, so writing that prose was effort
that bought nothing, and it actively made snapshot review harder: when
`in_context` and `facing_concern` each hold a sentence fragment, you
have to go back to the fixture to check the parser put each fragment in
the slot it belongs in.

Three vocabularies were in play as a result: the README long form
(`<use case/user story u>`) in most of the insta tests, a one-letter
form (`<u>`, `<c>`, ...) in two unit tests, and hand-written prose in
the on-disk fixtures and the `YAdr::parse` doctest. Fixtures now
standardise on a single three-letter form, one per capture slot:

    In the context of <ctx>, we faced <con>.

    We decided for <opt>, and neglected <alt>.

    We did this to achieve <qua>, accepting <dwn>.

    We think this is the right trade-off because <why>.

plus `<title>`, `<tail>`, and `<chg1>`/`<chg2>`/... for change entries.
The change descriptions are numbered so that a snapshot would show it if
a description were ever paired with the wrong date.

Note that no placeholder may contain a comma or a period: those are what
terminate the non-greedy capture groups in `YADR_PARAGRAPH_REGEXES`. The
one fixture that needs bulk, `indented_malformed_paragraph`, therefore
puts its filler *inside* the angle brackets rather than around them, so
that each parameter position stays exactly one placeholder.

Three things deliberately keep their prose:

- Both `realistic` tests, which parse a Y-Statement taken verbatim from
  `dson`. They exist to catch the format only working for prose we wrote
  ourselves, and they cover what placeholders can't: commas inside
  `chosen_option`, a period mid-`because`, parenthesised asides.
- The format documentation (README, the module docs, the `Args` doc
  comment, the `YAdr` struct docs), which keeps the descriptive long
  form. Documentation explains what belongs in a slot; a fixture only
  needs to label it.
- The malformed paragraph in `tests/fixtures/broken/malformed.rs`, since
  that sentence is the thing under test.

Some consequences worth knowing about:

- Titles are all `<title>` now, so `tests/cli.rs` identifies statements
  by date rather than by title throughout.
- The `YAdr::parse` doctest demonstrated that the parser leaves comment
  wrapping in a field; three-letter placeholders never wrap, so it keeps
  one deliberately long placeholder that spans the line break.
- Most fixtures still wrap the third paragraph before `<dwn>` even
  though it would now fit on one line. That keeps coverage of a capture
  group whose match spans a line break. The first paragraph of
  `retry.py` is wrapped for the same kind of reason — the `yadr show`
  reflow assertion needs something to catch — and says so, since
  unwrapping it would make that assertion pass vacuously.

The 26 affected snapshots were regenerated and reviewed rather than
blind-accepted: the diagnostic ones carry width-sensitive caret spans,
and each was checked to still underline the paragraph it is meant to.
`cargo test --all-targets`, `cargo test --doc`, clippy, and the dogfood
`yadr check` over this repo all pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/lib.rs                                    | 290 +++++------
 tests/cli.rs                                  |  34 +-
 tests/fixtures/broken/malformed.rs            |   5 +-
 tests/fixtures/clean/retry.py                 |  18 +-
 tests/fixtures/clean/storage.rs               |  33 +-
 tests/fixtures/clean/toolchain.nix            |  15 +-
 tests/instas.rs                               | 479 +++++++++---------
 .../instas__bad_change_ordering.snap          |  15 +-
 tests/snapshots/instas__block_nix.snap        |  16 +-
 .../instas__change_invalid_date.snap          |   8 +-
 .../instas__change_missing_colon.snap         |  13 +-
 .../instas__changes_before_tail.snap          |  15 +-
 tests/snapshots/instas__docstr_double.snap    |  16 +-
 tests/snapshots/instas__docstr_raw.snap       |  16 +-
 .../snapshots/instas__docstr_raw_unicode.snap |  16 +-
 tests/snapshots/instas__docstr_single.snap    |  16 +-
 tests/snapshots/instas__docstr_unicode.snap   |  16 +-
 tests/snapshots/instas__double_block_nix.snap |  16 +-
 .../instas__early_termination_dashes.snap     |  18 +-
 ...tas__early_termination_triple_newline.snap |  18 +-
 ...nstas__early_termination_with_changes.snap |  24 +-
 tests/snapshots/instas__hashes.snap           |  16 +-
 tests/snapshots/instas__hashes_nix.snap       |  17 +-
 .../instas__indented_malformed_paragraph.snap |  23 +-
 tests/snapshots/instas__malformed_para.snap   |  15 +-
 .../snapshots/instas__missing_paragraph.snap  |   7 +-
 .../instas__no_empty_line_before_changes.snap |  13 +-
 tests/snapshots/instas__stars.snap            |  18 +-
 tests/snapshots/instas__stripes.snap          |  16 +-
 tests/snapshots/instas__stripes_to_space.snap |  34 +-
 tests/snapshots/instas__two_in_one_py.snap    |  32 +-
 tests/snapshots/instas__two_in_one_rs.snap    |  32 +-
 tests/snapshots/instas__with_changes.snap     |  24 +-
 33 files changed, 643 insertions(+), 701 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 2c3f1ab..77592b5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1023,23 +1023,24 @@ impl<'a> YAdr<'a> {
     /// use yadr::YAdr;
     ///
     /// let yadr = YAdr::parse(
-    ///     "YADR: 2024-06-18 Store timestamps as UTC
+    ///     "YADR: 2024-06-18 <title>
     ///
-    ///      In the context of comparing timestamps across machines, we faced ambiguity about
-    ///      which offset each one was written in.
+    ///      In the context of <ctx>, we faced <con>.
     ///
-    ///      We decided for storing everything in UTC, and neglected recording a local offset
-    ///      alongside each timestamp.
+    ///      We decided for <opt>, and neglected <alt written out at enough
+    ///      length that it wraps onto a second line>.
     ///
-    ///      We did this to achieve unambiguous ordering, accepting an extra lookup when
-    ///      rendering a timestamp in local time.
+    ///      We did this to achieve <qua>, accepting <dwn>.
     ///
-    ///      We think this is the right trade-off because ordering matters everywhere and
-    ///      local-time rendering only in the user interface.",
+    ///      We think this is the right trade-off because <why>.",
     /// )?;
     ///
-    /// assert_eq!(yadr.title, "2024-06-18 Store timestamps as UTC");
-    /// assert_eq!(yadr.neglected_options, "recording a local offset\n     alongside each timestamp");
+    /// assert_eq!(yadr.title, "2024-06-18 <title>");
+    /// assert_eq!(yadr.in_context, "<ctx>");
+    /// assert_eq!(
+    ///     yadr.neglected_options,
+    ///     "<alt written out at enough\n     length that it wraps onto a second line>",
+    /// );
     /// # Ok::<_, miette::Report>(())
     /// ```
     ///
@@ -1210,19 +1211,19 @@ mod tests {
     #[test]
     fn parse_borrows_from_its_input() {
         let statement = String::from(
-            "YADR: 2024-06-18 a-title
+            "YADR: 2024-06-18 <title>
 
-            In the context of <u>, we faced <c>.
+            In the context of <ctx>, we faced <con>.
 
-            We decided for <o>, and neglected <others>.
+            We decided for <opt>, and neglected <alt>.
 
-            We did this to achieve <q>, accepting <d>.
+            We did this to achieve <qua>, accepting <dwn>.
 
-            We think this is the right trade-off because <r>.",
+            We think this is the right trade-off because <why>.",
         );
         let yadr = YAdr::parse(&statement).expect("statement is well-formed");
-        assert!(matches!(yadr.in_context, Cow::Borrowed("<u>")));
-        assert_eq!(yadr.title, "2024-06-18 a-title");
+        assert!(matches!(yadr.in_context, Cow::Borrowed("<ctx>")));
+        assert_eq!(yadr.title, "2024-06-18 <title>");
         assert_eq!(yadr.date, Date::constant(2024, 6, 18));
 
         // ...whereas `FromStr` has to own, since it cannot name the input's lifetime.
@@ -1232,15 +1233,15 @@ mod tests {
 
     #[test]
     fn parse_rejects_a_second_statement() {
-        let one = "YADR: 2024-06-18 a-title
+        let one = "YADR: 2024-06-18 <title>
 
-            In the context of <u>, we faced <c>.
+            In the context of <ctx>, we faced <con>.
 
-            We decided for <o>, and neglected <others>.
+            We decided for <opt>, and neglected <alt>.
 
-            We did this to achieve <q>, accepting <d>.
+            We did this to achieve <qua>, accepting <dwn>.
 
-            We think this is the right trade-off because <r>.";
+            We think this is the right trade-off because <why>.";
         let two = format!("{one}\n\n{}", one.replace("2024-06-18", "2024-06-19"));
         let e = YAdr::parse(&two).expect_err("two statements is not one statement");
         assert!(
@@ -1449,31 +1450,28 @@ mod tests {
 
     #[test]
     fn full_yadr() {
-        let source = "YADR: 2023-11-28 some-title
+        let source = "YADR: 2023-11-28 <title>
 
-        In the context of <use case/user story u>, we faced <concern c>.
+        In the context of <ctx>, we faced <con>.
 
-        We decided for <option o>, and neglected <other options>.
+        We decided for <opt>, and neglected <alt>.
 
-        We did this to achieve <system qualities/desired consequences>, accepting
-        <downside d/undesired consequences>.
+        We did this to achieve <qua>, accepting
+        <dwn>.
 
-        We think this is the right trade-off because <additional rationale>.
+        We think this is the right trade-off because <why>.
         ";
         let mut yadr = YAdr::parse(source).unwrap();
         yadr.tidy();
         assert_eq!(yadr.date, Date::constant(2023, 11, 28));
-        assert_eq!(yadr.title, "2023-11-28 some-title");
-        assert_eq!(yadr.in_context, "<use case/user story u>");
-        assert_eq!(yadr.facing_concern, "<concern c>");
-        assert_eq!(yadr.chosen_option, "<option o>");
-        assert_eq!(yadr.neglected_options, "<other options>");
-        assert_eq!(yadr.to_achieve, "<system qualities/desired consequences>");
-        assert_eq!(
-            yadr.accepted_downsides,
-            "<downside d/undesired consequences>"
-        );
-        assert_eq!(yadr.because, "<additional rationale>");
+        assert_eq!(yadr.title, "2023-11-28 <title>");
+        assert_eq!(yadr.in_context, "<ctx>");
+        assert_eq!(yadr.facing_concern, "<con>");
+        assert_eq!(yadr.chosen_option, "<opt>");
+        assert_eq!(yadr.neglected_options, "<alt>");
+        assert_eq!(yadr.to_achieve, "<qua>");
+        assert_eq!(yadr.accepted_downsides, "<dwn>");
+        assert_eq!(yadr.because, "<why>");
         assert_eq!(yadr.tail, None);
 
         // `Display` is meant to emit the canonical format, which means what it prints has to be
@@ -1490,15 +1488,15 @@ mod tests {
         find_all(
             r#"
                 /*
-                 * YADR: 2023-11-28 foo-bar also
-                 * In the context of <use case/user story u>, we faced <concern c>.
+                 * YADR: 2023-11-28 <title>
+                 * In the context of <ctx>, we faced <con>.
                  *
-                 * We decided for <option o>, and neglected <other options>.
+                 * We decided for <opt>, and neglected <alt>.
                  *
-                 * We did this to achieve <system qualities/desired consequences>, accepting
-                 * <downside d/undesired consequences>.
+                 * We did this to achieve <qua>, accepting
+                 * <dwn>.
                  *
-                 * We think this is the right trade-off because <additional rationale>.
+                 * We think this is the right trade-off because <why>.
                  */
             "#,
             Language::Rust,
@@ -1511,20 +1509,14 @@ mod tests {
         assert_eq!(yadrs.len(), 1);
         assert_eq!(yadrs[0].0, 3);
         assert_eq!(yadrs[0].1.date, Date::constant(2023, 11, 28));
-        assert_eq!(yadrs[0].1.title, "2023-11-28 foo-bar also");
-        assert_eq!(yadrs[0].1.in_context, "<use case/user story u>");
-        assert_eq!(yadrs[0].1.facing_concern, "<concern c>");
-        assert_eq!(yadrs[0].1.chosen_option, "<option o>");
-        assert_eq!(yadrs[0].1.neglected_options, "<other options>");
-        assert_eq!(
-            yadrs[0].1.to_achieve,
-            "<system qualities/desired consequences>"
-        );
-        assert_eq!(
-            yadrs[0].1.accepted_downsides,
-            "<downside d/undesired consequences>"
-        );
-        assert_eq!(yadrs[0].1.because, "<additional rationale>");
+        assert_eq!(yadrs[0].1.title, "2023-11-28 <title>");
+        assert_eq!(yadrs[0].1.in_context, "<ctx>");
+        assert_eq!(yadrs[0].1.facing_concern, "<con>");
+        assert_eq!(yadrs[0].1.chosen_option, "<opt>");
+        assert_eq!(yadrs[0].1.neglected_options, "<alt>");
+        assert_eq!(yadrs[0].1.to_achieve, "<qua>");
+        assert_eq!(yadrs[0].1.accepted_downsides, "<dwn>");
+        assert_eq!(yadrs[0].1.because, "<why>");
         assert_eq!(yadrs[0].1.tail, None);
     }
 
@@ -1534,17 +1526,17 @@ mod tests {
         find_all(
             r#"
                 /*
-                 * YADR: 2023-11-28 foo-bar also
-                 * In the context of <use case/user story u>, we faced <concern c>.
+                 * YADR: 2023-11-28 <title>
+                 * In the context of <ctx>, we faced <con>.
                  *
-                 * We decided for <option o>, and neglected <other options>.
+                 * We decided for <opt>, and neglected <alt>.
                  *
-                 * We did this to achieve <system qualities/desired consequences>, accepting
-                 * <downside d/undesired consequences>.
+                 * We did this to achieve <qua>, accepting
+                 * <dwn>.
                  *
-                 * We think this is the right trade-off because <additional rationale>.
+                 * We think this is the right trade-off because <why>.
                  *
-                 * Also, foobar to the baz.
+                 * <tail>
                  */
             "#,
             Language::Rust,
@@ -1557,24 +1549,15 @@ mod tests {
         assert_eq!(yadrs.len(), 1);
         assert_eq!(yadrs[0].0, 3);
         assert_eq!(yadrs[0].1.date, Date::constant(2023, 11, 28));
-        assert_eq!(yadrs[0].1.title, "2023-11-28 foo-bar also");
-        assert_eq!(yadrs[0].1.in_context, "<use case/user story u>");
-        assert_eq!(yadrs[0].1.facing_concern, "<concern c>");
-        assert_eq!(yadrs[0].1.chosen_option, "<option o>");
-        assert_eq!(yadrs[0].1.neglected_options, "<other options>");
-        assert_eq!(
-            yadrs[0].1.to_achieve,
-            "<system qualities/desired consequences>"
-        );
-        assert_eq!(
-            yadrs[0].1.accepted_downsides,
-            "<downside d/undesired consequences>"
-        );
-        assert_eq!(yadrs[0].1.because, "<additional rationale>");
-        assert_eq!(
-            yadrs[0].1.tail.as_ref().unwrap(),
-            "Also, foobar to the baz."
-        );
+        assert_eq!(yadrs[0].1.title, "2023-11-28 <title>");
+        assert_eq!(yadrs[0].1.in_context, "<ctx>");
+        assert_eq!(yadrs[0].1.facing_concern, "<con>");
+        assert_eq!(yadrs[0].1.chosen_option, "<opt>");
+        assert_eq!(yadrs[0].1.neglected_options, "<alt>");
+        assert_eq!(yadrs[0].1.to_achieve, "<qua>");
+        assert_eq!(yadrs[0].1.accepted_downsides, "<dwn>");
+        assert_eq!(yadrs[0].1.because, "<why>");
+        assert_eq!(yadrs[0].1.tail.as_ref().unwrap(), "<tail>");
     }
 
     #[test]
@@ -1583,18 +1566,18 @@ mod tests {
         find_all(
             r#"
                 /*
-                 * YADR: 2023-11-28 foo-bar also
-                 * In the context of <use case/user story u>, we faced <concern c>.
+                 * YADR: 2023-11-28 <title>
+                 * In the context of <ctx>, we faced <con>.
                  *
-                 * We decided for <option o>, and neglected <other options>.
+                 * We decided for <opt>, and neglected <alt>.
                  *
-                 * We did this to achieve <system qualities/desired consequences>, accepting
-                 * <downside d/undesired consequences>.
+                 * We did this to achieve <qua>, accepting
+                 * <dwn>.
                  *
-                 * We think this is the right trade-off because <additional rationale>.
+                 * We think this is the right trade-off because <why>.
                  *
-                 * 2023-11-29: jon did a thing
-                 * 2023-11-30: james did another thing
+                 * 2023-11-29: <chg1>
+                 * 2023-11-30: <chg2>
                  */
             "#,
             Language::Rust,
@@ -1608,9 +1591,9 @@ mod tests {
         assert_eq!(yadrs[0].1.tail, None);
         assert_eq!(yadrs[0].1.changes.len(), 2);
         assert_eq!(yadrs[0].1.changes[0].0, Date::constant(2023, 11, 29));
-        assert_eq!(yadrs[0].1.changes[0].1, "jon did a thing");
+        assert_eq!(yadrs[0].1.changes[0].1, "<chg1>");
         assert_eq!(yadrs[0].1.changes[1].0, Date::constant(2023, 11, 30));
-        assert_eq!(yadrs[0].1.changes[1].1, "james did another thing");
+        assert_eq!(yadrs[0].1.changes[1].1, "<chg2>");
     }
 
     #[test]
@@ -1619,20 +1602,20 @@ mod tests {
         find_all(
             r#"
                 /*
-                 * YADR: 2023-11-28 foo-bar also
-                 * In the context of <use case/user story u>, we faced <concern c>.
+                 * YADR: 2023-11-28 <title>
+                 * In the context of <ctx>, we faced <con>.
                  *
-                 * We decided for <option o>, and neglected <other options>.
+                 * We decided for <opt>, and neglected <alt>.
                  *
-                 * We did this to achieve <system qualities/desired consequences>, accepting
-                 * <downside d/undesired consequences>.
+                 * We did this to achieve <qua>, accepting
+                 * <dwn>.
                  *
-                 * We think this is the right trade-off because <additional rationale>.
+                 * We think this is the right trade-off because <why>.
                  *
-                 * And also there's a tail, followed by changes:
+                 * <tail>
                  *
-                 * 2023-11-29: jon did a thing
-                 * 2023-11-30: james did another thing
+                 * 2023-11-29: <chg1>
+                 * 2023-11-30: <chg2>
                  */
             "#,
             Language::Rust,
@@ -1643,15 +1626,12 @@ mod tests {
         )
         .unwrap();
         assert_eq!(yadrs.len(), 1);
-        assert_eq!(
-            yadrs[0].1.tail.as_ref().unwrap(),
-            "And also there's a tail, followed by changes:"
-        );
+        assert_eq!(yadrs[0].1.tail.as_ref().unwrap(), "<tail>");
         assert_eq!(yadrs[0].1.changes.len(), 2);
         assert_eq!(yadrs[0].1.changes[0].0, Date::constant(2023, 11, 29));
-        assert_eq!(yadrs[0].1.changes[0].1, "jon did a thing");
+        assert_eq!(yadrs[0].1.changes[0].1, "<chg1>");
         assert_eq!(yadrs[0].1.changes[1].0, Date::constant(2023, 11, 30));
-        assert_eq!(yadrs[0].1.changes[1].1, "james did another thing");
+        assert_eq!(yadrs[0].1.changes[1].1, "<chg2>");
     }
 
     #[test]
@@ -1660,26 +1640,26 @@ mod tests {
         find_all(
             r#"
                 /*
-                 * YADR: 2023-11-28 foo-bar also
-                 * In the context of <use case/user story u>, we faced <concern c>.
+                 * YADR: 2023-11-28 <title>
+                 * In the context of <ctx>, we faced <con>.
                  *
-                 * We decided for <option o>, and neglected <other options>.
+                 * We decided for <opt>, and neglected <alt>.
                  *
-                 * We did this to achieve <system qualities/desired consequences>, accepting
-                 * <downside d/undesired consequences>.
+                 * We did this to achieve <qua>, accepting
+                 * <dwn>.
                  *
-                 * We think this is the right trade-off because <additional rationale>.
+                 * We think this is the right trade-off because <why>.
                  */
 
-                // YADR: 2023-11-29 bar-baz
-                // In the context of <use case/user story u>, we faced <concern c>.
+                // YADR: 2023-11-29 <title>
+                // In the context of <ctx>, we faced <con>.
                 //
-                // We decided for <option o>, and neglected <other options>.
+                // We decided for <opt>, and neglected <alt>.
                 //
-                // We did this to achieve <system qualities/desired consequences>, accepting
-                // <downside d/undesired consequences>.
+                // We did this to achieve <qua>, accepting
+                // <dwn>.
                 //
-                // We think this is the right trade-off because <additional rationale>.
+                // We think this is the right trade-off because <why>.
             "#,
             Language::Rust,
             |line, yadr| {
@@ -1692,20 +1672,17 @@ mod tests {
         assert_eq!(yadrs[0].0, 3);
         assert_eq!(yadrs[1].0, 14);
         assert_eq!(yadrs[0].1.date, Date::constant(2023, 11, 28));
-        assert_eq!(yadrs[0].1.title, "2023-11-28 foo-bar also");
+        assert_eq!(yadrs[0].1.title, "2023-11-28 <title>");
         assert_eq!(yadrs[1].1.date, Date::constant(2023, 11, 29));
-        assert_eq!(yadrs[1].1.title, "2023-11-29 bar-baz");
+        assert_eq!(yadrs[1].1.title, "2023-11-29 <title>");
         for (_, yadr) in &yadrs {
-            assert_eq!(yadr.in_context, "<use case/user story u>");
-            assert_eq!(yadr.facing_concern, "<concern c>");
-            assert_eq!(yadr.chosen_option, "<option o>");
-            assert_eq!(yadr.neglected_options, "<other options>");
-            assert_eq!(yadr.to_achieve, "<system qualities/desired consequences>");
-            assert_eq!(
-                yadr.accepted_downsides,
-                "<downside d/undesired consequences>"
-            );
-            assert_eq!(yadr.because, "<additional rationale>");
+            assert_eq!(yadr.in_context, "<ctx>");
+            assert_eq!(yadr.facing_concern, "<con>");
+            assert_eq!(yadr.chosen_option, "<opt>");
+            assert_eq!(yadr.neglected_options, "<alt>");
+            assert_eq!(yadr.to_achieve, "<qua>");
+            assert_eq!(yadr.accepted_downsides, "<dwn>");
+            assert_eq!(yadr.because, "<why>");
             assert_eq!(yadr.tail, None);
         }
     }
@@ -1716,25 +1693,25 @@ mod tests {
         find_all(
             r#"
                 /*
-                 * YADR: 2023-11-28 foo-bar also
-                 * In the context of <use case/user story u>, we faced <concern c>.
+                 * YADR: 2023-11-28 <title>
+                 * In the context of <ctx>, we faced <con>.
                  *
-                 * We decided for <option o>, and neglected <other options>.
+                 * We decided for <opt>, and neglected <alt>.
                  *
-                 * We did this to achieve <system qualities/desired consequences>, accepting
-                 * <downside d/undesired consequences>.
+                 * We did this to achieve <qua>, accepting
+                 * <dwn>.
                  *
-                 * We think this is the right trade-off because <additional rationale>.
+                 * We think this is the right trade-off because <why>.
 
-                 YADR: 2023-11-29 bar-baz
-                 In the context of <use case/user story u>, we faced <concern c>.
+                 YADR: 2023-11-29 <title>
+                 In the context of <ctx>, we faced <con>.
 
-                 We decided for <option o>, and neglected <other options>.
+                 We decided for <opt>, and neglected <alt>.
 
-                 We did this to achieve <system qualities/desired consequences>, accepting
-                 <downside d/undesired consequences>.
+                 We did this to achieve <qua>, accepting
+                 <dwn>.
 
-                 We think this is the right trade-off because <additional rationale>.
+                 We think this is the right trade-off because <why>.
                  */
             "#,
             Language::Rust,
@@ -1748,20 +1725,17 @@ mod tests {
         assert_eq!(yadrs[0].0, 3);
         assert_eq!(yadrs[1].0, 13);
         assert_eq!(yadrs[0].1.date, Date::constant(2023, 11, 28));
-        assert_eq!(yadrs[0].1.title, "2023-11-28 foo-bar also");
+        assert_eq!(yadrs[0].1.title, "2023-11-28 <title>");
         assert_eq!(yadrs[1].1.date, Date::constant(2023, 11, 29));
-        assert_eq!(yadrs[1].1.title, "2023-11-29 bar-baz");
+        assert_eq!(yadrs[1].1.title, "2023-11-29 <title>");
         for (_, yadr) in &yadrs {
-            assert_eq!(yadr.in_context, "<use case/user story u>");
-            assert_eq!(yadr.facing_concern, "<concern c>");
-            assert_eq!(yadr.chosen_option, "<option o>");
-            assert_eq!(yadr.neglected_options, "<other options>");
-            assert_eq!(yadr.to_achieve, "<system qualities/desired consequences>");
-            assert_eq!(
-                yadr.accepted_downsides,
-                "<downside d/undesired consequences>"
-            );
-            assert_eq!(yadr.because, "<additional rationale>");
+            assert_eq!(yadr.in_context, "<ctx>");
+            assert_eq!(yadr.facing_concern, "<con>");
+            assert_eq!(yadr.chosen_option, "<opt>");
+            assert_eq!(yadr.neglected_options, "<alt>");
+            assert_eq!(yadr.to_achieve, "<qua>");
+            assert_eq!(yadr.accepted_downsides, "<dwn>");
+            assert_eq!(yadr.because, "<why>");
             assert_eq!(yadr.tail, None);
         }
     }
diff --git a/tests/cli.rs b/tests/cli.rs
index d4c1854..0a3fa8c 100644
--- a/tests/cli.rs
+++ b/tests/cli.rs
@@ -5,16 +5,19 @@
 //! exist in `main.rs`: argument parsing, the directory walk, the exclude rules, the shape of each
 //! subcommand's output, and the exit status.
 //!
-//! The fixtures are deliberately kept small and boring. They exist to be parsed, not read.
+//! The fixtures are deliberately kept small and boring. They exist to be parsed, not read, so a
+//! statement is identified here by its date rather than by its title.
 
 use assert_cmd::Command;
 use predicates::prelude::*;
 
 /// A tree of three files, one per supported language, holding four valid Y-Statements between
-/// them. `storage.rs` holds two so that per-file grouping in `list` output gets exercised.
+/// them, dated 2024-01-15, 2024-01-22, 2024-03-02, and 2024-04-09. `storage.rs` holds the first
+/// two so that per-file grouping in `list` output gets exercised.
 const CLEAN: &str = "tests/fixtures/clean";
 
-/// A tree holding a single Y-Statement whose second paragraph doesn't follow the format.
+/// A tree holding a single Y-Statement, dated 2024-05-20, whose second paragraph doesn't follow
+/// the format.
 const BROKEN: &str = "tests/fixtures/broken";
 
 fn yadr() -> Command {
@@ -37,18 +40,10 @@ fn list_finds_statements_in_every_supported_language() {
         .args(["ls", CLEAN])
         .assert()
         .success()
-        .stdout(predicate::str::contains(
-            "2024-01-15 Store timestamps as UTC",
-        ))
-        .stdout(predicate::str::contains(
-            "2024-01-22 Fail closed on an unreadable file",
-        ))
-        .stdout(predicate::str::contains(
-            "2024-03-02 Retry with exponential backoff",
-        ))
-        .stdout(predicate::str::contains(
-            "2024-04-09 Pin the toolchain in the lock file",
-        ));
+        .stdout(predicate::str::contains("2024-01-15 <title>"))
+        .stdout(predicate::str::contains("2024-01-22 <title>"))
+        .stdout(predicate::str::contains("2024-03-02 <title>"))
+        .stdout(predicate::str::contains("2024-04-09 <title>"));
 }
 
 /// The two statements in `storage.rs` should appear under a single `==>` heading for that file,
@@ -75,7 +70,7 @@ fn list_reports_the_most_recent_change() {
         .assert()
         .success()
         .stdout(predicate::str::contains(
-            "2024-01-15 Store timestamps as UTC (last changed: 2024-02-01)",
+            "2024-01-15 <title> (last changed: 2024-02-01)",
         ));
 }
 
@@ -108,15 +103,12 @@ fn show_prints_one_statement_in_full() {
 
     // the source location, so the reader can go and find it
     assert!(
-        stdout.contains("tests/fixtures/clean/retry.py:3"),
+        stdout.contains("tests/fixtures/clean/retry.py:6"),
         "no source location in:\n{stdout}"
     );
     // reflowed onto one line per paragraph, rather than as it was wrapped in the comment
     assert!(
-        stdout.contains(
-            "In the context of talking to an upstream service that occasionally rejects requests, \
-             we faced the question of how quickly to retry."
-        ),
+        stdout.contains("In the context of <ctx>, we faced <con>."),
         "paragraph was not reflowed in:\n{stdout}"
     );
     // and only the statement that was asked for
diff --git a/tests/fixtures/broken/malformed.rs b/tests/fixtures/broken/malformed.rs
index 7cd56cf..4be9ce2 100644
--- a/tests/fixtures/broken/malformed.rs
+++ b/tests/fixtures/broken/malformed.rs
@@ -5,10 +5,9 @@
 // decided for", so the diagnostic should name paragraph 2.
 
 /*
- * YADR: 2024-05-20 A statement that does not follow the format
+ * YADR: 2024-05-20 <title>
  *
- * In the context of testing what yadr reports for a malformed statement, we faced the need
- * for an input that is recognisably a Y-Statement but does not parse as one.
+ * In the context of <ctx>, we faced <con>.
  *
  * We chose one of the options available to us, and forgot to write the rest of the format.
  */
diff --git a/tests/fixtures/clean/retry.py b/tests/fixtures/clean/retry.py
index 8466dba..969ac04 100644
--- a/tests/fixtures/clean/retry.py
+++ b/tests/fixtures/clean/retry.py
@@ -1,17 +1,17 @@
 # A fixture for yadr's end-to-end tests. Never executed; only ever read as text.
+#
+# The first paragraph is wrapped across two comment lines even though it would fit on one, so that
+# `show_prints_one_statement_in_full` in `tests/cli.rs` has a reflow to catch.
 
-# YADR: 2024-03-02 Retry with exponential backoff
+# YADR: 2024-03-02 <title>
 #
-# In the context of talking to an upstream service that occasionally rejects requests, we
-# faced the question of how quickly to retry.
+# In the context of <ctx>, we
+# faced <con>.
 #
-# We decided for doubling the delay after each attempt up to a ceiling, and neglected both
-# retrying immediately and giving up after the first failure.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve recovery from brief outages without adding load to a service that is
-# already struggling, accepting that a request can take much longer than usual to resolve.
+# We did this to achieve <qua>, accepting <dwn>.
 #
-# We think this is the right trade-off because the outages we see in practice are short, and
-# a caller that cannot wait can impose its own deadline.
+# We think this is the right trade-off because <why>.
 def fetch():
     pass
diff --git a/tests/fixtures/clean/storage.rs b/tests/fixtures/clean/storage.rs
index 54b5be0..8059b73 100644
--- a/tests/fixtures/clean/storage.rs
+++ b/tests/fixtures/clean/storage.rs
@@ -1,37 +1,30 @@
 // A fixture for yadr's end-to-end tests. This file is never compiled; the test suite only ever
 // runs the `yadr` binary over it and asserts on what comes out. Two Y-Statements live here so that
-// the tests cover a file containing more than one.
+// the tests cover a file containing more than one, and they use different comment syntaxes so that
+// both of Rust's are covered.
 
 /*
- * YADR: 2024-01-15 Store timestamps as UTC
+ * YADR: 2024-01-15 <title>
  *
- * In the context of comparing event timestamps recorded on different machines, we faced
- * ambiguity about which offset a bare local timestamp had been written in.
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for storing every timestamp in UTC, and neglected recording the local offset
- * alongside each timestamp.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve unambiguous ordering of events no matter where they were recorded,
- * accepting that rendering a timestamp in the recorder's own time zone needs a separate
- * lookup.
+ * We did this to achieve <qua>, accepting <dwn>.
  *
- * We think this is the right trade-off because ordering matters everywhere in the system,
- * whereas local-time rendering matters only in the user interface.
+ * We think this is the right trade-off because <why>.
  *
- * 2024-02-01: noted that the user interface is where the offset lookup happens.
+ * 2024-02-01: <chg>
  */
 fn store() {}
 
-// YADR: 2024-01-22 Fail closed on an unreadable file
+// YADR: 2024-01-22 <title>
 //
-// In the context of walking a source tree we do not control, we faced the question of what
-// to do when a file cannot be read.
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for aborting the whole run, and neglected skipping the file with a warning.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve a guarantee that a successful run really did inspect everything,
-// accepting that one unreadable file stops the run.
+// We did this to achieve <qua>, accepting <dwn>.
 //
-// We think this is the right trade-off because a partial pass reported as a success is worse
-// than an obvious failure.
+// We think this is the right trade-off because <why>.
 fn read() {}
diff --git a/tests/fixtures/clean/toolchain.nix b/tests/fixtures/clean/toolchain.nix
index c7c21ac..c84503c 100644
--- a/tests/fixtures/clean/toolchain.nix
+++ b/tests/fixtures/clean/toolchain.nix
@@ -1,17 +1,12 @@
 # A fixture for yadr's end-to-end tests. Never evaluated; only ever read as text.
 
-# YADR: 2024-04-09 Pin the toolchain in the lock file
+# YADR: 2024-04-09 <title>
 #
-# In the context of builds that have to reproduce on a colleague's machine and in CI, we
-# faced drift between whichever toolchain each of them happened to have installed.
+# In the context of <ctx>, we faced <con>.
 #
-# We decided for pinning an exact toolchain version in the lock file, and neglected tracking
-# the latest stable release.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve builds that produce the same result everywhere, accepting that
-# picking up a new compiler becomes a deliberate change rather than something that happens on
-# its own.
+# We did this to achieve <qua>, accepting <dwn>.
 #
-# We think this is the right trade-off because a build that only fails on someone else's
-# machine costs far more to chase down than an occasional version bump.
+# We think this is the right trade-off because <why>.
 { }
diff --git a/tests/instas.rs b/tests/instas.rs
index e8cec67..a621624 100644
--- a/tests/instas.rs
+++ b/tests/instas.rs
@@ -43,17 +43,17 @@ fn stars() {
         Rust,
         r#"
 /*
- * YADR: 2023-11-29 foo-bar also
- * In the context of <use case/user story u>, we faced <concern c>.
+ * YADR: 2023-11-29 <title>
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  *
- * Also, foobar to the baz.
+ * <tail>
  */
 "#
     );
@@ -64,15 +64,15 @@ fn stripes() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 "#
     );
 }
@@ -82,15 +82,15 @@ fn hashes_nix() {
     harness!(
         Nix,
         r#"
-# YADR: 2023-11-30 bar-baz
-# In the context of <use case/user story u>, we faced <concern c>.
+# YADR: 2023-11-30 <title>
+# In the context of <ctx>, we faced <con>.
 #
-# We decided for <option o>, and neglected <other options>.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve <system qualities/desired consequences>, accepting
-# <downside d/undesired consequences>.
+# We did this to achieve <qua>, accepting
+# <dwn>.
 #
-# We think this is the right trade-off because <additional rationale>.
+# We think this is the right trade-off because <why>.
 "#
     );
 }
@@ -100,15 +100,15 @@ fn block_nix() {
     harness!(
         Nix,
         r#"
-/* YADR: 2023-11-30 bar-baz
- * In the context of <use case/user story u>, we faced <concern c>.
+/* YADR: 2023-11-30 <title>
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  */
 "#
     );
@@ -119,15 +119,15 @@ fn double_block_nix() {
     harness!(
         Nix,
         r#"
-/** YADR: 2023-11-30 bar-baz
- * In the context of <use case/user story u>, we faced <concern c>.
+/** YADR: 2023-11-30 <title>
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  **/
 "#
     );
@@ -138,30 +138,30 @@ fn stripes_to_space() {
     harness!(
         Rust,
         r#"
-//! YADR: 2023-11-30 bar-baz
-//! In the context of <use case/user story u>, we faced <concern c>.
+//! YADR: 2023-11-30 <title>
+//! In the context of <ctx>, we faced <con>.
 //!
-//! We decided for <option o>, and neglected <other options>.
+//! We decided for <opt>, and neglected <alt>.
 //!
-//! We did this to achieve <system qualities/desired consequences>, accepting
-//! <downside d/undesired consequences>.
+//! We did this to achieve <qua>, accepting
+//! <dwn>.
 //!
-//! We think this is the right trade-off because <additional rationale>.
+//! We think this is the right trade-off because <why>.
 //!
-//! some more additional docs
-//! for this
-//! module
+//! <tail spanning
+//! several lines
+//! of module docs>
 //!
 //!
-//! YADR: 2023-12-01 foo-bar-baz
-//! In the context of <use case/user story u>, we faced <concern c>.
+//! YADR: 2023-12-01 <title>
+//! In the context of <ctx>, we faced <con>.
 //!
-//! We decided for <option o>, and neglected <other options>.
+//! We decided for <opt>, and neglected <alt>.
 //!
-//! We did this to achieve <system qualities/desired consequences>, accepting
-//! <downside d/undesired consequences>.
+//! We did this to achieve <qua>, accepting
+//! <dwn>.
 //!
-//! We think this is the right trade-off because <additional rationale>.
+//! We think this is the right trade-off because <why>.
 "#
     );
 }
@@ -171,15 +171,15 @@ fn hashes() {
     harness!(
         Python,
         r#"
-# YADR: 2023-11-30 bar-baz
-# In the context of <use case/user story u>, we faced <concern c>.
+# YADR: 2023-11-30 <title>
+# In the context of <ctx>, we faced <con>.
 #
-# We decided for <option o>, and neglected <other options>.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve <system qualities/desired consequences>, accepting
-# <downside d/undesired consequences>.
+# We did this to achieve <qua>, accepting
+# <dwn>.
 #
-# We think this is the right trade-off because <additional rationale>.
+# We think this is the right trade-off because <why>.
 "#
     );
 }
@@ -190,15 +190,15 @@ fn docstr_double() {
         Python,
         r#"
 """
-YADR: 2023-11-30 bar-baz
-In the context of <use case/user story u>, we faced <concern c>.
+YADR: 2023-11-30 <title>
+In the context of <ctx>, we faced <con>.
 
-We decided for <option o>, and neglected <other options>.
+We decided for <opt>, and neglected <alt>.
 
-We did this to achieve <system qualities/desired consequences>, accepting
-<downside d/undesired consequences>.
+We did this to achieve <qua>, accepting
+<dwn>.
 
-We think this is the right trade-off because <additional rationale>.
+We think this is the right trade-off because <why>.
 """
 "#
     );
@@ -210,15 +210,15 @@ fn docstr_single() {
         Python,
         r#"
 '''
-YADR: 2023-11-30 bar-baz
-In the context of <use case/user story u>, we faced <concern c>.
+YADR: 2023-11-30 <title>
+In the context of <ctx>, we faced <con>.
 
-We decided for <option o>, and neglected <other options>.
+We decided for <opt>, and neglected <alt>.
 
-We did this to achieve <system qualities/desired consequences>, accepting
-<downside d/undesired consequences>.
+We did this to achieve <qua>, accepting
+<dwn>.
 
-We think this is the right trade-off because <additional rationale>.
+We think this is the right trade-off because <why>.
 '''
 "#
     );
@@ -230,15 +230,15 @@ fn docstr_raw() {
         Python,
         r#"
 r'''
-YADR: 2023-11-30 bar-baz
-In the context of <use case/user story u>, we faced <concern c>.
+YADR: 2023-11-30 <title>
+In the context of <ctx>, we faced <con>.
 
-We decided for <option o>, and neglected <other options>.
+We decided for <opt>, and neglected <alt>.
 
-We did this to achieve <system qualities/desired consequences>, accepting
-<downside d/undesired consequences>.
+We did this to achieve <qua>, accepting
+<dwn>.
 
-We think this is the right trade-off because <additional rationale>.
+We think this is the right trade-off because <why>.
 '''
 "#
     );
@@ -250,15 +250,15 @@ fn docstr_unicode() {
         Python,
         r#"
 u'''
-YADR: 2023-11-30 bar-baz
-In the context of <use case/user story u>, we faced <concern c>.
+YADR: 2023-11-30 <title>
+In the context of <ctx>, we faced <con>.
 
-We decided for <option o>, and neglected <other options>.
+We decided for <opt>, and neglected <alt>.
 
-We did this to achieve <system qualities/desired consequences>, accepting
-<downside d/undesired consequences>.
+We did this to achieve <qua>, accepting
+<dwn>.
 
-We think this is the right trade-off because <additional rationale>.
+We think this is the right trade-off because <why>.
 '''
 "#
     );
@@ -298,15 +298,15 @@ fn docstr_raw_unicode() {
         Python,
         r#"
 ru'''
-YADR: 2023-11-30 bar-baz
-In the context of <use case/user story u>, we faced <concern c>.
+YADR: 2023-11-30 <title>
+In the context of <ctx>, we faced <con>.
 
-We decided for <option o>, and neglected <other options>.
+We decided for <opt>, and neglected <alt>.
 
-We did this to achieve <system qualities/desired consequences>, accepting
-<downside d/undesired consequences>.
+We did this to achieve <qua>, accepting
+<dwn>.
 
-We think this is the right trade-off because <additional rationale>.
+We think this is the right trade-off because <why>.
 '''
 "#
     );
@@ -317,21 +317,21 @@ fn early_termination_dashes() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
+// <tail>
 //
 // ---
 //
-// I don't want this included.
+// <excluded>
 "#
     );
 }
@@ -341,20 +341,20 @@ fn early_termination_triple_newline() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
+// <tail>
 //
 //
-// I don't want this included.
+// <excluded>
 "#
     );
 }
@@ -364,21 +364,21 @@ fn with_changes() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
+// <tail>
 //
-// 2023-12-01: changed thing 1
-// 2023-12-02: changed thing 2
-// 2023-12-03: changed thing 3
+// 2023-12-01: <chg1>
+// 2023-12-02: <chg2>
+// 2023-12-03: <chg3>
 "#
     );
 }
@@ -388,24 +388,24 @@ fn early_termination_with_changes() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
+// <tail>
 //
-// 2023-12-01: changed thing 1
-// 2023-12-02: changed thing 2
-// 2023-12-03: changed thing 3
+// 2023-12-01: <chg1>
+// 2023-12-02: <chg2>
+// 2023-12-03: <chg3>
 //
 //
-// I don't want this included.
+// <excluded>
 "#
     );
 }
@@ -463,28 +463,25 @@ fn indented_malformed_paragraph() {
         Rust,
         r#"
         /*
-         * YADR: 2024-02-10 bar-baz
+         * YADR: 2024-02-10 <title>
          *
-         * In the context of <use case/user story u> written out at enough length that it
-         * wraps onto a second and then a third line of the comment, we faced <concern c>
-         * that is described at similar length.
+         * In the context of <ctx padded out over enough words that it wraps onto a second
+         * and then a third line of the comment so that the paragraph offset has to account
+         * for the line breaks within it>, we faced <con described at a similar length>.
          *
-         * We decided for <option o>, spelled out over several lines so that the paragraph
-         * ahead of the malformed one is more than a single line tall, and neglected <other
-         * options>, which are listed here at a comparable length so that this paragraph
-         * ends up four lines tall in total.
+         * We decided for <opt spelled out over several lines so that the paragraph ahead of
+         * the malformed one is more than a single line tall>, and neglected <alt listed here
+         * at a comparable length so that this paragraph ends up four lines tall in total>.
          *
-         * We did this to produce <system qualities/desired consequences>, spread over
-         * enough lines that the reported span has to cover more than one of them, and
-         * padded out further so that the shape of this paragraph matches the one before
-         * it, accepting <downside d/undesired consequences>, which are written out at
-         * length for the same reason.
+         * We did this to produce <qua spread over enough lines that the reported span has to
+         * cover more than one of them and padded out further so that the shape of this
+         * paragraph matches the one before it>, accepting <dwn written out at length for the
+         * same reason>.
          *
-         * We think this is the right trade-off because <additional rationale>, stated over
-         * a few lines so that the diagnostic has something to show underneath the span it
-         * highlights.
+         * We think this is the right trade-off because <why stated over a few lines so that
+         * the diagnostic has something to show underneath the span it highlights>.
          *
-         * A trailing paragraph, so the malformed one is not the last thing in the comment.
+         * <trailing paragraph so the malformed one is not the last thing in the comment>
          */
 "#
     );
@@ -496,25 +493,25 @@ fn two_in_one_rs() {
         Rust,
         r#"
 /*
- * YADR: 2023-11-29 foo-bar also
- * In the context of <use case/user story u>, we faced <concern c>.
+ * YADR: 2023-11-29 <title>
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
 
- YADR: 2023-11-30 bar-baz
- In the context of <use case/user story u>, we faced <concern c>.
+ YADR: 2023-11-30 <title>
+ In the context of <ctx>, we faced <con>.
 
- We decided for <option o>, and neglected <other options>.
+ We decided for <opt>, and neglected <alt>.
 
- We did this to achieve <system qualities/desired consequences>, accepting
- <downside d/undesired consequences>.
+ We did this to achieve <qua>, accepting
+ <dwn>.
 
- We think this is the right trade-off because <additional rationale>.
+ We think this is the right trade-off because <why>.
  */
 "#
     );
@@ -525,25 +522,25 @@ fn two_in_one_py() {
     harness!(
         Python,
         r#"
-# YADR: 2023-11-29 foo-bar also
-# In the context of <use case/user story u>, we faced <concern c>.
+# YADR: 2023-11-29 <title>
+# In the context of <ctx>, we faced <con>.
 #
-# We decided for <option o>, and neglected <other options>.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve <system qualities/desired consequences>, accepting
-# <downside d/undesired consequences>.
+# We did this to achieve <qua>, accepting
+# <dwn>.
 #
-# We think this is the right trade-off because <additional rationale>.
+# We think this is the right trade-off because <why>.
 #
-# YADR: 2023-11-30 bar-baz
-# In the context of <use case/user story u>, we faced <concern c>.
+# YADR: 2023-11-30 <title>
+# In the context of <ctx>, we faced <con>.
 #
-# We decided for <option o>, and neglected <other options>.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve <system qualities/desired consequences>, accepting
-# <downside d/undesired consequences>.
+# We did this to achieve <qua>, accepting
+# <dwn>.
 #
-# We think this is the right trade-off because <additional rationale>.
+# We think this is the right trade-off because <why>.
 "#
     );
 }
@@ -554,13 +551,13 @@ fn missing_paragraph() {
         Rust,
         r#"
 /*
- * YADR: 2023-11-29 foo-bar also
- * In the context of <use case/user story u>, we faced <concern c>.
+ * YADR: 2023-11-29 <title>
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  */
 "#
     );
@@ -572,15 +569,15 @@ fn malformed_para() {
         Rust,
         r#"
 /*
- * YADR: 2023-11-29 foo-bar also
- * In the context of <use case/user story u>, we faced <concern c>.
+ * YADR: 2023-11-29 <title>
+ * In the context of <ctx>, we faced <con>.
  *
- * We failed to follow the format for <option o>, and neglected <other options>.
+ * We failed to follow the format for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  */
 "#
     );
@@ -593,14 +590,14 @@ fn title_no_colon() {
         r#"
 /*
  * YADR 2023-11-29 foo-bar also
- * In the context of <use case/user story u>, we faced <concern c>.
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  */
 "#
     );
@@ -613,14 +610,14 @@ fn no_title_seq() {
         r#"
 /*
  * YADR: foo-bar also
- * In the context of <use case/user story u>, we faced <concern c>.
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  */
 "#
     );
@@ -633,14 +630,14 @@ fn no_title() {
         r#"
 /*
  * YADR
- * In the context of <use case/user story u>, we faced <concern c>.
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  */
 "#
     );
@@ -653,14 +650,14 @@ fn empty_title() {
         r#"
 /*
  * YADR:   
- * In the context of <use case/user story u>, we faced <concern c>.
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for <option o>, and neglected <other options>.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve <system qualities/desired consequences>, accepting
- * <downside d/undesired consequences>.
+ * We did this to achieve <qua>, accepting
+ * <dwn>.
  *
- * We think this is the right trade-off because <additional rationale>.
+ * We think this is the right trade-off because <why>.
  */
 "#
     );
@@ -671,21 +668,21 @@ fn change_missing_colon() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
+// <tail>
 //
-// 2023-12-01: changed thing 1
-// 2023-12-02 changed thing 2
-// 2023-12-03: changed thing 3
+// 2023-12-01: <chg1>
+// 2023-12-02 <chg2>
+// 2023-12-03: <chg3>
 "#
     );
 }
@@ -695,21 +692,21 @@ fn changes_before_tail() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// 2023-12-01: changed thing 1
-// 2023-12-02: changed thing 2
-// 2023-12-03: changed thing 3
+// 2023-12-01: <chg1>
+// 2023-12-02: <chg2>
+// 2023-12-03: <chg3>
 //
-// Here's a tail.
+// <tail>
 "#
     );
 }
@@ -719,21 +716,21 @@ fn change_invalid_date() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
+// <tail>
 //
-// 2023-12-01: changed thing 1
-// 000: changed thing 2
-// 2023-12-03: changed thing 3
+// 2023-12-01: <chg1>
+// 000: <chg2>
+// 2023-12-03: <chg3>
 "#
     );
 }
@@ -743,20 +740,20 @@ fn no_empty_line_before_changes() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
-// 2023-12-01: changed thing 1
-// 2023-12-02: changed thing 2
-// 2023-12-03: changed thing 3
+// <tail>
+// 2023-12-01: <chg1>
+// 2023-12-02: <chg2>
+// 2023-12-03: <chg3>
 "#
     );
 }
@@ -766,21 +763,21 @@ fn bad_change_ordering() {
     harness!(
         Rust,
         r#"
-// YADR: 2023-11-30 bar-baz
-// In the context of <use case/user story u>, we faced <concern c>.
+// YADR: 2023-11-30 <title>
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for <option o>, and neglected <other options>.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve <system qualities/desired consequences>, accepting
-// <downside d/undesired consequences>.
+// We did this to achieve <qua>, accepting
+// <dwn>.
 //
-// We think this is the right trade-off because <additional rationale>.
+// We think this is the right trade-off because <why>.
 //
-// Here's a tail.
+// <tail>
 //
-// 2023-12-02: changed thing 2
-// 2023-12-03: changed thing 3
-// 2023-12-01: changed thing 1
+// 2023-12-02: <chg2>
+// 2023-12-03: <chg3>
+// 2023-12-01: <chg1>
 "#
     );
 }
diff --git a/tests/snapshots/instas__bad_change_ordering.snap b/tests/snapshots/instas__bad_change_ordering.snap
index 0646b10..ddbaf73 100644
--- a/tests/snapshots/instas__bad_change_ordering.snap
+++ b/tests/snapshots/instas__bad_change_ordering.snap
@@ -1,18 +1,17 @@
 ---
 source: tests/instas.rs
-expression: "format!(\"{e:?}\")"
+expression: "format! (\"{e:?}\")"
 ---
   x in comment on line 2
   |-> in Y-Statement starting on line 2
   `-> ADR change entries are not in chronological order
     ,-[13:1]
- 10 | Here's a tail.
+ 10 | <tail>
  11 | 
- 12 | 2023-12-02: changed thing 2
- 13 | 2023-12-03: changed thing 3
-    : ^^^^^^^^^^^^^|^^^^^^^^^^^^^
-    :              `-- this entry should come after the one below it
- 14 | 2023-12-01: changed thing 1
+ 12 | 2023-12-02: <chg2>
+ 13 | 2023-12-03: <chg3>
+    : ^^^^^^^^^|^^^^^^^^
+    :          `-- this entry should come after the one below it
+ 14 | 2023-12-01: <chg1>
     `----
   help: sort the change entries such that they are listed from oldest to newest
-
diff --git a/tests/snapshots/instas__block_nix.snap b/tests/snapshots/instas__block_nix.snap
index 5c74022..20736ff 100644
--- a/tests/snapshots/instas__block_nix.snap
+++ b/tests/snapshots/instas__block_nix.snap
@@ -7,14 +7,14 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__change_invalid_date.snap b/tests/snapshots/instas__change_invalid_date.snap
index 2391963..f082f4e 100644
--- a/tests/snapshots/instas__change_invalid_date.snap
+++ b/tests/snapshots/instas__change_invalid_date.snap
@@ -6,11 +6,11 @@ expression: "format! (\"{e:?}\")"
   |-> in Y-Statement starting on line 2
   `-> Y-Statement change entry did not match expected format: expected four digit year (or leading sign for six digit year), but found end of input
     ,-[13:1]
- 10 | Here's a tail.
+ 10 | <tail>
  11 | 
- 12 | 2023-12-01: changed thing 1
- 13 | 000: changed thing 2
+ 12 | 2023-12-01: <chg1>
+ 13 | 000: <chg2>
     : ^|^
     :  `-- expected YYYY-MM-DD
- 14 | 2023-12-03: changed thing 3
+ 14 | 2023-12-03: <chg3>
     `----
diff --git a/tests/snapshots/instas__change_missing_colon.snap b/tests/snapshots/instas__change_missing_colon.snap
index cc4a534..67cef26 100644
--- a/tests/snapshots/instas__change_missing_colon.snap
+++ b/tests/snapshots/instas__change_missing_colon.snap
@@ -1,16 +1,15 @@
 ---
 source: tests/instas.rs
-expression: "format!(\"{e:?}\")"
+expression: "format! (\"{e:?}\")"
 ---
   x in comment on line 2
   |-> in Y-Statement starting on line 2
   `-> missing empty line before list of change list
     ,-[14:1]
  11 | 
- 12 | 2023-12-01: changed thing 1
- 13 | 2023-12-02 changed thing 2
- 14 | 2023-12-03: changed thing 3
-    : ^^^^^^^^^^^^^|^^^^^^^^^^^^^
-    :              `-- before this list of changes
+ 12 | 2023-12-01: <chg1>
+ 13 | 2023-12-02 <chg2>
+ 14 | 2023-12-03: <chg3>
+    : ^^^^^^^^^|^^^^^^^^
+    :          `-- before this list of changes
     `----
-
diff --git a/tests/snapshots/instas__changes_before_tail.snap b/tests/snapshots/instas__changes_before_tail.snap
index 03db0f7..7f84f50 100644
--- a/tests/snapshots/instas__changes_before_tail.snap
+++ b/tests/snapshots/instas__changes_before_tail.snap
@@ -1,19 +1,18 @@
 ---
 source: tests/instas.rs
-expression: "format!(\"{e:?}\")"
+expression: "format! (\"{e:?}\")"
 ---
   x in comment on line 2
   |-> in Y-Statement starting on line 2
   `-> found ADR change in the middle of a YADR block
     ,-[12:1]
   9 | 
- 10 | 2023-12-01: changed thing 1
- 11 | 2023-12-02: changed thing 2
- 12 | 2023-12-03: changed thing 3
-    : ^^^^^^^^^^^^^|^^^^^^^^^^^^^
-    :              `-- this looks like an ADR change entry
+ 10 | 2023-12-01: <chg1>
+ 11 | 2023-12-02: <chg2>
+ 12 | 2023-12-03: <chg3>
+    : ^^^^^^^^^|^^^^^^^^
+    :          `-- this looks like an ADR change entry
  13 | 
- 14 | Here's a tail.
+ 14 | <tail>
     `----
   help: move the change entries to the end of the YADR block
-
diff --git a/tests/snapshots/instas__docstr_double.snap b/tests/snapshots/instas__docstr_double.snap
index 8846ec6..6bfb63f 100644
--- a/tests/snapshots/instas__docstr_double.snap
+++ b/tests/snapshots/instas__docstr_double.snap
@@ -7,14 +7,14 @@ expression: v
         3,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__docstr_raw.snap b/tests/snapshots/instas__docstr_raw.snap
index 8846ec6..6bfb63f 100644
--- a/tests/snapshots/instas__docstr_raw.snap
+++ b/tests/snapshots/instas__docstr_raw.snap
@@ -7,14 +7,14 @@ expression: v
         3,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__docstr_raw_unicode.snap b/tests/snapshots/instas__docstr_raw_unicode.snap
index 8846ec6..6bfb63f 100644
--- a/tests/snapshots/instas__docstr_raw_unicode.snap
+++ b/tests/snapshots/instas__docstr_raw_unicode.snap
@@ -7,14 +7,14 @@ expression: v
         3,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__docstr_single.snap b/tests/snapshots/instas__docstr_single.snap
index 8846ec6..6bfb63f 100644
--- a/tests/snapshots/instas__docstr_single.snap
+++ b/tests/snapshots/instas__docstr_single.snap
@@ -7,14 +7,14 @@ expression: v
         3,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__docstr_unicode.snap b/tests/snapshots/instas__docstr_unicode.snap
index 8846ec6..6bfb63f 100644
--- a/tests/snapshots/instas__docstr_unicode.snap
+++ b/tests/snapshots/instas__docstr_unicode.snap
@@ -7,14 +7,14 @@ expression: v
         3,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__double_block_nix.snap b/tests/snapshots/instas__double_block_nix.snap
index 5c74022..20736ff 100644
--- a/tests/snapshots/instas__double_block_nix.snap
+++ b/tests/snapshots/instas__double_block_nix.snap
@@ -7,14 +7,14 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__early_termination_dashes.snap b/tests/snapshots/instas__early_termination_dashes.snap
index 0d3fd0d..383bd3c 100644
--- a/tests/snapshots/instas__early_termination_dashes.snap
+++ b/tests/snapshots/instas__early_termination_dashes.snap
@@ -7,16 +7,16 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: Some(
-                "Here's a tail.",
+                "<tail>",
             ),
             changes: [],
         },
diff --git a/tests/snapshots/instas__early_termination_triple_newline.snap b/tests/snapshots/instas__early_termination_triple_newline.snap
index 0d3fd0d..383bd3c 100644
--- a/tests/snapshots/instas__early_termination_triple_newline.snap
+++ b/tests/snapshots/instas__early_termination_triple_newline.snap
@@ -7,16 +7,16 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: Some(
-                "Here's a tail.",
+                "<tail>",
             ),
             changes: [],
         },
diff --git a/tests/snapshots/instas__early_termination_with_changes.snap b/tests/snapshots/instas__early_termination_with_changes.snap
index b4c1854..bcdc564 100644
--- a/tests/snapshots/instas__early_termination_with_changes.snap
+++ b/tests/snapshots/instas__early_termination_with_changes.snap
@@ -7,29 +7,29 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: Some(
-                "Here's a tail.",
+                "<tail>",
             ),
             changes: [
                 (
                     2023-12-01,
-                    "changed thing 1",
+                    "<chg1>",
                 ),
                 (
                     2023-12-02,
-                    "changed thing 2",
+                    "<chg2>",
                 ),
                 (
                     2023-12-03,
-                    "changed thing 3",
+                    "<chg3>",
                 ),
             ],
         },
diff --git a/tests/snapshots/instas__hashes.snap b/tests/snapshots/instas__hashes.snap
index 5c74022..20736ff 100644
--- a/tests/snapshots/instas__hashes.snap
+++ b/tests/snapshots/instas__hashes.snap
@@ -7,14 +7,14 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__hashes_nix.snap b/tests/snapshots/instas__hashes_nix.snap
index 9c6282d..20736ff 100644
--- a/tests/snapshots/instas__hashes_nix.snap
+++ b/tests/snapshots/instas__hashes_nix.snap
@@ -1,6 +1,5 @@
 ---
 source: tests/instas.rs
-assertion_line: 81
 expression: v
 ---
 [
@@ -8,14 +7,14 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__indented_malformed_paragraph.snap b/tests/snapshots/instas__indented_malformed_paragraph.snap
index 4f35db5..8557751 100644
--- a/tests/snapshots/instas__indented_malformed_paragraph.snap
+++ b/tests/snapshots/instas__indented_malformed_paragraph.snap
@@ -6,18 +6,17 @@ expression: "format! (\"{e:?}\")"
   |-> in Y-Statement starting on line 3
   |-> in paragraph 3 of that statement
   `-> Y-Statement did not match expected format
-    ,-[11:1]
-  8 |     options>, which are listed here at a comparable length so that this paragraph
-  9 |     ends up four lines tall in total.
- 10 |     
- 11 | ,-> We did this to produce <system qualities/desired consequences>, spread over
- 12 | |   enough lines that the reported span has to cover more than one of them, and
- 13 | |   padded out further so that the shape of this paragraph matches the one before
- 14 | |   it, accepting <downside d/undesired consequences>, which are written out at
- 15 | |-> length for the same reason.
+    ,-[10:1]
+  7 |     the malformed one is more than a single line tall>, and neglected <alt listed here
+  8 |     at a comparable length so that this paragraph ends up four lines tall in total>.
+  9 |     
+ 10 | ,-> We did this to produce <qua spread over enough lines that the reported span has to
+ 11 | |   cover more than one of them and padded out further so that the shape of this
+ 12 | |   paragraph matches the one before it>, accepting <dwn written out at length for the
+ 13 | |-> same reason>.
     : `---- expected "We did this to achieve <..>, accepting <..>."
- 16 |     
- 17 |     We think this is the right trade-off because <additional rationale>, stated over
- 18 |     a few lines so that the diagnostic has something to show underneath the span it
+ 14 |     
+ 15 |     We think this is the right trade-off because <why stated over a few lines so that
+ 16 |     the diagnostic has something to show underneath the span it highlights>.
     `----
   help: Note that punctuation is significant; you have to match every , and .
diff --git a/tests/snapshots/instas__malformed_para.snap b/tests/snapshots/instas__malformed_para.snap
index eab71e8..50764c2 100644
--- a/tests/snapshots/instas__malformed_para.snap
+++ b/tests/snapshots/instas__malformed_para.snap
@@ -1,20 +1,19 @@
 ---
 source: tests/instas.rs
-expression: "format!(\"{e:?}\")"
+expression: "format! (\"{e:?}\")"
 ---
   x in comment on line 2
   |-> in Y-Statement starting on line 3
   |-> in paragraph 2 of that statement
   `-> Y-Statement did not match expected format
    ,-[3:1]
- 1 | In the context of <use case/user story u>, we faced <concern c>.
+ 1 | In the context of <ctx>, we faced <con>.
  2 | 
- 3 | We failed to follow the format for <option o>, and neglected <other options>.
-   : ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-   :                                       `-- expected "We decided for <..>, and neglected <..>."
+ 3 | We failed to follow the format for <opt>, and neglected <alt>.
+   : ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^|^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   :                                `-- expected "We decided for <..>, and neglected <..>."
  4 | 
- 5 | We did this to achieve <system qualities/desired consequences>, accepting
- 6 | <downside d/undesired consequences>.
+ 5 | We did this to achieve <qua>, accepting
+ 6 | <dwn>.
    `----
   help: Note that punctuation is significant; you have to match every , and .
-
diff --git a/tests/snapshots/instas__missing_paragraph.snap b/tests/snapshots/instas__missing_paragraph.snap
index 8dae7e9..43c5c67 100644
--- a/tests/snapshots/instas__missing_paragraph.snap
+++ b/tests/snapshots/instas__missing_paragraph.snap
@@ -1,16 +1,15 @@
 ---
 source: tests/instas.rs
-expression: "format!(\"{e:?}\")"
+expression: "format! (\"{e:?}\")"
 ---
   x in comment on line 2
   |-> in Y-Statement starting on line 3
   `-> Y-Statement is missing a paragraph.
    ,-[7:1]
  4 | 
- 5 | We did this to achieve <system qualities/desired consequences>, accepting
- 6 | <downside d/undesired consequences>.
+ 5 | We did this to achieve <qua>, accepting
+ 6 | <dwn>.
  7 |    
    : ^|^
    :  `-- expected "We think this is the right trade-off because <..>."
    `----
-
diff --git a/tests/snapshots/instas__no_empty_line_before_changes.snap b/tests/snapshots/instas__no_empty_line_before_changes.snap
index b011672..5146852 100644
--- a/tests/snapshots/instas__no_empty_line_before_changes.snap
+++ b/tests/snapshots/instas__no_empty_line_before_changes.snap
@@ -1,17 +1,16 @@
 ---
 source: tests/instas.rs
-expression: "format!(\"{e:?}\")"
+expression: "format! (\"{e:?}\")"
 ---
   x in comment on line 2
   |-> in Y-Statement starting on line 2
   `-> missing empty line before list of change list
     ,-[11:1]
-  8 |     We think this is the right trade-off because <additional rationale>.
+  8 |     We think this is the right trade-off because <why>.
   9 |     
- 10 |     Here's a tail.
- 11 | ,-> 2023-12-01: changed thing 1
- 12 | |   2023-12-02: changed thing 2
- 13 | |-> 2023-12-03: changed thing 3
+ 10 |     <tail>
+ 11 | ,-> 2023-12-01: <chg1>
+ 12 | |   2023-12-02: <chg2>
+ 13 | |-> 2023-12-03: <chg3>
     : `---- before this list of changes
     `----
-
diff --git a/tests/snapshots/instas__stars.snap b/tests/snapshots/instas__stars.snap
index ee8489e..60a8dca 100644
--- a/tests/snapshots/instas__stars.snap
+++ b/tests/snapshots/instas__stars.snap
@@ -7,16 +7,16 @@ expression: v
         3,
         YAdr {
             date: 2023-11-29,
-            title: "2023-11-29 foo-bar also",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-29 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: Some(
-                "Also, foobar to the baz.",
+                "<tail>",
             ),
             changes: [],
         },
diff --git a/tests/snapshots/instas__stripes.snap b/tests/snapshots/instas__stripes.snap
index 5c74022..20736ff 100644
--- a/tests/snapshots/instas__stripes.snap
+++ b/tests/snapshots/instas__stripes.snap
@@ -7,14 +7,14 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__stripes_to_space.snap b/tests/snapshots/instas__stripes_to_space.snap
index a9897de..fd95e86 100644
--- a/tests/snapshots/instas__stripes_to_space.snap
+++ b/tests/snapshots/instas__stripes_to_space.snap
@@ -7,16 +7,16 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: Some(
-                "some more additional docs\nfor this\nmodule",
+                "<tail spanning\nseveral lines\nof module docs>",
             ),
             changes: [],
         },
@@ -25,14 +25,14 @@ expression: v
         17,
         YAdr {
             date: 2023-12-01,
-            title: "2023-12-01 foo-bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-12-01 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__two_in_one_py.snap b/tests/snapshots/instas__two_in_one_py.snap
index f3e8a77..4fd6df5 100644
--- a/tests/snapshots/instas__two_in_one_py.snap
+++ b/tests/snapshots/instas__two_in_one_py.snap
@@ -7,14 +7,14 @@ expression: v
         2,
         YAdr {
             date: 2023-11-29,
-            title: "2023-11-29 foo-bar also",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-29 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
@@ -23,14 +23,14 @@ expression: v
         12,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__two_in_one_rs.snap b/tests/snapshots/instas__two_in_one_rs.snap
index 8f2bba0..03393ca 100644
--- a/tests/snapshots/instas__two_in_one_rs.snap
+++ b/tests/snapshots/instas__two_in_one_rs.snap
@@ -7,14 +7,14 @@ expression: v
         3,
         YAdr {
             date: 2023-11-29,
-            title: "2023-11-29 foo-bar also",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-29 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
@@ -23,14 +23,14 @@ expression: v
         13,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: None,
             changes: [],
         },
diff --git a/tests/snapshots/instas__with_changes.snap b/tests/snapshots/instas__with_changes.snap
index b4c1854..bcdc564 100644
--- a/tests/snapshots/instas__with_changes.snap
+++ b/tests/snapshots/instas__with_changes.snap
@@ -7,29 +7,29 @@ expression: v
         2,
         YAdr {
             date: 2023-11-30,
-            title: "2023-11-30 bar-baz",
-            in_context: "<use case/user story u>",
-            facing_concern: "<concern c>",
-            chosen_option: "<option o>",
-            neglected_options: "<other options>",
-            to_achieve: "<system qualities/desired consequences>",
-            accepted_downsides: "<downside d/undesired consequences>",
-            because: "<additional rationale>",
+            title: "2023-11-30 <title>",
+            in_context: "<ctx>",
+            facing_concern: "<con>",
+            chosen_option: "<opt>",
+            neglected_options: "<alt>",
+            to_achieve: "<qua>",
+            accepted_downsides: "<dwn>",
+            because: "<why>",
             tail: Some(
-                "Here's a tail.",
+                "<tail>",
             ),
             changes: [
                 (
                     2023-12-01,
-                    "changed thing 1",
+                    "<chg1>",
                 ),
                 (
                     2023-12-02,
-                    "changed thing 2",
+                    "<chg2>",
                 ),
                 (
                     2023-12-03,
-                    "changed thing 3",
+                    "<chg3>",
                 ),
             ],
         },