Skip to main content

​
ISSUE-FORMAT — the digest issue filed by docs-sync

One issue per audit run, on mnfst/docs, label docs-sync plus one label per finding category present. No findings = no issue = no noise.

​
Title

Docs audit — <date> (PRs #<from>–#<to>)

​
Body structure

Categories: OBSOLETE · INTERNAL-LEAK · WRONG · MISSING-CASE · IMAGE. IMAGE findings have no options; they say where the image goes, what it must show, and why that spot (Seb produces the images elsewhere).

​
Iron rules

  • Every finding carries BOTH sides of the evidence (doc sentence + code/PR reference). A finding without verifiable evidence does not ship.
  • Options, never decisions. The agent may recommend (“option 2 recommended because…”) but never presents a single path.
  • Findings previously rejected by Seb (see memory) are not re-raised unless the platform changed again on that exact point — then the finding says so explicitly.

​
Language rule (added after run 1, hardened after Seb’s feedback)

The issue is read by a HUMAN first, agents second. This is a TEMPLATE: every agent, whatever the harness or machine, copies the skeleton below verbatim and fills the blanks. No reordering, no omissions, no extra sections.
Element by element:
  1. One plain sentence stating the problem (“An image of the Settings page showing the Enable logs switch is missing”). Eight words beat three bullet lists. No UI-component jargon, no file names, no code references in this sentence. An optional second sentence may add ONE fact that changes how Seb decides; never restate the first sentence.
  2. Page (visible): the LIVE docs URL where the problem sits (https://manifest.build/docs/<slug>), with the section named in words (“First request, the Send a request step”). Seb opens it and sees the problem. The file path stays in the details block.
  3. What actually happens (visible, not folded): the user journey as established from the code, 2 to 6 numbered steps, pure user language (screens, fields, buttons, what the user sees and does). No file names, no code words. This block lets Seb verify the behavior from his own knowledge of the product BEFORE judging the options, and it is the basis of the future fix’s wording. Every step must be backed by a code reference in the details block.
  4. Fix or Options. One obvious fix → a single Fix: line. A real choice → Options:, each ONE line, each a genuinely different outcome. An option must never restate the problem, describe context, or say what the doc “already does” (that is evidence). Mark the recommendation with the word “Recommended.” at the end of its line, once, without repeating why beyond a parenthesis.
  5. All evidence (doc quotes, file:line, PR numbers, rationale) goes in a collapsed block the human can ignore: <details><summary>Evidence (for the agent)</summary>...</details> When the behavior can be reproduced with one cheap API request (a harness key is available on Seb’s machines and the VM), DO it and put the request + verbatim response in the evidence: reproduction beats code citation.
Voice: see the self-contained “Voice” section below. It applies to every finding. An IMAGE finding is ONLY the plain sentence plus the details block: no options, no rationale paragraph. If Seb cannot know what to do after reading one sentence, the finding fails the format.

​
Language of publication (absolute rule)

Everything published on GitHub — issue titles, bodies, comments, labels, PR descriptions — is written in ENGLISH, always. mnfst/docs is a public repo with an international audience. French is for the private conversation with Seb only. An issue drafted in French fails verification.

​
Voice (self-contained — do not depend on any external skill)

  • Short sentences. Direct. Like a senior engineer writing a bug report.
  • No em dashes. Use colons, commas, or periods.
  • No filler words: robust, comprehensive, leverage, utilize, enhance, streamline, seamlessly, facilitate.
  • Exact quotes, exact error codes, exact paths. Never paraphrase a quote.
  • Every sentence carries new information. If a sentence repeats the title or another sentence, delete it.

​
Canonical example (imitate this shape exactly)

Why this example is right: the title states the false claim and the truth in one line; the journey lets Seb verify the behavior himself in four user-language steps; the options are two different outcomes, one line each; the recommendation is one word; everything else is folded.