repo-standard/docs/presentation-research-2026-08-03.md

Presentation research — what "professional" can and cannot be measured as

Date: 2026-08-03 · Status: research complete, architecture decision open Method: adversarial deep research (107 agents, 25 sources fetched, 124 claims extracted, 25 verified, 11 confirmed / 14 refuted) + direct measurement of the 18 locally-cloned open/ repos + live verification against the operator's own Forgejo instance.

The headline is uncomfortable and load-bearing: most of what people call "professional presentation" has no evidence base as a requirement. Half the research question returned nothing that survived adversarial verification. That result constrains what this plugin may honestly check.

---

1. Measured: the org as it stands

18 of the 19 registered open/ repos (.profile is not cloned locally).

Dimension	Measurement
Real images	0. Every ![...] in all 18 READMEs resolves to a badge.
Mermaid diagrams	3 blocks total — voyage 2, llm-security 1, graceful-handoff 1.
README length	1,239 → 8,725 words. 7× spread.
H2 sections	5 → 26. Nine repos sit above the empirical IQR ceiling of 12.
Badges	0 → 8. Six repos carry 7–8.
Language	ms-ai-architect ships Norwegian body prose and a Norwegian changelog table; okr ships a Norwegian changelog table. Both are public.
Heading casing	Mixed within one file in 5/18 — "What Is This?" beside "What it does".
First H2	Install in 15/18. The org's strongest existing coherence signal.

linkedin-studio was flagged by the crude language heuristic and cleared on inspection — a false positive, discarded before it reached this table.

2. Confirmed by the evidence

Peer-reviewed, adversarially survived. Every number here is descriptive of what typical repos do, not prescriptive of what an excellent repo should do. Inverting them into requirements contradicts the authors' own conclusions — the research flagged this "descriptive-to-normative trap" as its single biggest methodological hazard.

1. Structure: median 7 sections, middle 50% between 5 and 12 (Prana et al., Empirical Software Engineering 2019, doi 10.1007/s10664-018-9660-3; n=393 repos / 4,226 annotated sections). The metric is sections, not words — the paper reports no length measurement. Population filtered to ≥2 KB English .md software repos.

2. Content skew, and the one normative finding in the whole set. What 97.0%, How 88.5%, References 60.8%, Who 52.9%, Contribution 27.8%, Why 25.7%, When/status 21.4%. The authors argue in their own voice that supplying Why and When is how a repository differentiates itself and signals maturity. This is the only recommendation sourced from authors rather than from inverting a statistic.

3. No evidence-based README length target exists. The only measured baselines (Gaughan et al., CHASE 2025) are of first versions, which are stubs — median reading time 14.79 s, 39% readable in under 10 seconds. The authors frame this as a deficiency, not a norm. Any length rule is taste.

4. Badges: a measured inflection at 5. Trockman et al., ICSE 2018 (doi 10.1145/3180155.3180209; n=294,941 npm packages): a non-linear relationship with popularity inflecting at 5 badges, motivated by survey respondents calling over-badged READMEs cluttered and "trying too hard". The paper also splits badges into assessment signals (a service actually ran an analysis) versus conventional signals (a lookup or a static statement — "cheap to produce, therefore easy to fake"), and advises limiting the latter. This is the only presentation anti-pattern in the entire evidence set with a measured basis. It aligns exactly with this plugin's existing BADGE-STATIC-CLAIM invariant. The coefficient sits in an appendix without CI or p-value, so it supports "badge count is not monotonically beneficial" and cannot support a hard "never exceed 5".

5. Prose readability is machine-measurable. Flesch Reading Ease, McAlpine EFLAW, and Linsear Write via Python textstat; published medians 50.86 / 16.50 / 7.14. Linsear Write is the one designed for technical documents. EFLAW scores accessibility to non-native English readers — it does not measure language choice, and confidence here is medium (single source, and the medians describe sparse first drafts).

3. Refuted — evidence you might expect to have, and do not

Fourteen claims were killed 0–3 or 1–2. The consequential ones:

• Every claim about visual content failed. That images are rare and therefore differentiating; that static images correlate with popularity while GIFs and video do not; that outbound links are the strongest structural feature. There is currently no evidential basis for any rule about screenshots, diagrams, GIFs, or terminal recordings. Adding visuals may still be right — but it is taste, and must be argued as taste.
• Nothing survived on cross-repo coherence mechanisms. No evidence on shared skeletons, org profile pages, catalog hubs, naming taxonomies, or which mechanisms are GitHub-specific. This is the central half of the question and it is unresearched, not settled.
• Nothing survived on named exemplar organisations.
• Nothing survived on English-only language policy. One incidental datapoint: Prana et al. excluded 48 of 1,193 inspected repos as non-English (~4%).
• Nothing survived on prose/markdown linting tooling. Vale, markdownlint, textlint and write-good have no evidenced effect on perceived quality. Only the three textstat metrics are evidenced, and only as instruments.
• Nothing survived on AI-generated-prose tells beyond badge overload — arguably the most consequential 2026 anti-pattern, and entirely unevidenced.

