@dxos/plugin-github 0.7.4 → 0.14.0

package/src/walkthrough/plan.test.ts

@@ -0,0 +1,178 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { parsePatch } from './patch.ts';
+import { assembleWalkthrough, buildChapterPrompt, buildPlannerPrompt, chapterDiff, parsePlan } from './plan.ts';
+
+const PATCH = [file('src/core.ts', 3), file('src/caller.ts', 2), file('pnpm-lock.yaml', 400)].join('\n');
+const FACTS = { owner: 'dxos', repo: 'dxos', number: 13288, title: 'A large change' };
+const PATHS = ['src/core.ts', 'src/caller.ts'];
+
+describe('buildPlannerPrompt', () => {
+  test('lists files and sizes, never their contents', () => {
+    const prompt = buildPlannerPrompt(FACTS, PATCH);
+
+    expect(prompt).to.contain('src/core.ts (+3/-0, 1 hunks)');
+    expect(prompt).to.not.contain('+line 0;');
+  });
+
+  test('leaves generated files out of the plan entirely', () => {
+    expect(buildPlannerPrompt(FACTS, PATCH)).to.not.contain('pnpm-lock.yaml');
+    expect(buildPlannerPrompt(FACTS, PATCH)).to.contain('Files changed (2)');
+  });
+});
+
+describe('parsePlan', () => {
+  const RESPONSE = JSON.stringify({
+    title: 'Evaluate queries in SQLite',
+    overview: 'A second executor, off by default.',
+    chapters: [
+      { title: 'The compiler', summary: 'Why a CTE per step.', files: ['src/core.ts'] },
+      { title: 'The call sites', files: ['src/caller.ts'] },
+    ],
+  });
+
+  test('reads a plan, fenced or bare', () => {
+    const plan = parsePlan(RESPONSE, PATHS);
+    expect(plan?.title).to.eq('Evaluate queries in SQLite');
+    expect(plan?.chapters.map((chapter) => chapter.title)).to.deep.eq(['The compiler', 'The call sites']);
+    expect(parsePlan('Here you go:\n```json\n' + RESPONSE + '\n```\n', PATHS)?.chapters).to.have.length(2);
+  });
+
+  test('drops a file the patch does not contain', () => {
+    const invented = JSON.stringify({
+      title: 'A change',
+      chapters: [{ title: 'One', files: ['src/core.ts', 'src/invented.ts'] }],
+    });
+    expect(parsePlan(invented, PATHS)?.chapters[0].files).to.deep.eq(['src/core.ts']);
+  });
+
+  test('gives a file to the first chapter that claims it', () => {
+    const duplicated = JSON.stringify({
+      title: 'A change',
+      chapters: [
+        { title: 'One', files: ['src/core.ts'] },
+        { title: 'Two', files: ['src/core.ts', 'src/caller.ts'] },
+      ],
+    });
+    const plan = parsePlan(duplicated, PATHS);
+    expect(plan?.chapters[0].files).to.deep.eq(['src/core.ts']);
+    expect(plan?.chapters[1].files).to.deep.eq(['src/caller.ts']);
+  });
+
+  test('sweeps up files the planner forgot, so the reader still meets them', () => {
+    const partial = JSON.stringify({ title: 'A change', chapters: [{ title: 'One', files: ['src/core.ts'] }] });
+    const plan = parsePlan(partial, PATHS);
+
+    expect(plan?.chapters).to.have.length(2);
+    expect(plan?.chapters[1]).to.deep.contain({ title: 'The rest of the change' });
+    expect(plan?.chapters[1].files).to.deep.eq(['src/caller.ts']);
+  });
+
+  test('drops a summary that is not a string, rather than carrying it into the next prompt', () => {
+    const malformed = JSON.stringify({
+      title: 'A change',
+      overview: { not: 'a string' },
+      chapters: [{ title: 'One', summary: { also: 'not a string' }, files: ['src/core.ts', 42] }],
+    });
+    const plan = parsePlan(malformed, PATHS);
+
+    expect(plan?.overview).to.eq('');
+    expect(plan?.chapters[0].summary).to.be.undefined;
+    expect(plan?.chapters[0].files).to.deep.eq(['src/core.ts']);
+    expect(buildChapterPrompt(plan!, plan!.chapters[0], 'diff')).to.not.contain('[object Object]');
+  });
+
+  test('reads a fenced plan whose JSON contains a fence-like sequence', () => {
+    const response = [
+      'Here is the plan:',
+      '```json',
+      JSON.stringify({
+        title: 'A change',
+        overview: 'Chapters are written as ```text blocks elsewhere.',
+        chapters: [{ title: 'One', files: ['src/core.ts'] }],
+      }),
+      '```',
+    ].join('\n');
+
+    expect(parsePlan(response, PATHS)?.chapters[0].title).to.eq('One');
+  });
+
+  test('refuses an unreadable answer rather than inventing a plan', () => {
+    expect(parsePlan('I cannot help with that.', PATHS)).to.be.undefined;
+    expect(parsePlan('{"title": "A change"}', PATHS)).to.be.undefined;
+    expect(parsePlan(JSON.stringify({ title: 'A', chapters: [{ title: 'B', files: ['gone.ts'] }] }), PATHS)).to.be
+      .undefined;
+  });
+});
+
+describe('chapterDiff', () => {
+  test('carries only the chapter’s own files', () => {
+    const files = parsePatch(PATCH);
+    const diff = chapterDiff(files, { title: 'The compiler', files: ['src/core.ts'] });
+
+    expect(diff).to.contain('src/core.ts');
+    expect(diff).to.not.contain('src/caller.ts');
+  });
+});
+
+describe('buildChapterPrompt', () => {
+  test('names the heading to write and the other chapters as context', () => {
+    const plan = parsePlan(
+      JSON.stringify({
+        title: 'A change',
+        overview: 'Why.',
+        chapters: [
+          { title: 'One', summary: 'Explain the core.', files: ['src/core.ts'] },
+          { title: 'Two', files: ['src/caller.ts'] },
+        ],
+      }),
+      PATHS,
+    )!;
+    const prompt = buildChapterPrompt(plan, plan.chapters[0], 'diff goes here');
+
+    expect(prompt).to.contain('Your chapter: ## One');
+    expect(prompt).to.contain('What it must explain: Explain the core.');
+    expect(prompt).to.contain('Other chapters, for context only: Two');
+    expect(prompt).to.contain('diff goes here');
+  });
+});
+
+describe('assembleWalkthrough', () => {
+  test('puts one H1 over the chapters the writers produced', () => {
+    const body = assembleWalkthrough({ title: 'A change', overview: 'Why it exists.', chapters: [] }, [
+      '## One\n\nFirst.\n',
+      '## Two\n\nSecond.\n',
+    ]);
+
+    expect(body.match(/^# /gm)).to.have.length(1);
+    expect(body).to.contain('# A change');
+    expect(body).to.contain('Why it exists.');
+    expect(body.indexOf('## One')).to.be.lessThan(body.indexOf('## Two'));
+    expect(body).to.not.contain('\n\n\n');
+  });
+
+  test('puts a blank line between one chapter and the next heading', () => {
+    const body = assembleWalkthrough({ title: 'A change', overview: 'Why it exists.', chapters: [] }, [
+      '## One\n\nFirst.',
+      '## Two\n\nSecond.',
+    ]);
+
+    expect(body).to.contain('First.\n\n## Two');
+  });
+});
+
+// A declaration rather than an arrow: the fixture above calls it at module evaluation.
+function file(path: string, lines: number): string {
+  return [
+    `diff --git a/${path} b/${path}`,
+    `--- a/${path}`,
+    `+++ b/${path}`,
+    `@@ -1,1 +1,${lines + 1} @@`,
+    ' keep();',
+    ...Array.from({ length: lines }, (_, index) => `+line ${index};`),
+  ].join('\n');
+}

package/src/walkthrough/plan.ts

@@ -0,0 +1,251 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { isGeneratedFile } from './generated.ts';
+import { spaceHeadings } from './headings.ts';
+import { type PatchFile, parsePatch } from './patch.ts';
+
+/**
+ * Two-stage generation for a pull request whose diff does not fit one prompt.
+ *
+ * One-shot generation over a trimmed diff fails in a specific way on a large change: the model
+ * writes the first two sections in full, then runs out of room and leaves the rest to the appended
+ * `## Also changed` section — so the bigger the pull request, the less of it the walkthrough
+ * actually covers. Here a planner sees only the file list and decides the chapters, then each
+ * chapter is narrated against its own files, and the chapters are concatenated.
+ */
+
+/** A chapter the planner assigned files to. */
+export type Chapter = {
+  title: string;
+  /** Paths from the file list, exactly as given. */
+  files: string[];
+  /** Why this chapter exists, handed to the chapter writer as its brief. */
+  summary?: string;
+};
+
+export type Plan = {
+  /** The H1 for the whole document. */
+  title: string;
+  /** Two or three sentences opening the document, before the first chapter. */
+  overview: string;
+  chapters: Chapter[];
+};
+
+/**
+ * Diffs longer than this get the two-stage treatment.
+ *
+ * Twice the one-shot budget: below that, trimming drops a file or two and the single prompt still
+ * sees the shape of the change, and a second model call would buy nothing.
+ */
+export const DEFAULT_CHAPTER_THRESHOLD_CHARS = 32_000;
+
+export const PLANNER_SYSTEM_PROMPT = [
+  'You plan the chapters of a walkthrough: the document that takes a reviewer through a pull',
+  'request in the order it is best understood.',
+  '',
+  'You see the files and their sizes, never their contents. Decide the ORDER a reviewer should meet',
+  'this change in, and which files belong together.',
+  '',
+  'Rules:',
+  '- The core of the change comes first. Mechanical consequences (call sites, tests, docs) come',
+  '  after the thing that forced them.',
+  '- A chapter is a reason, not a directory. Files that change for the same reason belong together',
+  '  however far apart they sit in the tree.',
+  '- Every file in the list belongs to exactly one chapter. Do not invent files.',
+  '- Between three and seven chapters. Fewer on a change with one idea, more on a change that',
+  '  genuinely does several things.',
+  '',
+  'Answer with JSON and nothing else:',
+  '{"title": "…", "overview": "…", "chapters": [{"title": "…", "summary": "…", "files": ["…"]}]}',
+  '',
+  '`title` is the H1 for the document: what the change does, in one line. `overview` is two or',
+  'three sentences on what it does and why, for the reader who has not seen the diff. Each',
+  "chapter's `summary` is one sentence telling that chapter's writer what to explain.",
+].join('\n');
+
+/** The file list the planner sees: path, size of change, and nothing else. */
+export const buildPlannerPrompt = (
+  facts: { owner: string; repo: string; number: number; title: string; description?: string },
+  diff: string,
+): string => {
+  const files = parsePatch(diff).filter((file) => !isGeneratedFile(file));
+  const lines = [`Repository: ${facts.owner}/${facts.repo}`, `Pull request: #${facts.number}`, `Title: ${facts.title}`];
+  if (facts.description?.trim()) {
+    lines.push('', 'Description as written by the author:', facts.description.trim());
+  }
+  lines.push('', `Files changed (${files.length}):`, '');
+  for (const file of files) {
+    lines.push(`${file.path} (+${file.added}/-${file.removed}, ${file.hunks.length} hunks)`);
+  }
+
+  return lines.join('\n');
+};
+
+/**
+ * Reads the planner's answer.
+ *
+ * Tolerant of a fenced block or surrounding prose, because a refusal to parse costs the whole run
+ * and the recovery — falling back to one-shot — is worse than reading a fence.
+ */
+export const parsePlan = (response: string, paths: readonly string[]): Plan | undefined => {
+  // A closer is its own line of at least as many backticks: a `​``text` sequence inside a JSON
+  // string would otherwise end the block early and leave `JSON.parse` a truncated payload.
+  const fenced = response.match(/^[ \t]*(`{3,})[^\n]*\n([\s\S]*?)^[ \t]*\1`*[ \t]*$/m);
+  const text = (fenced?.[2] ?? response).trim();
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start < 0 || end <= start) {
+    return undefined;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return undefined;
+  }
+
+  const decoded = decodePlan(parsed);
+  if (!decoded) {
+    return undefined;
+  }
+
+  const known = new Set(paths);
+  const claimed = new Set<string>();
+  const chapters: Chapter[] = [];
+  for (const chapter of decoded.chapters) {
+    // A path the patch does not contain, or one a previous chapter already took, would make a
+    // chapter prompt carrying no diff — an invented file is the planner's likeliest mistake.
+    const files = chapter.files.filter((path) => known.has(path) && !claimed.has(path));
+    for (const path of files) {
+      claimed.add(path);
+    }
+    if (files.length > 0) {
+      chapters.push({ title: chapter.title, files, summary: chapter.summary });
+    }
+  }
+  if (chapters.length === 0) {
+    return undefined;
+  }
+
+  // Files the planner forgot still have to reach the reader, and the last chapter is where the
+  // mechanical remainder belongs.
+  const unclaimed = paths.filter((path) => !claimed.has(path));
+  if (unclaimed.length > 0) {
+    chapters.push({ title: 'The rest of the change', files: [...unclaimed] });
+  }
+
+  return { title: decoded.title, overview: decoded.overview, chapters };
+};
+
+/** Fields of the shape the planner was asked for; anything else is dropped rather than carried. */
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+/**
+ * Reads the model's JSON into the typed shape, field by field.
+ *
+ * Every value is checked, `summary` included: a non-string there would reach `buildChapterPrompt`
+ * and be interpolated into the next prompt as `[object Object]`.
+ */
+const decodePlan = (value: unknown): (Omit<Plan, 'chapters'> & { chapters: Chapter[] }) | undefined => {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  if (!isString(record.title) || !Array.isArray(record.chapters)) {
+    return undefined;
+  }
+
+  const chapters = record.chapters.flatMap((entry): Chapter[] => {
+    if (typeof entry !== 'object' || entry === null) {
+      return [];
+    }
+    const chapter = entry as Record<string, unknown>;
+    if (!isString(chapter.title) || !Array.isArray(chapter.files)) {
+      return [];
+    }
+    return [
+      {
+        title: chapter.title,
+        files: chapter.files.filter(isString),
+        ...(isString(chapter.summary) ? { summary: chapter.summary } : {}),
+      },
+    ];
+  });
+
+  return { title: record.title, overview: isString(record.overview) ? record.overview : '', chapters };
+};
+
+/** The diff of one chapter's files, in patch order. */
+export const chapterDiff = (files: readonly PatchFile[], chapter: Chapter): string => {
+  const wanted = new Set(chapter.files);
+  return files
+    .filter((file) => wanted.has(file.path))
+    .map((file) => [...file.preamble, ...file.hunks.flatMap((hunk) => [hunk.header, ...hunk.lines])].join('\n'))
+    .join('\n');
+};
+
+export const CHAPTER_SYSTEM_PROMPT = [
+  'You write ONE chapter of a walkthrough of a pull request: the section a reviewer reads to',
+  'understand this part of the change.',
+  '',
+  'You are given the chapter you are writing, the document it belongs to, and the diff of this',
+  "chapter's files only. Other chapters cover the rest; do not describe them.",
+  '',
+  'Output:',
+  '- Open with the H2 heading you are given, exactly as given. No H1, no other H2.',
+  '- Under it, a short paragraph saying what this part does and what constraint it satisfies, then',
+  '  the code it refers to.',
+  '- Reference a change with an EMPTY fenced block, exactly like this, and nothing inside it:',
+  '',
+  '  ```diff file=path/to/file.ts lines=66-99',
+  '  ```',
+  '',
+  '- `file` is the path exactly as the diff gives it. `lines` is the range in the file AFTER the',
+  '  change, from the `@@` header. NEVER put diff content inside the fence: it is filled in for you',
+  '  from the real patch, and anything you write there is discarded.',
+  '- A mechanical change repeated across files is one point: fence the instance that shows the',
+  '  shape and say how many others take it.',
+  '- EVERY file listed in your chapter appears in at least one fence. A file whose hunks do not',
+  '  each earn a paragraph still gets one fence, grouped with the others that change for its reason.',
+  '',
+  'Write for a reviewer reading once. The sentence rule is the one that matters most:',
+  '- ONE IDEA PER SENTENCE, under thirty words. No semicolons joining two clauses, no dashes',
+  '  carrying a second thought, no sentence that needs a comma-separated list of parentheticals.',
+  '  Where you would write a long sentence, write two short ones.',
+  '- Name the mechanism, not the feeling. Prose explains WHY the change is the way it is: the',
+  '  constraint, the failure it avoids, the alternative rejected. Do not narrate what the diff shows.',
+  '- Active voice with the actor named. Plain words. Sentence case headings. No emoji.',
+  '- Output the markdown for this chapter and nothing else. No preamble, no closing summary.',
+].join('\n');
+
+export const buildChapterPrompt = (plan: Plan, chapter: Chapter, diff: string): string =>
+  [
+    `Document: ${plan.title}`,
+    plan.overview ? `Overview: ${plan.overview}` : '',
+    '',
+    `Your chapter: ## ${chapter.title}`,
+    chapter.summary ? `What it must explain: ${chapter.summary}` : '',
+    '',
+    `Other chapters, for context only: ${plan.chapters
+      .filter((other) => other.title !== chapter.title)
+      .map((other) => other.title)
+      .join('; ')}`,
+    '',
+    'Diff:',
+    '',
+    diff,
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+
+/** Stitches the planner's opening and the chapter bodies into one document. */
+export const assembleWalkthrough = (plan: Plan, chapters: string[]): string =>
+  spaceHeadings(
+    [`# ${plan.title}`, '', plan.overview, '', ...chapters.map((chapter) => chapter.trim())]
+      .filter((part, index) => part !== '' || index < 3)
+      .join('\n')
+      .replace(/\n{3,}/g, '\n\n'),
+  ).trimEnd() + '\n';

package/src/walkthrough/prompt.test.ts

@@ -0,0 +1,100 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { SYSTEM_PROMPT, buildPrompt, promptOmissions } from './prompt.ts';
+
+const INPUT = {
+  owner: 'dxos',
+  repo: 'dxos',
+  number: 13082,
+  title: 'A change',
+  description: 'Why it exists.',
+  baseBranch: 'main',
+  headBranch: 'feature',
+  diff: [file('src/small.ts', 2), file('src/large.ts', 400)].join('\n'),
+};
+
+describe('buildPrompt', () => {
+  test('states the change and appends the diff', () => {
+    const prompt = buildPrompt(INPUT);
+
+    expect(prompt).to.contain('Repository: dxos/dxos');
+    expect(prompt).to.contain('Pull request: #13082');
+    expect(prompt).to.contain('Title: A change');
+    expect(prompt).to.contain('Branch: feature into main');
+    expect(prompt).to.contain('Why it exists.');
+    expect(prompt).to.contain('diff --git a/src/small.ts');
+  });
+
+  test('omits the branch line when the pull request does not say', () => {
+    const { baseBranch, headBranch, ...rest } = INPUT;
+    expect(buildPrompt(rest)).to.not.contain('Branch:');
+  });
+
+  test('drops whole files to fit the budget, largest first', () => {
+    const prompt = buildPrompt(INPUT, { maxDiffChars: 200 });
+
+    expect(prompt).to.contain('src/small.ts');
+    expect(prompt).to.not.contain('+line 399;');
+    expect(prompt).to.contain('Omitted from the diff below for length');
+    expect(prompt).to.contain('src/large.ts');
+  });
+
+  test('drops a generated file even when everything fits', () => {
+    const withLock = {
+      ...INPUT,
+      diff: [INPUT.diff, file('pnpm-lock.yaml', 3), file('assets/logo.png', 1)].join('\n'),
+    };
+    const prompt = buildPrompt(withLock);
+
+    // A lockfile is the largest hunk in most pull requests and the one nobody reads, so it never
+    // competes with code for the budget.
+    expect(prompt).to.not.contain('diff --git a/pnpm-lock.yaml');
+    expect(prompt).to.contain('src/small.ts');
+    expect(prompt).to.contain('not yours to describe: pnpm-lock.yaml, assets/logo.png');
+    expect(promptOmissions(withLock)).to.deep.eq(['pnpm-lock.yaml', 'assets/logo.png']);
+  });
+
+  test('reports what the budget dropped', () => {
+    expect(promptOmissions(INPUT, { maxDiffChars: 200 })).to.deep.eq(['src/large.ts']);
+    expect(promptOmissions(INPUT)).to.deep.eq([]);
+  });
+
+  test('leaves a diff within budget untouched', () => {
+    const prompt = buildPrompt(INPUT);
+    expect(prompt).to.contain('+line 399;');
+    expect(prompt).to.not.contain('Omitted from the diff');
+  });
+});
+
+describe('SYSTEM_PROMPT', () => {
+  test('tells the model the fence is empty and filled for it', () => {
+    // The whole design rests on this instruction; a model that transcribes the diff produces an
+    // artefact that misquotes the change.
+    expect(SYSTEM_PROMPT).to.contain('```diff file=path/to/file.ts lines=66-99');
+    expect(SYSTEM_PROMPT).to.contain('NEVER put diff content');
+    expect(SYSTEM_PROMPT).to.contain('file AFTER the change');
+  });
+
+  test('asks for prose a reviewer can read once', () => {
+    // Review time is what the walkthrough exists to save; see `.agents/skills/readable-prose`.
+    expect(SYSTEM_PROMPT).to.contain('One idea per sentence');
+    expect(SYSTEM_PROMPT).to.contain('Name the mechanism, not the feeling');
+    expect(SYSTEM_PROMPT).to.contain('Sentence case headings');
+  });
+});
+
+// A declaration rather than an arrow: the fixture above calls it at module evaluation.
+function file(path: string, lines: number): string {
+  return [
+    `diff --git a/${path} b/${path}`,
+    `--- a/${path}`,
+    `+++ b/${path}`,
+    `@@ -1,1 +1,${lines + 1} @@`,
+    ' keep();',
+    ...Array.from({ length: lines }, (_, index) => `+line ${index};`),
+  ].join('\n');
+}

package/src/walkthrough/prompt.ts

@@ -0,0 +1,147 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { isGeneratedFile } from './generated.ts';
+import { parsePatch } from './patch.ts';
+
+/** What the model is told about the change. */
+export type WalkthroughInput = {
+  owner: string;
+  repo: string;
+  number: number;
+  title: string;
+  description?: string;
+  baseBranch?: string;
+  headBranch?: string;
+  /** The whole unified diff, as git wrote it. */
+  diff: string;
+};
+
+export type PromptOptions = {
+  /**
+   * Character budget for the diff. Files are dropped smallest-budget-first when it is exceeded;
+   * anything dropped still reaches the reader, because the postprocess appends every hunk the prose
+   * does not claim.
+   */
+  maxDiffChars?: number;
+};
+
+/**
+ * Measured against Sonnet, whose 16k output budget covers reasoning AND the answer. A whole
+ * 75k-character diff is ~33k input tokens, and the model then spends the entire output budget
+ * reasoning: the response comes back `finishReason: 'length'` carrying a reasoning block and NO
+ * text at all. At ~19k characters the same request answers in full with room to spare.
+ *
+ * Trimming costs nothing a reader sees, because every hunk the prose does not claim is appended
+ * verbatim by {@link fillWalkthrough}.
+ */
+const DEFAULT_MAX_DIFF_CHARS = 16_000;
+
+/**
+ * What the model is for: the ORDER and the REASONS, never the diff content.
+ *
+ * Every chunk is emitted as an empty fence carrying a path and a line range, which a postprocess
+ * fills from the patch itself. A model asked to transcribe a diff gets lines subtly wrong, and a
+ * review artefact that misquotes the change is worse than no artefact.
+ */
+export const SYSTEM_PROMPT = [
+  'You write walkthroughs of pull requests: one markdown document that takes a reviewer through a',
+  'change in the order it is best understood, rather than in the order the files happen to sort.',
+  '',
+  'Structure:',
+  '- Open with an H1 naming the change, then two or three sentences on what it does and why.',
+  '- Group the change into sections with H2 headings, ordered so each one builds on the last.',
+  '  Put the core of the change first and the mechanical consequences after it.',
+  '- Under a heading, write a short paragraph saying what this part does and what constraint it',
+  '  satisfies, then show the code it refers to.',
+  '',
+  'Showing code — this is the part to get right:',
+  '- Reference a change with an EMPTY fenced block, exactly like this, and nothing inside it:',
+  '',
+  '  ```diff file=path/to/file.ts lines=66-99',
+  '  ```',
+  '',
+  '- `file` is the path exactly as the diff gives it, after the change. `lines` is the range in the',
+  '  file AFTER the change, taken from the `@@` header. Omit `lines` to show the whole file.',
+  '- NEVER put diff content, code, `@@` headers or `+`/`-` lines inside the fence. It is filled in',
+  '  for you from the real patch. Anything you write there is discarded.',
+  '- One fence per point being made. Several fences under one heading is normal.',
+  '',
+  'Style:',
+  '- Prose explains WHY the change is the way it is: the constraint, the failure it avoids, the',
+  '  alternative that was rejected. Do not narrate what the diff already shows.',
+  '- Do not describe every file. Cover what a reviewer must understand; the rest is appended for',
+  '  you under a separate heading.',
+  '- No preamble, no "this PR", no closing summary. Output the markdown document and nothing else.',
+  '',
+  'Write for a reviewer reading once:',
+  '- One idea per sentence. Past thirty words, split it. The reader must never backtrack to parse.',
+  '- Name the mechanism, not the feeling: "the second attempt runs on a warmed socket", never',
+  '  "this makes the call more robust". A sentence that would fit another project unchanged says',
+  '  nothing about this one. Cut it.',
+  '- Active voice with the actor named: "the compiler validates queries", not "queries are validated".',
+  '- Plain words. Never: additionally, crucial, delve, enhance, leverage, pivotal, robust, seamless,',
+  '  showcase, testament, underscore, utilize. Say "is" rather than "serves as" or "stands as".',
+  '- Sentence case headings. No emoji. No bold label that restates the line it introduces.',
+  '- End a sentence or use a comma rather than an em dash.',
+].join('\n');
+
+/** Trims the patch to the budget, keeping as many files as fit and naming what was left out. */
+const budgetDiff = (diff: string, maxChars: number): { diff: string; omitted: string[] } => {
+  const parsed = parsePatch(diff);
+  const generated = parsed.filter((file) => isGeneratedFile(file)).map((file) => file.path);
+  const files = parsed
+    // Generated files go first, whatever the budget: a lockfile is the largest thing in most pull
+    // requests and the one the reader skips, so it would otherwise push out code that matters.
+    .filter((file) => !isGeneratedFile(file))
+    .map((file) => ({
+      path: file.path,
+      text: [...file.preamble, ...file.hunks.flatMap((hunk) => [hunk.header, ...hunk.lines])].join('\n'),
+    }));
+  const withoutGenerated = files.map((file) => file.text).join('\n');
+  if (withoutGenerated.length <= maxChars) {
+    return { diff: generated.length > 0 ? withoutGenerated : diff, omitted: generated };
+  }
+
+  const order = [...files].sort((left, right) => left.text.length - right.text.length);
+  const kept = new Set<string>();
+  let used = 0;
+  for (const file of order) {
+    if (used + file.text.length > maxChars) {
+      continue;
+    }
+    used += file.text.length + 1;
+    kept.add(file.path);
+  }
+
+  return {
+    diff: files
+      .filter((file) => kept.has(file.path))
+      .map((file) => file.text)
+      .join('\n'),
+    omitted: [...generated, ...files.filter((file) => !kept.has(file.path)).map((file) => file.path)],
+  };
+};
+
+/** The user-side content: what the change is, followed by the diff the fences will be filled from. */
+export const buildPrompt = (input: WalkthroughInput, options: PromptOptions = {}): string => {
+  const { diff, omitted } = budgetDiff(input.diff, options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS);
+  const lines = [`Repository: ${input.owner}/${input.repo}`, `Pull request: #${input.number}`, `Title: ${input.title}`];
+  if (input.headBranch && input.baseBranch) {
+    lines.push(`Branch: ${input.headBranch} into ${input.baseBranch}`);
+  }
+  if (input.description?.trim()) {
+    lines.push('', 'Description as written by the author:', input.description.trim());
+  }
+  if (omitted.length > 0) {
+    lines.push('', `Omitted from the diff below for length, and not yours to describe: ${omitted.join(', ')}.`);
+  }
+  lines.push('', 'Diff:', '', diff);
+
+  return lines.join('\n');
+};
+
+/** Chunks the model cannot have claimed, because the diff never showed them. */
+export const promptOmissions = (input: WalkthroughInput, options: PromptOptions = {}): string[] =>
+  budgetDiff(input.diff, options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS).omitted;