progress-sync

# Progress Sync Compress a work log into one page that a reader outside the work can absorb in a few minutes. ## When to use A recurring or one-off update addressed to someone who is not doing the work: weekly team update, advisor meeting, board or investor note, client status, grant milestone, incident write-up. **Not for** manuscripts or scholarly prose — use `academic-humanizer`. Not for meeting minutes, task tracking, or standups. Not for anything where the reader needs the full record; this produces a view of the log, never a replacement for it. ## Core principle Most updates fail because everything is written at the same weight, so the reader does the ranking. Rank it for them. Every item becomes **one claim the reader can act on**, with its evidence in small print underneath. Reading only the bold lines must give the whole update. --- ## Step 1 — Ask before rendering Ask once, five fields, all skippable except purpose: > Purpose (research progress, product progress, decision request, investor update, …)? > Who is reporting — name, role, or skip? Who is it for — name, role, or skip? > Period to show? Output language? > Anything you skip is left off the page rather than filled in. **Language defaults to English**, whatever language the source log is in. Produce another language only when the user asks for one, or says to match the source. Set `lang` on `<html>` to match, so the measure rules in Step 6 apply correctly. Every label on the page — the kicker, the byline slots, the closing-block heading — renders in the output language, not the source's. **Absent means absent.** A field not supplied is omitted from the header entirely — no empty label, no "TBD", no placeholder name. A role ("后端组", "the modeling team") is always acceptable in place of a person, and is safer for a document that may be forwarded. Never invent a name, title, recipient, or date. Date defaults to today. ### Purpose — what the claims must answer | Purpose | The claims answer | |---|---| | Research progress | What do we now know that we did not last time? | | Product progress | What shipped, what is next, what changed for the user? | | Engineering / delivery status | What is built, what slipped, what is the critical path? | | Experiment or results report | What did the run show, and how far does it support the claim? | | Decision request | What choice is needed, what are the options, what does each cost? | | Proposal / kickoff | What are we asking to start, why now, what does it need? | | Milestone or grant report | Against what was promised, what was delivered? | | Investor or board update | What moved against plan, and what does it imply? | | Client or customer status | What was delivered, what is outstanding, does the date hold? | | Incident postmortem | What broke, what was the impact, what stops a repeat? | | Risk / blocker escalation | What is stuck, what does it cost, who can unstick it? | | Market or competitive scan | What changed outside, and what should we do differently? | Free text is allowed for anything else (compliance status, handover, closeout). ### Recipient — register, never facts | Recipient | Leads with | Method detail | Jargon | |---|---|---|---| | Advisor / PI | the technical finding and what it revises | high | field terms fine | | Peer collaborator | what changed on the shared interface | high | shared vocabulary assumed | | Manager / team lead | what moved, what slipped, who is blocked | medium | gloss outside the team's daily use | | Director / skip-level | outcomes against plan, decisions needed | low | gloss all | | CEO / executive | the decision, its cost, risk of deferring | minimal | none unglossed | | Investor / board | movement since last update and its implication | minimal | none; plain numbers | | Client / customer | delivered, outstanding, whether the date holds | low, framed as impact on them | none; no internal system names | | Funder / program officer | deliverables against the proposal | medium, tied to milestones | glossed, in the proposal's terms | | Regulator / auditor | what is in place and the evidence | high, traceability first | precise and defined | Default when unknown: **manager**, gloss everything. It survives forwarding best. **The register changes; the facts do not.** If two versions of the same update would disagree about whether something is going wrong, that is spin. Do not produce it. --- ## Step 2 — Rank Order by what the recipient must know, not by chronology: 1. anything blocked, slipped, or failed 2. anything that changed a decision or invalidated a prior belief 3. what advanced 4. what is merely in progress — usually cut Four to six items is the working range. More than six means the ranking has not been done. ## Step 3 — Compress each item to a claim plus evidence The **claim** is one sentence, bold, stating something actionable or falsifiable. Write "being unable to fix is itself a signal", not "how we handle repair failures". Write "the detector finds 70% of them, up from 45%", not "detector performance improved". The **evidence** is 1–3 sentences in small print: the number, the mechanism, the counterexample, the tradeoff. It must support the claim above it and nothing else. Never state a number without saying what it means. "35%" is not a finding; "it gets the disease wrong two times in three, which is the only part that matters clinically" is. ## Step 4 — Clean the prose Two passes, both adapted from `academic-humanizer` (MIT; see README): **Strip AI tells.** Inflated significance ("marks a pivotal moment"); "-ing" tails that fake depth ("…, highlighting the importance of"); promotional adjectives (rich, robust, seamless, comprehensive); AI vocabulary (delve, underscore, leverage as filler, landscape, realm, testament); vague attribution ("studies show"); rule-of-three padding; copula avoidance ("serves as" → "is"); em-dash overuse. **No verb stronger than its evidence.** `prove` → `show`; `demonstrates that X is superior` → `on these three cases, X matches or beats Y`. Prefer ranges over averaged point values. **Gloss every term the reader may not know, inline, on first use** — in the sentence, not a footnote or glossary. Write "p95 latency (the speed all but the slowest 5% of requests beat)", not "p95". How aggressively to gloss depends on the recipient row above. ## Step 5 — The closing block Every page ends with one tinted block holding the single most important thing the reader should take away. **Its type follows what the thing actually is** — do not dress an observation up as a decision. Framing a heads-up as a decision misleads the reader about what is being asked of them, and teaches them to discount the block. | Type | Use when | Heading (EN / ZH) | |---|---|---| | Decision needed | a choice only the reader can make, and work is blocked until they make it | Decision needed from you / 本次请您决定 | | Confirmation needed | you have already decided and need sign-off, not deliberation | Confirmation needed / 请您确认 | | For discussion | there is no single answer yet and you want their thinking | For discussion / 本次想与您讨论 | | Help needed | a specific unblock — an introduction, access, budget, a person's time | Where we need help / 需要您协助 | | To watch | nothing to do now, but it will matter if it continues | Worth watching / 需要留意 | | Risk notice | you are flagging exposure the reader owns, not asking for anything | Heads-up on risk / 风险提示 | | Nothing needed | genuinely nothing is required this period | Nothing needed this period / 本期无需您处理 | Pick by semantics, not by habit. If the source log ends with "question for leadership: do we pay or delay", that is **Decision needed**. If it ends with "Acme hasn't logged in since the 18th", that is **To watch**. If it ends with "we think the chunking caused it but cannot separate the two changes", that is **For discussion**. "Nothing needed this period" is a real and useful outcome. Say it plainly rather than inventing a question so the block has something in it. Whatever the type, the block carries three things: the item itself, why it matters to this reader, and what — if anything — is wanted from them. One item only. Remaining questions stay in the source log; say so if the user asks, but do not list them on the page. ## Step 6 — Render and verify Copy `assets/template.html`, fill it, then: ```bash bash scripts/render.sh <filled.html> <out.pdf> ``` It prints the page count. **If it is more than 1, cut detail from step 3 — never a blocker, never the decision block.** Re-render until it reports 1. Then show the user the PDF path and open it. Before cutting text, check the measure. The template's default line length is set for Latin script; the `:lang(zh)` and `:lang(ja)` rules narrow it for CJK, which sets roughly one em per character. Set the `lang` attribute on `<html>` correctly — a Latin document rendered with the CJK measure wastes about a third of the page width and will overflow for layout reasons rather than content reasons. If page one is more than about a fifth empty, the page is underfull: restore the detail you cut, or put back an item that was ranked out. An underfull page means the ranking was too aggressive. --- ## Never drop - a blocker, a slip, a failed attempt, or a negative result - an unresolved disagreement - a number that contradicts the headline claim If the page will not close, the detail goes, not the bad news. ## Never invent No finding, number, date, name, or next step that is not in the source log. If the log is thin, produce a shorter page and say what is missing. ## Output The filled HTML, the PDF, the page count, and one line naming what was cut to make it fit.