@supersuit/hyperspec 0.6.0 → 0.8.0

package/examples/writing/essay/judge/doctor.packet.json

@@ -0,0 +1,108 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "doctor",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "the doctor grades the draft against every condition; the simulated reader is asked whether it would copy the questions now",
+  "instructions": "Grade the draft (inputs.draft) against each condition in inputs.conditions: a condition passes unless the draft does what its fails_when describes. For every judgment, quote the draft as evidence: each evidence field is a span copied verbatim from inputs.draft. Then answer whether this reader, having read the draft, would take the next step (inputs.goal.next_if_worked) now, and quote the passage that decided it. Answer only in the verdict shape given in verdict_schema: one entry per condition id, each exactly once, with pass and would_take_next_step as true or false, and a note saying why for every condition that fails.",
+  "inputs": {
+    "goal": {
+      "from": "plans to run the first one-on-one from their own list",
+      "to": "hands the first one-on-one to the report and asks the three questions",
+      "next_if_worked": "writes the three questions on a card before the meeting",
+      "change": {
+        "kind": "action",
+        "text": "the reader asks the three questions in their next one-on-one and waits after each"
+      }
+    },
+    "conditions": [
+      {
+        "id": "r1",
+        "text": "the opening line tells the reader who sets the agenda of a first one-on-one",
+        "fails_when": "a reader shown only the first two sentences cannot say who should set the agenda"
+      },
+      {
+        "id": "r2",
+        "text": "the three questions appear word for word as the voice memo states them",
+        "fails_when": "any of the three questions differs from essay/materials/voice-memo.md by a word"
+      },
+      {
+        "id": "r3",
+        "text": "every survey figure in the draft matches the verified survey summary",
+        "fails_when": "a figure in the draft has no entry in the claims ledger pointing at essay/materials/team-survey.md, or differs from it"
+      },
+      {
+        "id": "r4",
+        "text": "the draft argues only the four claims in the spine, in order",
+        "fails_when": "a paragraph advances a point that traces to none of c1 to c4, or c3 lands before c2"
+      },
+      {
+        "id": "r5",
+        "text": "the draft tells the reader what to do with silence in the meeting",
+        "fails_when": "the draft never says to wait after asking a question"
+      },
+      {
+        "id": "r6",
+        "text": "the draft stays inside its length envelope",
+        "fails_when": "the word count is under 700 or over 1,100"
+      }
+    ],
+    "draft": "# Hand your first one-on-one to the person you manage\n\n## Who sets the agenda\n\nYour first one-on-one with a new report is the only meeting on your calendar where they should\nset the agenda. Everything else you run. This one you hand over.\n\nIf you walk in with a list, you have told your report what the meeting is for, and it is for\nyou. They will answer your list politely and leave. You will know nothing you did not know when\nyou sat down, and so will they.\n\nMy team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last\nquarter was one where they brought the first topic. The meeting that worked for them was the one\nthey started.\n\nSo give them the start. The simplest way to do it is a running agenda: one shared document per\nperson, kept for as long as you manage them. Your report adds items before each meeting, and you\nadd yours last, at the bottom. That is how an engineering manager I interviewed, eight years into\nthe job, runs hers. Her rule is short: the report owns the agenda.\n\n## My first one-on-one\n\nMy first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a\nlist, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes\nlater my report said thanks and left, and I had learned nothing I could not have read in the\ntracker.\n\nWhat I ran was a status meeting, which is a meeting spent reading out loud what the tracker\nalready says. Your report wrote those updates. Asking them to recite the updates to you teaches\nyou nothing new, and it spends the one half hour a week that belongs to them.\n\nThe survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the\nlast quarter was mostly project status. Read the tracker before you walk in, and leave status\nthere.\n\n## The three questions\n\nHere is what I ask now, in this order, and then I let the report take over:\n\n1. What is taking more of your energy than it should?\n2. What do you want to be doing more of in six months?\n3. What should I stop doing, or start doing, that would make your week easier?\n\nThree is enough to hand the meeting over. The first asks about this week. The second asks about\nthe next six months. The third asks about you, and it is the one your report will not raise\nwithout being asked. A fourth question starts to look like your list again, and the list is what\nyou came to give up.\n\nAsk them in the same words every time. Your report will learn them, and after a few weeks they\nwill walk in with answers already half formed. That is the point of fixing the words: the meeting\nstarts on their topic before you have said anything at all.\n\nThe second question is the one my own team asked for. The most common free-text request in the\nsurvey, in 9 responses, was to be asked what they want to work on next.\n\nAfter the third question, stop talking.\n\n## What to do with the answers\n\nWait after each question, longer than you want to. Dana, the engineering manager I interviewed,\nputs it in three short sentences: \"Wait. Count to five. The real answer is the second one.\" The first\nanswer your report gives is the tidy one, the version they could give anyone. The second is what\nthey came in with, and you only hear it if you let the silence run.\n\nWrite down what they say, in their words, at the top of the running agenda. That list is where\nyour next one-on-one starts, so the meeting stays theirs the week after too.\n\nDo not try to fix everything in the room. Pick one thing you can act on this week, say what you\nwill do, and do it before you meet again. The rest stays on the running agenda until it is done\nor your report takes it off.\n\nAnd keep your own urgent items out of it. She told me: \"If I have something urgent, it is not a\none-on-one topic. I send it the day it happens.\" Your report should never have to wait a week to\nhear something you needed them to know on Monday.\n\n## Before the meeting\n\nOpen the invite and delete your list from it. Ask your report to add the first item to the\nrunning agenda instead.\n\nSo write the three questions on a card. Ask the first one. Then wait, longer than feels polite,\nbecause the first answer is the one they rehearsed and the second one is the one you came for.\n"
+  },
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "conditions",
+      "would_take_next_step",
+      "evidence"
+    ],
+    "properties": {
+      "conditions": {
+        "type": "array",
+        "description": "one entry per condition id, each exactly once",
+        "items": {
+          "type": "object",
+          "required": [
+            "id",
+            "pass",
+            "evidence",
+            "note"
+          ],
+          "properties": {
+            "id": {
+              "enum": [
+                "r1",
+                "r2",
+                "r3",
+                "r4",
+                "r5",
+                "r6"
+              ]
+            },
+            "pass": {
+              "type": "boolean"
+            },
+            "evidence": {
+              "type": "string",
+              "description": "a span copied verbatim from the draft"
+            },
+            "note": {
+              "type": "string",
+              "description": "why; required when pass is false"
+            }
+          }
+        }
+      },
+      "would_take_next_step": {
+        "type": "boolean",
+        "description": "whether this reader would take inputs.goal.next_if_worked now"
+      },
+      "evidence": {
+        "type": "string",
+        "description": "a span copied verbatim from the draft that decided would_take_next_step"
+      }
+    }
+  }
+}