4. Platform ground truth — verified live, not inferred

Measured against git.fromaitochitta.com, Forgejo 15.0.6+gitea-1.22.0:

• Mermaid renders in README.md. Confirmed on the real instance. The published voyage README yields two div.mermaid-block containers, each holding an iframe.markup-render whose srcdoc contains real SVG (26,634 and 24,713 bytes), laid out at 191 px and 1,459 px. The server marks the fences class="chroma language-mermaid display"; Forgejo's own frontend then replaces them. Diagrams therefore need no committed image — and no user-authored iframe, since Forgejo injects its own.
• GitHub's #gh-dark-mode-only / #gh-light-mode-only fragments will NOT work here. That support landed upstream in Gitea 1.26.0 (PR #36922, merged 2026-03-21, released 2026-04-18). This instance is built on gitea-1.22.0 — four minor versions below. Both variants would stack. Any dark-mode image strategy is unavailable today.
• A rendered caution: the second voyage diagram occupies 1,459 px of vertical space and wraps node text mid-word. Mermaid rendering working and Mermaid rendering well are separate questions.
• MERMAID_MAX_SOURCE_CHARACTERS is a per-instance limit; both current diagrams are under it. A longer diagram degrades silently to a plain code block.

5. What this permits, and what it forbids

Cross-referencing the evidence against this plugin's own invariants (No hook until the rule is precise; When a check fires many times in one repo, suspect the CHECK; a gate that fails every repo teaches people to switch the gate off; the gate sees ONE repo):

Defensible as engine checks — precise, measurable, low false-positive risk:

• Badge count above the measured inflection (as WARN, never ERROR — the source cannot carry a hard threshold).
• Non-English prose on a public README. Machine-detectable, and the two hits found are unambiguous. Needs the operator's policy decision first: this is a coherence choice, not a research finding.
• Section count outside 5–12, as information rather than a failure.

Not defensible as engine checks:

• Anything about images, diagrams, screenshots — no evidence base.
• README length — no evidence base.
• Tone, voice, "reads as AI-generated" — no evidence base, and irreducibly judgement.
• Readability thresholds — the instruments exist, the thresholds do not, and a wrong threshold is precisely the false-positive class that gets gates switched off.

Out of scope for this plugin by its own charter: everything about recognisability across repos. The gate sees one repo. A shared skeleton, an org profile page, a consistent description register, a catalog hub — these are org-level questions, and the research found no evidence to guide them anyway.

6. Open decisions

1. Language policy. Is English-only the standard for public open/ repos? Research offers nothing; this is the operator's call. Two repos fail it today if the answer is yes.
2. Where does cross-repo coherence live? Not here. Deciding where is not the same as deciding who builds it — that requires a session in the owning repo.
3. Is a visual standard wanted at all, given that it can only ever be taste? Mermaid is confirmed available; that is capability, not justification.

Verification log

Claim	Source
Median 7 sections, IQR 5–12	Prana et al., EMSE 2019, doi 10.1007/s10664-018-9660-3
Why 25.7% / When 21.4%; authors' differentiation argument	ibid., Table 3 + §7 Implications
No evidence-based length target; first-version stubs	Gaughan et al., CHASE 2025, arXiv:2502.18440
Badge inflection at 5; assessment vs conventional signals	Trockman et al., ICSE 2018, doi 10.1145/3180155.3180209
Flesch / EFLAW / Linsear via textstat	Gaughan et al., CHASE 2025
#gh-dark-mode-only landed in Gitea 1.26.0	go-gitea/gitea PR #36922, issue #35545, release history
Mermaid renders in this instance's README	Live DOM inspection, git.fromaitochitta.com/open/voyage
Instance version 15.0.6+gitea-1.22.0	GET /api/v1/version
All §1 org measurements	Direct measurement of 18 cloned repos

Not verified: whether Forgejo carries Gitea PR #36922 in any later release (only that this instance predates it); whether the markdown sanitizer strips user-authored iframe (two claims failed verification, so embedded terminal recordings remain unestablished); any claim about exemplar organisations, linting tools, or English-only policy.