Title/heading quality findings: duplicate titles and missing/empty H1 — the scent agents actually act on
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
Why
In index.md, llms.txt, and trails.json, the document title is the only cue a consumer (human or agent) has when deciding whether to open a doc. This is where the information-scent theory genuinely applies to agents — not anchor text (see the ADR 0016 correction issue): agents see hrefs in source, but in matlatl's own emitted catalogs the title IS the affordance.
Title resolution already exists (corpus.Document.Title: front-matter → first H1 → DocumentID, ADR 0016). What's missing is flagging when that chain produces bad scent.
Findings to add (all Info, never gating)
untitled-doc— no front-matter title and no H1: the catalog falls back to the file path. Fix: add a title or H1.duplicate-title— two+ docs resolve to the same title: indistinguishable entries in every emitted catalog. Fix: disambiguate.- Consider: generic titles ("Notes", "Misc", "TODO", "Untitled") via a small in-source phrase set, mirroring
scent.go's scent-free set.
Notes
- Deterministic and trivial: pure functions over already-parsed titles; sorted iteration.
- findings.json schema bump (additive kinds + summary counts).
- Dogfood first — matlatl's own ADR titles (
# 16. Agent experience: …) should pass; numeric prefixes are identity-bearing, don't flag them.
🤖 Generated with Claude Code
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing corpus.Document.Title and the existing scent.go phrase set, then inspect how findings.json and the catalogs index.md, llms.txt, and trails.json are produced. Done means deterministic, sorted Info findings for untitled-doc and duplicate-title, optional generic-title handling, additive summary counts, and passing dogfood checks for the ADR titles.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100