package/examples/writing/essay/judge/lineup.packet.json

@@ -0,0 +1,64 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "lineup",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "blind lineup within this scope; a judge shown a generated passage beside the scope's three goldens cannot pick it out",
+  "instructions": "Each passage in inputs.candidates carries a capital-letter label. All but one were written by the writer of inputs.scope, for this form, audience and purpose, and approved by a person; exactly one comes from a new draft. Pick the label of the passage you believe comes from the new draft, judging by voice alone: rhythm, diction, sentence shape, what this writer would and would not say. Give your confidence from 0 (a guess) to 1 (certain), and in reason say what in the candidates decided it. Judge from the packet's inputs alone: do not open the spec, the draft or any other file the packet names. Answer only in the verdict shape given in verdict_schema.",
+  "inputs": {
+    "scope": {
+      "writer": "example-author",
+      "form": "essay",
+      "audience": "new managers",
+      "purpose": "teach"
+    },
+    "candidates": [
+      {
+        "label": "A",
+        "text": "So write the three questions on a card. Ask the first one. Then wait, longer than feels polite, because the first answer is the one they rehearsed and the second one is the one you came for."
+      },
+      {
+        "label": "B",
+        "text": "If you can read it in the tracker, do not ask for it in the room. Status already has a home, and your report is the one who put it there. Spend the half hour on what the tracker cannot hold: how the work looks from their side of it."
+      },
+      {
+        "label": "C",
+        "text": "Your first one-on-one with a new report is the only meeting on your calendar where they should set the agenda. Everything else you run. This one you hand over."
+      },
+      {
+        "label": "D",
+        "text": "The survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status. Read the tracker before you walk in, and leave status there."
+      }
+    ]
+  },
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "pick",
+      "confidence",
+      "reason"
+    ],
+    "properties": {
+      "pick": {
+        "enum": [
+          "A",
+          "B",
+          "C",
+          "D"
+        ],
+        "description": "the label of the passage you believe comes from the new draft"
+      },
+      "confidence": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
+      "reason": {
+        "type": "string",
+        "description": "what in the candidates decided the pick"
+      }
+    }
+  }
+}

