open/repo-mailbox
1
0
Fork 0
Code Issues Releases 1 Activity

docs(focus): record the condition --focus rests on, before it is built

Browse source 
A cross-repo exchange settled that --plan may grow a --focus filter only if
the same run reports the repos it held back. The decision constrains a future
feature, but it lived only in a private mailbox and a local-only STATE.md, so
nothing durable pointed at it.

The argument is an invariant, not a preference: --plan documents that it has
no cutoff and labels rather than drops, and --focus IS a cutoff. Measuring the
held-back population also turned up the find that carries the decision - a
heavy consumer of the subject, invisible to every strict-marker measurement in
the exchange, recovered only by enumerating what the filter would have hidden.

Other repos are unnamed by design: this mirror is public, and which repo
carries which malformed marker line is that repo's business.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01USD9q3Fr2unp58fe8YvapW
This commit is contained in:
Kjell Tore Guttormsen 2026-08-02 18:42:45 +02:00
commit cb77f2889d
1 changed files with 108 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

108
docs/focus-filter-decision.md Normal file
View file

@ -0,0 +1,108 @@
# `--focus`: what was decided, and the one condition it rests on
Measured 2026-08-02 across 27 `STATE.md` in the operator's tree. Nothing here is
built; `board.sh` is unchanged at v0.17.0. This file exists because the decision
constrains a future feature, and the exchange that produced it lives in a private
mailbox and a local-only `STATE.md` — neither of which is a durable record.
Repos other than `morning-driver` (the plan format's second declared consumer)
are deliberately unnamed: this is a public mirror, and which repo carries which
malformed marker line is that repo's business, not this one's. Every count below
is reproducible by the party that owns the data.
## The decision
A `--focus "<free text>"` argument may filter `--plan` down to the repos whose
`STATE.md` declares a matching topic slug, **on the condition** that the same run
also reports the repos it held back: those whose `STATE.md` mentions the resolved
slug without a valid marker line. Without that report the feature is not built.
## Why the report is a precondition, not an improvement
`--plan` already documents three properties about itself: it takes exactly one
position (the order), it has no cutoff so it hides nothing, and repos with no
board line are labelled rather than dropped — because a plan that omitted them
silently would repeat the defect the plan exists to avoid.
`--focus` is a cutoff. Absent a line saying what fell outside it, the flag breaks
a property the format has already written down. The report is what keeps the two
compatible. `command_missing=` and today's `MERK: N repo mangler board-linje` are
the same shape: they report, they select nothing, and the boundary at
`board.sh:45-51` is untouched by either.
## What the report actually yields (measured)
Strict marker lines over 27 `STATE.md` yield 7 distinct topic slugs; the slug
used as the worked example is declared by 6 repos. For the operator's real phrase
the truth set is ~11 repos, so a strict-marker answer has ~55% recall and no way
to say so. A predicate at that recall presenting itself as a finished day plan is
not a partial answer — it is a wrong one.
"The matched token" has two readings, differing only in noise:
| reading | `STATE.md` mentioning | of those, unmarked |
|---|---|---|
| the operator's bare word | 16 | 10 |
| the resolved slug | 13 | 7 |
Both catch every known miss. The resolved slug is the chosen reading: same
recall, half the noise, and the breadth of the report stops depending on the
operator's choice of words.
The 7 unmarked mentions fall into three classes, all owned by the topic register
(`~/.claude/coord/register.md`), none by this repo:
1. **Malformed marker** — the declaration exists but the register's own grep
loses it: a status token wrapped in bold, or a status token outside the
register's closed set of seven.
2. **Participation without declaration** — the repo owns the specification, or
names the subject in prose, and never writes a marker line at all. One case is
the repo that *is* the subject, which carries zero marker lines.
3. **Discussion** — see the next section.
The most consequential single find was class 1: a repo that pins the library in
its build file, one of the heaviest consumers in the tree, invisible to every
measurement in the exchange until the held-back population was listed. That is
the argument for the report, and it was found by enumerating, not by reasoning.
## Two constraints on the wording
**It says "mentions", never "covers".** The population is self-modifying: this
repo and `morning-driver` enter it only because they spent 2026-08-02 discussing
the subject. Excluding both reproduces exactly the count `morning-driver`
measured independently. A repo can enter the report by *talking about* a subject,
so the line must state a fact about text found (`N repo nevner <slug> uten
markørlinje`) and never a claim about relevance, which `board.sh` has no grounds
for.
**It states its own reach.** `board.sh` reads `STATE.md` and no other file, and
will not start reading others. One repo in the measured set has its strongest
evidence in a `README`, which the scan never sees; it is caught only because a
different line in its `STATE.md` happens to mention the slug. The report has
searched 27 `STATE.md`, and must say that rather than imply it searched repos.
A third invariant is inherited, not new: the scan must never be built on an
ignore-aware search tool. `STATE.md` is gitignored by policy in exactly the repos
that have a public mirror, so such a tool loses precisely that class — it
inverts its own purpose. `board.sh` is immune today because it reads each
`STATE.md` by explicit path in a plain loop. Any topic reader must stay that way.
## `topics=` is closed, not deferred
A `topics=` line per plan block was requested so a natural-language layer in
`morning-driver` could upgrade its evidence from "prose hit" to "declared". That
layer was withdrawn when selection moved here, so the field has no reader, and a
reported field with no reader is noise in a format with two declared consumers.
The need it covered survives but relocates: a *focused* run must say why each
surviving block survived. That is per-block evidence inside `--focus`, not a line
in all 27 blocks on every day the operator has no focus.
## Before any of this is built
No order from the operator exists. If one comes: a failing `board-selftest.sh`
check first, the report in the same commit as the filter — never after it — and
`morning-driver` notified before any field in the block format changes.
`--focus` is the chosen spelling over `--topic`: "topic" names the vocabulary,
which the register owns and this repo only reads; "focus" names the operator's
day, which is what the argument carries.