Tighten survey and chat-history Typst templates

skills/dump-chat-history/SKILL.md

@@ -132,7 +132,11 @@ typst compile report.typ report.pdf
 
 The template uses A4, quiet phase bands, serif prose, sans-serif headings, and
 monospaced original text, with portable font fallbacks. It permits long messages
-to continue across pages. Add phases and concise annotations when useful; do not
+to continue across pages. Front matter is short: title, optional subtitle, and
+one date line, so the first prompt appears on the first page; scope, coverage,
+and sources sit at the end. Change fonts with `--input heading-font="..."` and
+`--input body-font="..."`; pass `Libertinus Serif` for both to build with only
+Typst's bundled fonts. Add phases and concise annotations when useful; do not
 force a fixed page count, prompt ranking, productivity ratio, or research taxonomy.
 Ground outcome claims in the adjacent conversation or verifiable artifacts;
 distinguish reported historical checks from checks performed now.

skills/dump-chat-history/assets/report.typ

@@ -1,7 +1,9 @@
 // Copy beside history.json; compile with: typst compile report.typ report.pdf
+// Optional: --input heading-font="..." --input body-font="..." (installed fonts;
+// pass "Libertinus Serif" for both to build with only Typst's bundled fonts)
 #let report = json("history.json")
-#let sans = ("Avenir Next", "Libertinus Serif")
-#let serif = ("Charter", "Libertinus Serif")
+#let sans = (sys.inputs.at("heading-font", default: "Avenir Next"), "Libertinus Serif")
+#let serif = (sys.inputs.at("body-font", default: "Charter"), "Libertinus Serif")
 #let mono = "DejaVu Sans Mono"
 #let ink = rgb("24282b")
 #let muted = rgb("63707b")
@@ -10,7 +12,7 @@
 #set document(title: report.title, description: "Conversation history field note")
 #set page(paper: "a4", margin: (x: 23mm, y: 20mm), footer: context {
   set text(font: sans, size: 8pt, fill: muted)
-  [#report.title #h(1fr) #counter(page).display()]
+  grid(columns: (1fr, auto), gutter: 12pt, report.title, counter(page).display())
 })
 #set text(font: serif, size: 10pt, fill: ink)
 #set par(leading: 0.45em, spacing: 0.7em)
@@ -19,27 +21,26 @@
 #show raw: set text(font: mono, size: 8.7pt, hyphenate: false, ligatures: false)
 #show raw.where(block: true): set block(width: 100%, fill: rgb("f2f3f4"), inset: 7pt, radius: 2pt, breakable: true)
 
-#text(font: sans, size: 8pt, tracking: 1pt, fill: rust)[CONVERSATION FIELD NOTE]
-#v(7pt)
-// The topic is the title. Counts belong in metadata, never the headline.
-#text(font: sans, size: 27pt, weight: "bold", report.title)
-#v(7pt)
-#text(size: 12pt, report.at("subtitle", default: ""))
-#v(8pt)
-#text(font: sans, size: 9pt, fill: muted)[
-  #report.window.start – #report.window.end · #report.window.timezone
+// Short front matter: the transcript starts on the first page. Scope, coverage,
+// and sources sit at the end. The topic is the title; counts never are.
+#block(breakable: false, below: 10pt)[
+  #text(font: sans, size: 20pt, weight: "bold", report.title)
+  #if report.at("subtitle", default: "") != "" [
+    #v(4pt)
+    #text(size: 11pt, report.subtitle)
+  ]
+  #v(4pt)
+  #text(font: sans, size: 8.5pt, fill: muted)[
+    #report.window.start – #report.window.end · #report.window.timezone
+  ]
 ]
-#v(5pt)
-#report.scope
-#v(5pt)
-#report.coverage
 
-= Transcript
 #let visible = report.entries.filter(e => e.at("include_in_report", default: e.role == "user"))
 #for entry in visible {
   let phase = entry.at("phase", default: none)
   if phase != none {
-    block(width: 100%, fill: rgb("f6f3ef"), radius: 3pt, inset: 10pt, breakable: false)[
+    // sticky keeps the phase label with the message that follows it.
+    block(width: 100%, fill: rgb("f6f3ef"), radius: 3pt, inset: 10pt, sticky: true, above: 12pt)[
       #text(font: sans, weight: "semibold", phase)
     ]
   }
@@ -73,8 +74,11 @@
 ]
 
 = Sources and limits