package/examples/writing/essay/judge/persona.packet.json

@@ -0,0 +1,73 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "persona",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "persona-consistency judge; the mentor stance holds, and no fact appears that is not in the claims ledger",
+  "instructions": "Read inputs.draft as the speaker inputs.persona describes. Report every break as an entry in breaks: the passage as evidence, copied verbatim from inputs.draft, at least three whole words; its kind; and why. The kind is one of: stance (the voice leaves inputs.persona.stance), assertion (it asserts something outside inputs.persona.may_assert), will_not_say (it says something inputs.persona.will_not_say rules out), unsourced_fact (it states a fact that none of inputs.claims holds). When inputs.claims is null, no claims ledger is declared and facts cannot be checked against sources: do not report unsourced_fact. If the voice holds throughout, breaks is an empty list. Answer only in the verdict shape given in verdict_schema.",
+  "inputs": {
+    "persona": {
+      "identity": "self",
+      "stance": "mentor",
+      "may_assert": [
+        "what the author did in their own first one-on-ones and what happened",
+        "the three questions the author uses now"
+      ],
+      "will_not_say": [
+        "a claim about what most managers do, beyond the survey's own figures",
+        "the name of anyone on the author's team"
+      ]
+    },
+    "claims": [
+      "29 of 41 people said their most useful one-on-one in the last quarter was one where they brought the first topic.",
+      "That is how an engineering manager I interviewed, eight years into the job, runs hers.",
+      "Her rule is short: the report owns the agenda.",
+      "My first one-on-one as a manager was a disaster, and the reason was simple: I ran it.",
+      "11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.",
+      "What is taking more of your energy than it should?",
+      "What do you want to be doing more of in six months?",
+      "What should I stop doing, or start doing, that would make your week easier?",
+      "The most common free-text request in the survey, in 9 responses, was to be asked what they want to work on next."
+    ],
+    "draft": "# Hand your first one-on-one to the person you manage\n\n## Who sets the agenda\n\nYour first one-on-one with a new report is the only meeting on your calendar where they should\nset the agenda. Everything else you run. This one you hand over.\n\nIf you walk in with a list, you have told your report what the meeting is for, and it is for\nyou. They will answer your list politely and leave. You will know nothing you did not know when\nyou sat down, and so will they.\n\nMy team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last\nquarter was one where they brought the first topic. The meeting that worked for them was the one\nthey started.\n\nSo give them the start. The simplest way to do it is a running agenda: one shared document per\nperson, kept for as long as you manage them. Your report adds items before each meeting, and you\nadd yours last, at the bottom. That is how an engineering manager I interviewed, eight years into\nthe job, runs hers. Her rule is short: the report owns the agenda.\n\n## My first one-on-one\n\nMy first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a\nlist, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes\nlater my report said thanks and left, and I had learned nothing I could not have read in the\ntracker.\n\nWhat I ran was a status meeting, which is a meeting spent reading out loud what the tracker\nalready says. Your report wrote those updates. Asking them to recite the updates to you teaches\nyou nothing new, and it spends the one half hour a week that belongs to them.\n\nThe survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the\nlast quarter was mostly project status. Read the tracker before you walk in, and leave status\nthere.\n\n## The three questions\n\nHere is what I ask now, in this order, and then I let the report take over:\n\n1. What is taking more of your energy than it should?\n2. What do you want to be doing more of in six months?\n3. What should I stop doing, or start doing, that would make your week easier?\n\nThree is enough to hand the meeting over. The first asks about this week. The second asks about\nthe next six months. The third asks about you, and it is the one your report will not raise\nwithout being asked. A fourth question starts to look like your list again, and the list is what\nyou came to give up.\n\nAsk them in the same words every time. Your report will learn them, and after a few weeks they\nwill walk in with answers already half formed. That is the point of fixing the words: the meeting\nstarts on their topic before you have said anything at all.\n\nThe second question is the one my own team asked for. The most common free-text request in the\nsurvey, in 9 responses, was to be asked what they want to work on next.\n\nAfter the third question, stop talking.\n\n## What to do with the answers\n\nWait after each question, longer than you want to. Dana, the engineering manager I interviewed,\nputs it in three short sentences: \"Wait. Count to five. The real answer is the second one.\" The first\nanswer your report gives is the tidy one, the version they could give anyone. The second is what\nthey came in with, and you only hear it if you let the silence run.\n\nWrite down what they say, in their words, at the top of the running agenda. That list is where\nyour next one-on-one starts, so the meeting stays theirs the week after too.\n\nDo not try to fix everything in the room. Pick one thing you can act on this week, say what you\nwill do, and do it before you meet again. The rest stays on the running agenda until it is done\nor your report takes it off.\n\nAnd keep your own urgent items out of it. She told me: \"If I have something urgent, it is not a\none-on-one topic. I send it the day it happens.\" Your report should never have to wait a week to\nhear something you needed them to know on Monday.\n\n## Before the meeting\n\nOpen the invite and delete your list from it. Ask your report to add the first item to the\nrunning agenda instead.\n\nSo write the three questions on a card. Ask the first one. Then wait, longer than feels polite,\nbecause the first answer is the one they rehearsed and the second one is the one you came for.\n"
+  },
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "breaks"
+    ],
+    "properties": {
+      "breaks": {
+        "type": "array",
+        "description": "every place the persona breaks; empty when it holds",
+        "items": {
+          "type": "object",
+          "required": [
+            "evidence",
+            "kind",
+            "why"
+          ],
+          "properties": {
+            "evidence": {
+              "type": "string",
+              "description": "the passage, copied verbatim from the draft, at least three words"
+            },
+            "kind": {
+              "enum": [
+                "stance",
+                "assertion",
+                "will_not_say",
+                "unsourced_fact"
+              ]
+            },
+            "why": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/examples/writing/essay/judge/reader.packet.json

@@ -0,0 +1,93 @@
+{
+  "hyperspec_judge": "0.1",
+  "station": "reader",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "draft": "essay/draft.md",
+  "draft_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "rubric": "simulated reader reports where it got lost and where it stopped reading",
+  "instructions": "Read inputs.draft as the reader inputs.audience describes: where and how they read it, knowing only what they know and believing what they believe now. For every place you got lost (a term you do not know, a step that does not follow, a sentence you had to read twice), add an entry to lost_at: the passage as evidence, copied verbatim from inputs.draft, at least three whole words, and why. If you would stop reading before the end, set stopped_at to the passage where you stopped, quoted the same way, and why; if you would read to the end, set stopped_at to null. Then say in next_step what you would do next, in your own words, and whether you would do it now (would_take_next_step). Answer only in the verdict shape given in verdict_schema.",
+  "inputs": {
+    "audience": {
+      "who": "someone in their first three months of managing, who was promoted from the team they now lead",
+      "funnel_now": "has a first one-on-one with a new report on the calendar this week",
+      "knows": [
+        "one-on-one",
+        "report",
+        "tracker"
+      ],
+      "terms": [
+        "running agenda",
+        "status meeting"
+      ],
+      "believes_now": "a one-on-one is where a manager catches up on how the work is going",
+      "wants": "a plan for the first meeting that will not waste either person's half hour",
+      "reads_on": "a phone, in the ten minutes before the meeting",
+      "reader": "person"
+    },
+    "draft": "# Hand your first one-on-one to the person you manage\n\n## Who sets the agenda\n\nYour first one-on-one with a new report is the only meeting on your calendar where they should\nset the agenda. Everything else you run. This one you hand over.\n\nIf you walk in with a list, you have told your report what the meeting is for, and it is for\nyou. They will answer your list politely and leave. You will know nothing you did not know when\nyou sat down, and so will they.\n\nMy team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last\nquarter was one where they brought the first topic. The meeting that worked for them was the one\nthey started.\n\nSo give them the start. The simplest way to do it is a running agenda: one shared document per\nperson, kept for as long as you manage them. Your report adds items before each meeting, and you\nadd yours last, at the bottom. That is how an engineering manager I interviewed, eight years into\nthe job, runs hers. Her rule is short: the report owns the agenda.\n\n## My first one-on-one\n\nMy first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a\nlist, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes\nlater my report said thanks and left, and I had learned nothing I could not have read in the\ntracker.\n\nWhat I ran was a status meeting, which is a meeting spent reading out loud what the tracker\nalready says. Your report wrote those updates. Asking them to recite the updates to you teaches\nyou nothing new, and it spends the one half hour a week that belongs to them.\n\nThe survey shows the cost from their side. 11 of 41 said at least one of their one-on-ones in the\nlast quarter was mostly project status. Read the tracker before you walk in, and leave status\nthere.\n\n## The three questions\n\nHere is what I ask now, in this order, and then I let the report take over:\n\n1. What is taking more of your energy than it should?\n2. What do you want to be doing more of in six months?\n3. What should I stop doing, or start doing, that would make your week easier?\n\nThree is enough to hand the meeting over. The first asks about this week. The second asks about\nthe next six months. The third asks about you, and it is the one your report will not raise\nwithout being asked. A fourth question starts to look like your list again, and the list is what\nyou came to give up.\n\nAsk them in the same words every time. Your report will learn them, and after a few weeks they\nwill walk in with answers already half formed. That is the point of fixing the words: the meeting\nstarts on their topic before you have said anything at all.\n\nThe second question is the one my own team asked for. The most common free-text request in the\nsurvey, in 9 responses, was to be asked what they want to work on next.\n\nAfter the third question, stop talking.\n\n## What to do with the answers\n\nWait after each question, longer than you want to. Dana, the engineering manager I interviewed,\nputs it in three short sentences: \"Wait. Count to five. The real answer is the second one.\" The first\nanswer your report gives is the tidy one, the version they could give anyone. The second is what\nthey came in with, and you only hear it if you let the silence run.\n\nWrite down what they say, in their words, at the top of the running agenda. That list is where\nyour next one-on-one starts, so the meeting stays theirs the week after too.\n\nDo not try to fix everything in the room. Pick one thing you can act on this week, say what you\nwill do, and do it before you meet again. The rest stays on the running agenda until it is done\nor your report takes it off.\n\nAnd keep your own urgent items out of it. She told me: \"If I have something urgent, it is not a\none-on-one topic. I send it the day it happens.\" Your report should never have to wait a week to\nhear something you needed them to know on Monday.\n\n## Before the meeting\n\nOpen the invite and delete your list from it. Ask your report to add the first item to the\nrunning agenda instead.\n\nSo write the three questions on a card. Ask the first one. Then wait, longer than feels polite,\nbecause the first answer is the one they rehearsed and the second one is the one you came for.\n"
+  },
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "lost_at",
+      "stopped_at",
+      "would_take_next_step",
+      "next_step"
+    ],
+    "properties": {
+      "lost_at": {
+        "type": "array",
+        "description": "every place the reader got lost; empty when nowhere",
+        "items": {
+          "type": "object",
+          "required": [
+            "evidence",
+            "why"
+          ],
+          "properties": {
+            "evidence": {
+              "type": "string",
+              "description": "the passage where the reader got lost, copied verbatim from the draft, at least three words"
+            },
+            "why": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "stopped_at": {
+        "anyOf": [
+          {
+            "type": "null"
+          },
+          {
+            "type": "object",
+            "required": [
+              "evidence",
+              "why"
+            ],
+            "properties": {
+              "evidence": {
+                "type": "string",
+                "description": "the passage where the reader stopped reading, copied verbatim from the draft, at least three words"
+              },
+              "why": {
+                "type": "string"
+              }
+            }
+          }
+        ],
+        "description": "null when the reader read to the end"
+      },
+      "would_take_next_step": {
+        "type": "boolean",
+        "description": "whether the reader would take next_step now"
+      },
+      "next_step": {
+        "type": "string",
+        "description": "what the reader would do next, in their own words"
+      }
+    }
+  }
+}

package/examples/writing/essay/learn/first-draft.md

@@ -0,0 +1,84 @@
+# Hand your first one-on-one to the person you manage
+
+## Who sets the agenda
+
+Your first one-on-one with a new report is the only meeting on your calendar where they should
+set the agenda. Everything else you run. This one you hand over.
+
+If you walk in with a list, you have told your report what the meeting is for, and it is for
+you. They will answer your list politely and leave. You will know nothing you did not know when
+you sat down, and so will they.
+
+My team ran a [survey](materials/team-survey.md) this spring. 29 of 41 people said their most useful one-on-one in the last
+quarter was one where they brought the first topic. The meeting that worked for them was the one
+they started.
+
+So give them the start. The simplest way to do it is a running agenda: one shared document per
+person, kept for as long as you manage them. Your report adds items before each meeting, and you
+add yours last, at the bottom. That is how an engineering manager I interviewed, eight years into
+the job, runs hers. Her rule is short: the report owns the agenda.
+
+## My first one-on-one
+
+My first one-on-one as a manager was a disaster, and the reason was simple: I ran it. I had a
+list, and I went down the list. Project status, blockers, the thing from Tuesday. Thirty minutes
+later my report said thanks and left, and I had learned nothing I could not have read in the
+tracker. Most new managers make the same mistake.
+
+What I ran was a status meeting, which is a meeting spent reading out loud what the tracker
+already says. Your report wrote those updates. Asking them to recite the updates to you teaches
+you nothing new, and it spends the one half hour a week that belongs to them.
+
+The survey show the cost from their side. 11 of 41 said at least one of their one-on-ones in the
+last quarter was mostly project status. Read the tracker before you walk in, and leave status
+there.
+
+My second manager used to walk our one-on-ones outside, and I liked it. A walk takes the table
+out of the room.
+
+## The three questions
+
+Here is what I ask now, in this order, and then I let the report take over:
+
+1. What is taking more of your energy than it should?
+2. What do you want to be doing more of in six months?
+3. What should I stop doing, or start doing, that would make your week easier?
+
+Three is enough to hand the meeting over. The first asks about this week. The second asks about
+the next six months. The third asks about you, and it is the one your report will not raise
+without being asked. A fourth question starts to look like your list again, and the list is what
+you came to give up.
+
+It can be helpful to consider asking the questions in the same words each time. This may help
+your report become familiar with them, and over time they might start to prepare their answers.
+
+The second question is the one my own team asked for. The most common free-text request in the
+survey, in 9 responses, was to be asked what they want to work on next.
+
+After the third question, stop talking.
+
+## What to do with the answers
+
+Wait after each question, longer than you want to. Dana, the engineering manager I interviewed,
+puts it in three short sentences: "Wait. Count to five. The real answer is the second one." The first
+answer your report gives is the tidy one, the version they could give anyone. The second is what
+they came in with, and you only hear it if you let the silence run.
+
+Write down what they say, in their words, at the top of the running agenda. That list is where
+your next one-on-one starts, so the meeting stays theirs the week after too.
+
+You might want to avoid trying to fix everything in the room. Pick one thing you can act on this week, say what you
+will do, and do it before you meet again. The rest stays on the running agenda until it is done
+or your report takes it off.
+
+And keep your own urgent items out of it. She told me: "If I have something urgent, it is not a
+one-on-one topic. I send it the day it happens." Your report should never have to wait a week to
+hear something you needed them to know on Monday.
+
+## Before the meeting
+
+Open the invite and delete your list from it. Ask your report to add the first item to the
+running agenda instead.
+
+So write the three questions on a card. Ask the first one. Then wait, longer than feels polite,
+because the first answer is the one they rehearsed and the second one is the one you came for.

package/examples/writing/essay/learn/learn.packet.json

@@ -0,0 +1,106 @@
+{
+  "hyperspec_learn": "0.1",
+  "spec": "essay.hyperspec.md",
+  "spec_sha256": "e03dfac6b445ae779000f7fc109a9d713df2e5cf8967faf8e808fe87d63e40e9",
+  "first": "essay/learn/first-draft.md",
+  "first_sha256": "08f039cd278093c81338f8880c4533ada741ecc33b0c6610ffbd98b8d31c0c62",
+  "approved": "essay/draft.md",
+  "approved_sha256": "aa4a1d99604f7b2b398b67305b368abbb72651356c38bfffad1452db6be62f65",
+  "blocks": [
+    "materials",
+    "dna",
+    "persona",
+    "audience",
+    "goal",
+    "form",
+    "spine",
+    "sources",
+    "none"
+  ],
+  "instructions": "Each hunk is one edit a person made between the first draft a factory produced (first) and the draft they approved (approved): deleted (only in first), inserted (only in approved) or replaced (first became approved). For every hunk, name the one block of the spec (read it at the spec path) that, had it said more or said it better, would have had the factory write the approved text in the first place: materials (the source material the text drew on), dna (the writer's voice: goldens and style rules), persona (who is speaking: stance, what they may assert, what they will not say), audience (the reader: what they know, the terms they use), goal (the change the draft must produce and its conditions), form (length and shape), spine (the claims and their order), sources (the claims ledger), characters (fiction: a character's speech or knowledge), or none when no block of the spec could have prevented it. A hunk never crosses a paragraph or a heading; its sentences field counts the sentences it touched. Name only a block listed in blocks. Answer only in the verdict shape given in verdict_schema: one entry per hunk id, each exactly once, with a why saying what the block should have said, or why no block could have.",
+  "hunks": [
+    {
+      "id": "E1",
+      "kind": "deleted",
+      "first": "Most new managers make the same mistake.",
+      "approved": null,
+      "sentences": 1
+    },
+    {
+      "id": "E2",
+      "kind": "replaced",
+      "first": "The survey show the cost from their side.",
+      "approved": "The survey shows the cost from their side.",
+      "sentences": 1
+    },
+    {
+      "id": "E3",
+      "kind": "deleted",
+      "first": "My second manager used to walk our one-on-ones outside, and I liked it. A walk takes the table\nout of the room.",
+      "approved": null,
+      "sentences": 2
+    },
+    {
+      "id": "E4",
+      "kind": "replaced",
+      "first": "It can be helpful to consider asking the questions in the same words each time. This may help\nyour report become familiar with them, and over time they might start to prepare their answers.",
+      "approved": "Ask them in the same words every time. Your report will learn them, and after a few weeks they\nwill walk in with answers already half formed. That is the point of fixing the words: the meeting\nstarts on their topic before you have said anything at all.",
+      "sentences": 3
+    },
+    {
+      "id": "E5",
+      "kind": "replaced",
+      "first": "You might want to avoid trying to fix everything in the room.",
+      "approved": "Do not try to fix everything in the room.",
+      "sentences": 1
+    }
+  ],
+  "verdict_schema": {
+    "type": "object",
+    "required": [
+      "edits"
+    ],
+    "properties": {
+      "edits": {
+        "type": "array",
+        "description": "one entry per hunk id, each exactly once",
+        "items": {
+          "type": "object",
+          "required": [
+            "id",
+            "block",
+            "why"
+          ],
+          "properties": {
+            "id": {
+              "enum": [
+                "E1",
+                "E2",
+                "E3",
+                "E4",
+                "E5"
+              ]
+            },
+            "block": {
+              "enum": [
+                "materials",
+                "dna",
+                "persona",
+                "audience",
+                "goal",
+                "form",
+                "spine",
+                "sources",
+                "none"
+              ]
+            },
+            "why": {
+              "type": "string",
+              "description": "what the block should have said to prevent this edit, or why no block could have"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/examples/writing/essay/sample-verdicts/doctor.verdict.json

@@ -0,0 +1,43 @@
+{
+  "sample": "A sample judgment for the worked example, filled in by hand to show what a verdict looks like and what judge record does with it. It is one reading of the packet, not a model run, and another judge may answer differently. hyperspec ignores this field.",
+  "conditions": [
+    {
+      "id": "r1",
+      "pass": true,
+      "evidence": "Your first one-on-one with a new report is the only meeting on your calendar where they should set the agenda.",
+      "note": "the first sentence says the report sets the agenda"
+    },
+    {
+      "id": "r2",
+      "pass": true,
+      "evidence": "What should I stop doing, or start doing, that would make your week easier?",
+      "note": "all three numbered questions read word for word as the voice memo has them"
+    },
+    {
+      "id": "r3",
+      "pass": true,
+      "evidence": "11 of 41 said at least one of their one-on-ones in the last quarter was mostly project status.",
+      "note": "each survey figure (29 of 41, 11 of 41, 9 responses) has a ledger line pointing at the survey summary, and matches it"
+    },
+    {
+      "id": "r4",
+      "pass": true,
+      "evidence": "Three is enough to hand the meeting over.",
+      "note": "the sections carry c1, c2, c3 and c4 in that order; the paragraphs on writing the answers down and keeping urgent items out serve c1, that the meeting stays the report's"
+    },
+    {
+      "id": "r5",
+      "pass": true,
+      "evidence": "Wait after each question, longer than you want to.",
+      "note": "it says to wait after each question, and why the second answer is the one worth having"
+    },
+    {
+      "id": "r6",
+      "pass": true,
+      "evidence": "Open the invite and delete your list from it.",
+      "note": "about 830 words, inside 700 to 1,100"
+    }
+  ],
+  "would_take_next_step": true,
+  "evidence": "So write the three questions on a card."
+}

package/examples/writing/essay/sample-verdicts/learn.verdict.json

@@ -0,0 +1,30 @@
+{
+  "sample": "A sample judgment for the worked example, filled in by hand to show what a learn verdict looks like and what learn record does with it. It is one reading of the packet, not a model run, and another judge may answer differently. hyperspec ignores this field.",
+  "edits": [
+    {
+      "id": "E1",
+      "block": "persona",
+      "why": "persona.will_not_say already rules out a claim about what most managers do, and the factory still wrote one, so the rule needs saying more plainly"
+    },
+    {
+      "id": "E2",
+      "block": "none",
+      "why": "a typo; no block of the spec governs spelling"
+    },
+    {
+      "id": "E3",
+      "block": "materials",
+      "why": "the paragraph retells the voice memo segment marked aside, which no spine claim cites; the marking held it back and the factory used it anyway"
+    },
+    {
+      "id": "E4",
+      "block": "dna",
+      "why": "no golden and no style rule shows advice given flat, so the factory hedged it (can be helpful, may, might); a golden that states a habit as an instruction, or a rule against hedged advice, would have prevented it"
+    },
+    {
+      "id": "E5",
+      "block": "dna",
+      "why": "the same hedge in one sentence: this writer gives instructions, and nothing in the scope says so"
+    }
+  ]
+}

package/examples/writing/essay/sample-verdicts/lineup.verdict.json

@@ -0,0 +1,6 @@
+{
+  "sample": "A sample judgment for the worked example, filled in by hand to show what a verdict looks like and what judge record does with it. It is one reading of the packet, not a model run, and another judge may answer differently. hyperspec ignores this field.",
+  "pick": "D",
+  "confidence": 0.6,
+  "reason": "D is the only passage that rests on a survey figure, and it opens by pointing at something outside itself (the survey); A, B and C each turn one claim into an instruction in the second person, with no numbers."
+}

package/examples/writing/essay/sample-verdicts/persona.verdict.json

@@ -0,0 +1,4 @@
+{
+  "sample": "A sample judgment for the worked example, filled in by hand to show what a verdict looks like and what judge record does with it. It is one reading of the packet, not a model run, and another judge may answer differently. hyperspec ignores this field.",
+  "breaks": []
+}

package/examples/writing/essay/sample-verdicts/reader.verdict.json

@@ -0,0 +1,7 @@
+{
+  "sample": "A sample judgment for the worked example, filled in by hand to show what a verdict looks like and what judge record does with it. It is one reading of the packet, not a model run, and another judge may answer differently. hyperspec ignores this field.",
+  "lost_at": [],
+  "stopped_at": null,
+  "would_take_next_step": true,
+  "next_step": "take my own list out of the invite, write the three questions on a card, and ask the first one in this week's meeting"
+}