Skip to content
← Documentation

docs/what-the-city-is-asked.md


The three questions, and which channel should answer them

Before adding a second geometric axis, measured: what does a first-time reader try to do, and is geometry the right carrier for it?

Where the questions come from

Grounded in observed use rather than imagination — these are the three things I did when opening ky, a repository the system had never seen, and each one is why a capability exists (hesitations).

question evidence
Q1 What is this, and how much is here? the first thing read on opening was the counts
Q2 Where is the file I am thinking about? the reason FindSubject was built
Q3 What changed? the reason compare and review were built

A fourth is implied by the city metaphor rather than observed, and is marked as such below.

Is a second geometric dimension the right carrier?

Q1 — scale and orientation. No. Answered by counts already on screen: 177 buildings · 31 districts, the absence panel, the observation window. A second axis adds nothing a number does not already say, and the existing 1-D extent already shows the repository's size at a glance.

Q2 — lookup. No, and geometry is the wrong carrier in principle. A reader cannot scan 177 anonymous boxes for a filename; search answers in one query and flies the camera there. Measured: at 177 buildings, 171 labels (96.6%) overlap another and 121–129 buildings are covered by a nearer building's label — the geometric channel for identity was already failing before any axis was added. More space would not fix scanning; indexing did.

Q3 — change. No, and a second axis would make it worse. Already measured across four repositories: position is the worst change channel — 90.6% false firings, AUC 0.739, against subject-scoped scalars at 0% false under a stable reference (change-channels). Motion and position were falsified as change carriers by direct measurement. Giving change more geometry contradicts evidence already in hand.

None of the three most common questions wants a second geometric axis.

Q4 — what are the parts, and which go together?

Inferred from the city metaphor, not observed. Recorded as a hypothesis.

This is the only question a second axis could serve, and today the city actively misleads on it. Districts are drawn as rings around co-change positions, so containment and coupling disagree:

mean district span 26.9% of the whole city
districts spanning >50% of the city 3
foreign buildings inside a district's extent 24.2%
district pairs whose extents overlap 85/153 (55.6%)

A ring drawn around a set whose members are scattered across a quarter of the city, overlapping half the other rings, asserts a grouping the positions do not support.

And at the current granularity there is nothing to group

District is the full directory path: 32 districts over 178 buildings, median size 2. Two-member neighbourhoods are not neighbourhoods. Measured across depths:

path depth groups median largest singletons groups ≥8
1 6 6 101 3 2
2 10 12 59 3 6
3 24 5 56 7 7
4 (shipped) 30 3 56 12 6

Depth 2 is the only level with neighbourhood-shaped groups. Depth 1 collapses to src (101) and tests (68); the shipped depth fragments into pairs.

What this recommends

Do not add an invented second axis. Change what a district is.

Containment is observed — it comes from placement facts — and it already has a channel that is mis-granulated and spatially incoherent. Grouping at depth 2 and letting position carry coupling within a group would carry both truths at once: which part of the system a subject belongs to, and what it changes with. No new semantics; the second dimension would assert containment, which the world already records and currently expresses only as colour.

Two things must be measured before building it, and neither is done:

  1. What it costs the coupling claim. Constraining position by group must degrade the metric fit. Stress is already 1.029 — worse than a null configuration — so the honest comparison is against a repaired 1-D baseline, not against today's.
  2. Whether it survives other repositories. zustand at 5 placed buildings and httpie at 0 will not have neighbourhoods at any depth, and the layout must degrade truthfully rather than inventing structure.

One channel that carries nothing

footprint has 1 distinct value across 178 buildings. It varies with nothing and is decoration by this project's own definition. Recorded here rather than repaired, because removing it is a rendering change and those are frozen until each ships with before/after captures.