+#report.scope
+
+#report.coverage
 #for source in report.sources [
-  #block(breakable: true, above: 5pt)[
+  #block(breakable: true, above: 9pt)[
     #text(font: sans, size: 9pt, weight: "semibold", source.id)
     #linebreak()
     #raw(source.location, block: true)

skills/how-to-write-ideas-report/references/typst-reference.md

@@ -10,9 +10,18 @@ Reference files: ~/Documents/private-note/notes/typst-learn/ (typst-tricks.typ,
 
 ### Page Setup
 - Standalone figures: `#set page(width: auto, height: auto, margin: 5pt)`
-- Standard notes: `#set page(margin: 2cm)` + `#set text(size: 10pt)` + `#set heading(numbering: "1.1.")`
+- Reports: A4, 18 mm margins, 10 pt justified body text, 0.55 em leading, and a short running footer with the page number. Use the survey template as a working example.
 - Numbered equations: `#set math.equation(numbering: "(1)")`
 
+### Report hierarchy and legibility
+- Give the document title its own text block, not a numbered heading. Use about 18–20 pt for the title, 13–14 pt for sections, and 11 pt for subsections. No kicker line or decorative front matter: the first content paragraph belongs on the first page.
+- Use serif body text and a consistent sans-serif heading font. The report templates accept `--input heading-font="Your installed font"` (the chat-history template also `body-font`); `Libertinus Serif` works without system fonts. Do not shrink body text below 10 pt to meet a page count.
+- Justify body prose; keep table cells ragged right so narrow columns keep natural word spacing. Use at least 9 pt for tables and captions, and 8 pt for supporting metadata.
+- Reserve one dark accent and a light tint for navigation and brief assessments. Name categories and priorities explicitly so they remain readable in grayscale.
+- Use horizontal table rules, brief cells, and `table.header(repeat: true, ...)`. Keep long tables outside unbreakable figures or boxes. Match column widths to actual content, including the longest header and priority label.
+- Use `block(breakable: true, ...)` for long callouts and transcript entries. Keep a short label with its following content using `block(sticky: true, ...)`.
+- Inspect rendered pages with realistic paragraphs, long titles, source paths, and a table or message that crosses a page. Check that annotations cannot be mistaken for quoted text.
+
 ### Common Packages
 - CeTZ: `@preview/cetz:0.4.0`, `@preview/cetz-plot:0.1.2`
 - Algorithms: `@preview/algorithmic:1.0.3` — `Function`, `For`, `While`, `If`, `ElseIf`, `Else`, `Assign`, `Return`, `Comment`
@@ -39,7 +48,7 @@ Reference files: ~/Documents/private-note/notes/typst-learn/ (typst-tricks.typ,
 - `dict.at(key, default: 0)` — dict with default
 
 ### Content Helpers
-- Infobox: `rect(stroke: color, inset: 8pt, radius: 4pt, width: 100%, [*Title:*\ body])`
+- Short assessment: `block(stroke: (left: 2pt + color), inset: 10pt, width: 100%, breakable: true, body)`
 - Inline image alignment: `box(image(...), baseline: (size - 20pt) / 2 + offset)`
 - Image clipping: `box(clip: true, img, inset: (top: -top, bottom: -bottom, ...))`
 - Two columns: `grid(columns: (1fr, 1fr), gutter: 20pt, left, right)`

skills/survey/SKILL.md

@@ -78,7 +78,10 @@ Follow `skills/how-to-technical-writing/SKILL.md` for sentence- and paragraph-le
 - Check `CLAUDE.md`/`AGENTS.md` for a deliverables-location convention before choosing an output path.
 - Tailor technical depth to the user's role from `docs/discussion/user-profile.md` or available context.
 - Save to `articles/YYYY-MM-DD-<topic>-review.{md,typ,tex}` or a project-specific path if the user prefers.
-- For Typst, start from `skills/survey/template.typ` with `skills/survey/template.bib`. The scaffold provides `section_box`, `stage`, `proscons`, `compare_table`, and `problem_table`; delete unused helpers from the copied document.
+- For Typst, start from `skills/survey/template.typ` with `skills/survey/template.bib`. The scaffold provides `stage`, `proscons`, `compare_table`, and `problem_table`; delete unused helpers from the copied document.
+- Put only the review date beneath the title. Open with the single **Overview** described below, and end the body with **Open Problems**, followed by references. Do not add a separate scope block, assessment box, or closing "Next step" section.
+- Keep the template's dense, restrained layout: a plain title line, 10 pt justified body text, one accent color, and horizontal table rules. `compare_table` and `problem_table` accept custom `headers` and `columns`; choose them together, since a count mismatch fails the compile with a message. Write urgency labels as text. Keep long tables in the page flow so headers repeat across pages, and inspect the rendered result with realistic cell text.
+- The heading font can be changed with `--input heading-font="Your installed font"`. For a build using only Typst's bundled fonts, use `--input heading-font="Libertinus Serif"`.
 
 ### Gap-filling focus
 
@@ -93,17 +96,26 @@ When the source set comes from an existing, recent `NOTES.md` (the normal case),
 
 Organize the review **by technical approach**. State of the art and trade-offs live inside each approach, not in separate global sections. Do not add standalone global "Pros and Cons" or "State of the Art" sections.
 
-#### 1. What and Why
+#### 1. Overview
 
-Define the topic in 2–3 paragraphs for a new reader:
+Write two connected paragraphs for a new reader, without inline labels:
 
-- What it is and what problem it solves
-- Why it matters now
-- How it differs from the dominant or prior approach
+- Define the topic and problem, explain why it matters, and state the report's scope and intended audience. Distinguish it from the prior approach where that helps define the topic.
+- State the principal finding and its supporting evidence, then identify the unresolved constraint that motivates the key questions below. Cite the claims.
 
 Include a diagram only when it clarifies the architecture, data flow, or problem framing. Lay approaches side by side only when they solve the same task and are genuinely comparable; otherwise show their relationship or omit the figure.
 
-#### 2. Technical Approaches
+#### 2. Key Questions
+
+Give one subsection to each subtopic or open question the field is trying to settle (typically 2–5). For each, cover:
+
+- **The question** — one sentence, stated as a question.
+- **Why it matters** — what answering it gives: deeper understanding (what it would settle or unify) and/or practical value (what it would enable). Say which applies; a question with neither does not belong in the review.
+- **Where it stands** — the best partial answer and its limits, cited.
+
+Questions are ends, not means: do not give them strengths and limitations.
+
+#### 3. Technical Approaches
 
 Identify the main method families (typically 3–6) and give one subsection per approach. Optionally begin with a short field-wide timeline or landscape.
 
@@ -115,13 +127,13 @@ For each approach, cover:
 
 Optionally finish with a cross-approach comparison table when several approaches share meaningful criteria. Choose columns that actually discriminate this field (for example scalability, verifiability/cost, maturity, and best-fit use case). Skip it for a single-approach topic.
 
-#### 3. Open Problems
+#### 4. Open Problems
 
 End with a ranked table of 4–8 problems: number, problem, why it matters, who could solve it, and urgency (Critical / High / Medium). Cite the work that defines each gap or the closest existing result. Do not add business strategy, product fit, or investor sections to the neutral report.
 
 ### Visualization guidelines
 
-- Typst: use CeTZ for timelines and dependency diagrams; use native `grid`, `rect`, and fixed-width `box()` for text-heavy comparisons and role diagrams. See `skills/how-to-write-ideas-report/references/typst-reference.md`.
+- Typst: use CeTZ for timelines and dependency diagrams; use native `grid`, `block`, and fixed-width `box()` for text-heavy comparisons and role diagrams. See `skills/how-to-write-ideas-report/references/typst-reference.md`.
 - Use a native table for cross-approach comparisons.
 - Wrap multiline CeTZ content in a fixed-width box and use string identifiers for `name:`.
 - Compile after each figure; every claim in technical and open-problem tables needs at least one citation.