The cold questions have margin: two of the three fourth-place probes reach their page first (#978)

* manual: two cold questions reach their page first instead of fourth, so the floor has margin

MEASURED FIRST, on dev c495991 with the gate green: 8 of the 22 held-out
questions reach their page first, 9 reach it only within the top four, 5 miss,
and the floor is 17 = 8 + 9 exactly. So the floor did not have one thin probe —
it had NINE simultaneously load-bearing ones, and any of the nine slipping out
of fourth place reddens every open pull request. That is what cost four lanes an
evening: #933 lost one question by a hair to a section about a tick's cell, and
the gate reported an aggregate with no per-question ownership, so it took a
bisect to find out which.

Two of the three fourth-place probes are now first:

  how do I send it a photo                    4th -> 1st   attaching-files
  how do I tell it which project to work on   4th -> 1st   choosing-a-folder

  held out   first 10/22 -> 12/22   ·   within top 4  18/22 -> 18/22
  the hundred-probe plain table    unchanged, nothing lost a place

EACH WAS MEASURED AND ONLY THE FORM THAT MOVED WAS KEPT. attaching-files took
the asker's words into its EXISTING heading and went first. choosing-a-folder
did NOT move that way — the same edit to its heading left it fourth — because
its `/folder` section is four thousand characters and loses on length
normalisation however many of the asker's words the heading carries. A short
section of its own took it first. That is the form #973 proved works, and the
correction it forced on the folklore this repository was passing around: a new
`## ` heading is a HAZARD to be measured, not a prohibition to be obeyed. What
is forbidden is adding one and trusting it.

AND THE NEW SECTION SAYS WHAT THE PAGE SAYS. The first draft claimed the chosen
folder's name is on the status line, which contradicts this page's own law five
hundred lines down — what choosing a folder does is make the conversation ABOUT
it, while where aforge is standing does not move. Corrected before it shipped,
and it points at the section that owns the distinction rather than restating it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(changes): number the entry with the pull request it belongs to

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(changes): the length cap and the retrieval floor are one law, not two

Lane P's reframing of this change's own finding, and it is better than the
finding was. I had written "a long section resists its heading". What is
actually true is that CLAUDE.md's "keep each section under ~2000 characters and
self-contained" IS the retrieval rule: BM25 normalises by length, so a section
past the cap is already hard to reach whatever its heading says. Measured on
this page — the `/folder` section is 3825 characters and would not move to first
place however many of the asker's words its heading carried, while a
600-character section on the same page took the same question to first.
choosing-a-folder.md has nine sections over the cap, up to 5079.

That matters because of WHEN each rule can be followed. "Measure both forms"
only helps somebody who already has a retrieval failure to diagnose. "Keep the
section under two thousand characters" is a rule they can follow while writing,
before anything is red — and it now has a measured reason rather than reading as
a preference about how much prose a person wants at once.

It also gives the choice between the two forms a cheap test instead of
judgement: `wc -c` the section. Under the cap, put the asker's words in the
heading. Over it, split the section — which fixes both laws at once — or write a
short one beside it. Splitting is the better instrument where there is room,
because an over-cap section is a defect on its own terms and not only when a
probe finds it. Not done here: nine sections is its own piece of work.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(changes): name the section this change checked its claim against

Lane P's proposed shape for the one failure the manual gates cannot catch, tried
here on the change that found the need for it rather than argued about.

CLAUDE.md is explicit that the gates check a name is MENTIONED and never that the
claim around it is true — a tool named in a "what aforge cannot do" section
satisfies them perfectly while lying. It also already obliges a lane landing a
capability to grep the corpus for the old denial. So the honest statement is not
that there is no mechanism; it is that there is a stated obligation with nothing
behind it.

This entry now names the section it checked against. It is not a gate and could
not be made into one cheaply. It is a prompt to do the read, written where a
reviewer can see whether it was done — and the read is what caught this change's
own false sentence, which no test in this repository would have.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: santoshkumarradha

docs/changes/unreleased/978-cold-question-headroom.md

@@ -0,0 +1,45 @@
+---
+kind: fixed
+title: Two cold questions reach their page first instead of fourth, so the retrieval floor has margin
+pr: 978
+surface: [chat, docs]
+invalidates:
+  - "The held-out retrieval floor in internal/manual/plainquestions_test.go had NO margin anywhere, not one thin probe: on a green tree 8 of the 22 cold questions reached their page first, 9 reached it only within the top four, and the floor is 17 — so all nine of those were simultaneously load-bearing and any one slipping out of fourth place reddened every open pull request. Two of the three fourth-place probes are now first, so it is 12 first of 22 rather than 10 and the floor has room."
+  - "The folklore that a new `## ` heading in internal/manual/chat always hijacks BM25 and must never be added is too strong. It is a hazard, not a prohibition: #973's install section proved a new heading can be the right instrument, and the short section added here to choosing-a-folder.md took its question from fourth place to first with nothing else losing a place. What is forbidden is adding one WITHOUT measuring the whole table."
+  - "CLAUDE.md's `keep each section under ~2000 characters and self-contained` has been readable as a style preference about how much prose somebody wants to read at once. It is not: THE LENGTH LAW AND THE RETRIEVAL LAW ARE THE SAME LAW. BM25 normalises by length, so a section past the cap is already hard to reach whatever its heading says — measured here, the `/folder` section is 3825 characters and would not move to first place however many of the asker's words its heading carried, while a 600-character section on the same page took the same question to first. choosing-a-folder.md has nine sections over the cap, up to 5079."
+---
+
+Lane R and lane P spent an evening between them on a red that was one question
+slipping by three thousandths of a point, and the reason it cost that much is
+that the gate reports one aggregate with no per-question ownership.
+
+Both changes are measured rather than reasoned. `attaching-files` took the
+asker's words into its existing heading; `choosing-a-folder` did not move that
+way — its `/folder` section is 3825 characters and loses on length normalisation
+however many of the asker's words the heading carries — so it got a short section
+of its own instead, which is the form #973 proved works when the whole table is
+measured with it.
+
+**So there is a cheap test before choosing between the two forms, and it is not
+judgement:** `wc -c` the section. Under CLAUDE.md's ~2000 character cap, put the
+asker's words in its heading. Over the cap, the section is already unreachable —
+split it, which fixes the length law and the retrieval together, or write a short
+new one beside it. Splitting is the better instrument where there is room,
+because a section past the cap is a defect on its own terms and not only when a
+probe happens to find it. This change does not do that for choosing-a-folder.md's
+nine over-cap sections; that is its own piece of work.
+
+**Checked against:** `## What choosing a folder actually does — this conversation
+is now about it`, on the same page. The new section's first draft said the chosen
+folder's name is on the status line; that section says the opposite and is right
+— choosing a folder makes the conversation ABOUT it, while the directory aforge
+is standing in does not move. The claim was corrected before this shipped and the
+new section now points at that one rather than restating it.
+
+That line is here deliberately, as lane P's proposed shape for a problem the gates
+cannot catch: CLAUDE.md says the manual gates check that a name is MENTIONED,
+never that the claim around it is true, and a lane landing a capability is already
+obliged to grep the corpus for the old denial — an obligation with nothing behind
+it. Naming, in the entry, which other section you checked your claim against is
+not a gate. It is a prompt to do the read, written where a reviewer can see
+whether it was done.

internal/manual/chat/attaching-files.md

@@ -50,7 +50,7 @@ Inside the paste editor, `ctrl+x` does the same thing. There is no recovery afte
 is discarded, though ordinary unsent draft recovery still applies to the rest of the
 message.
 
-## Send a file with your message — /attach, how do I share a file with aforge
+## Send a file with your message — /attach, how do I share a file with aforge, how do I send it a photo or an image
 
 `/attach <path>` puts an ordinary file — a log, a CSV, a PDF, a stack trace you saved —
 on the tray above the message box, and it goes with the next thing you send.

internal/manual/chat/choosing-a-folder.md

@@ -64,6 +64,22 @@ whole gesture is `/folder` then `enter`.
 `esc` leaves everything exactly as it was: your half-written message comes back untouched,
 and nothing has been chosen.
 
+## Tell it which project to work on
+
+`/folder`, then pick the directory. The conversation says `folder · ~/code/agentfield`
+and is about that project from then on: its exact path is written into my
+instructions, along with its own `AGENTS.md` or `CLAUDE.md` rules if it has any,
+so you never have to say which folder you meant again.
+
+To add a second project, run `/folder` again — what the conversation is about
+grows as you name folders. What does NOT move is where aforge is standing: the
+directory you started it in is the one the status line shows and the one a bare
+`notes.md` means, for the life of the conversation. `## What choosing a folder
+actually does` below has the whole of that distinction.
+
+To start a new conversation already pointed at a project, `/folder` on the home
+screen picks the folder the next one opens in.
+
 ## The add context sheet over --host — another machine, over ssh
 
 Over `--host`, a bare `/attach` opens the add context sheet on the machine you are sitting