Explore /authors-optimization design docs → decide build-out (epic + worktree)

The /authors optimization DB spine is COMPLETE and committed on feature/authors-optimization (6 commits: #242 qualification, #251 pivot denorm, #252 composite indexes + pivot-first rewrite [perf win validated 21ms→0.05ms local; ~338ms→sub-5ms prod], #250 geo indexes, #249 whereExists rewrite). 4 feature children remain: #253 proximity search, #254 followed-only filter, #255 favorites+home+/settings, #256 frontend/UX. Weekly Claude usage hit ~80% (resets 6am America/Chicago) and I paused to avoid exhausting the cap unattended. How do you want to proceed?

Plan is locked: foundation #242 first (qualified location set), then a slimmed /authors epic — perf (C1/C2/C5/C6) + proximity (C7, both-sort default karma) + followed-only (C8) + favorites/home/standalone-/settings (C9) + frontend (C10), in a fresh feature/authors-optimization worktree. Interim cache dropped; app-wide centralization split to a later round. Approve to scaffold #242 + the epic + child briefs? (No rush — you can still tweak the breakdown/sequencing.)

# /authors optimization — scoped epic plan (final, awaiting scaffold go) ## Status Scope LOCKED with operator 2026-07-04/05 (decisions #62–#66 + scope discussion). Depends on foundation brief **#242** (qualified location set), sequenced FIRST. **Awaiting operator's go to scaffold** (clean decision on the board). Build is MUTATING → fresh `feature/authors-optimization` worktree, NOT the MAIN checkout. ## Prerequisite **#242 — Location qualification foundation** lands first: config-driven qualified `locations` flag + sweep + Scout/Meili reconciliation. This epic's proximity + typeahead search that qualified set. (Replaces the former in-epic C3 "minimal floor.") ## Final agreed scope ### IN - **Perf/data-model foundation** — denormalize sort keys + `is_visible` onto the 7.9M-row `location_reddit_user` pivot + 3 composite covering indexes + pivot-first rewrite → 338ms→sub-5ms dense-location filesort. - **Geo indexes + proximity search** — `(lat,lng)`/`(lat,long)` B-tree indexes; city-centric radius (0/10/25/50/100 mi); **sort offers both karma + distance, default karma** (#63); searches #242's qualified set. - **Followed-only filter** — warm 60-min cache + `whereIntegerInRaw`; auth-gated pill. - **Favorite locations + home + standalone `/settings` page** (#64) — `Location` adopts Markable; **add `users.location_id` FK** (#65, confirm not-exists first); reuse `users.location_id` as home; **low-friction favorite + set-home; favorites+home as quick-select in the location search.** - **Frontend/UX pass** — composite location chip, Followed pill, quick-select, star-a-location on /locations + /location/{slug}, /settings chrome. ### OUT (moved / dropped) - **Location qualification / minimal floor** → **#242** (foundation, sequenced first). - **Interim ordered-id page cache (former C4)** → **DROPPED** (operator, 2026-07-05) — the durable pivot-first fix supersedes it. - **App-wide location-search centralization + call-site audit (former C11/D0)** → **separate later round** after /authors. - **Legacy followed-users cache-key rename (#66)** → separate cleanup pass. - **Full location-record cleanup/merge** → separate future cycle. ## Proposed epic → child-brief breakdown (in `feature/authors-optimization`, after #242) | Child brief | From | Depends on | Notes | |---|---|---|---| | C1 · `whereExists` location rewrite | PR1 | — | safe quick win | | C2 · Geo lat/lng indexes | PR2 | — | quick win; unblocks proximity | | C5 · Pivot denormalization (cols + backfill + sync) | PR5 | — | durable refactor | | C6 · Composite indexes + pivot-first rewrite | PR6 | C5 | headline perf win | | C7 · Proximity search (both-sort, default karma) | PR7 | C2, C6, #242 | searches qualified set | | C8 · Followed-only filter | PR8 | C1 | independent | | C9 · Favorites + home + /settings (FK, quick-select) | PR9 | C8, #242 | standalone /settings | | C10 · Frontend/UX pass | PR10 | C7, C8, C9 | quick-select + star-a-location | C1/C2/C5 can start immediately in parallel; C5→C6 is the durable spine; C7/C9/C10 layer on top; the qualified-set consumers (C7/C9) follow #242. ## Constraints - Build in a fresh isolated worktree (`feature/authors-optimization`), never MAIN. - Each child brief independently reviewable/revertible; prod migrations online/off-peak per design §5. - Design §8 validation applies — perf numbers are derived; validate on prod after each index lands. ## Go gate Clean scaffold decision on the board (replaces withdrawn #67): approve → #242 lands first, then this epic + child briefs scaffold and dispatch into the worktree.

# /authors optimization — scoped epic plan (for operator approval) ## Status Scope locked with operator 2026-07-04 (decisions #62–66 + inline scope notes). This brief now holds the agreed scope + proposed epic/child-brief breakdown. **Awaiting operator's final go to scaffold the epic** (see open question). Build is MUTATING → dispatches into a fresh `feature/authors-optimization` worktree, NOT the MAIN checkout. ## Final agreed scope ### IN - **Perf/data-model foundation** — denormalize sort keys + `is_visible` onto the 7.9M-row `location_reddit_user` pivot + 3 composite covering indexes + pivot-first rewrite → 338ms→sub-5ms dense-location filesort. (Operator: reads are the bottleneck, KEEP.) - **Geo indexes + proximity search** — `(lat,lng)`/`(lat,long)` B-tree indexes; city-centric radius (0/10/25/50/100 mi); **sort offers both karma + distance, default karma** (#63). Uses the minimal location floor (below) instead of a quality gate. - **Minimal, always-on, invisible location floor** (replaces the cut quality feature) — governs which locations surface in typeahead + proximity: **min name length (~≥3 chars: kills `mf`, keeps `PDX`) + min post/author count**. No user toggle, tunable via AppSettings. Discovery only; `resolveFromSlug` reachability untouched. - **Followed-only filter** — warm 60-min cache + `whereIntegerInRaw`; auth-gated pill. - **Favorite locations + home + /settings** — `Location` adopts Markable; **standalone `/settings` page** (#64); **add `users.location_id` FK** ON DELETE SET NULL (#65, confirm not-exists first); reuse `users.location_id` as home. **Low-friction favorite + set-home actions, and favorites+home surfaced as quick-select options in the location search.** - **Frontend/UX pass** — composite location chip, Followed pill, quick-select, star-a-location on /locations + /location/{slug}, /settings chrome. (No quality toggle in the UX.) - **Interim ordered-id page cache** — 15-min stopgap before the durable index lands. - **App-wide location-search centralization** (NEW, operator ask) — audit every place the app does location search/filtering; unify onto the shared geo flow. Starts with a call-site discovery sub-task. ### CUT / DEFERRED (explicitly OUT of this epic) - **User-facing location "quality" toggle + full doc-30 quality UX** — cut. Replaced by the minimal invisible floor above. - **Full location-record qualification/cleanup** — deferred to a separate cycle. - **Legacy followed-users cache-key rename** (`user_followed_reddit_users_{id}`) — separate cleanup pass (#66), not this epic. ## Proposed epic → child-brief breakdown (maps to design README §4, adjusted for cuts) Parent: **Epic: /authors optimization** — dedicated worktree `feature/authors-optimization`. | # | Child brief | From | Depends on | Notes | |---|---|---|---|---| | D0 | Location-search call-site audit + unified geo interface | NEW | — | Discovery; feeds centralization + informs rewrites | | C1 | `whereExists` location rewrite | PR1 | — | Safe quick win | | C2 | Geo lat/lng indexes | PR2 | — | Quick win; unblocks proximity + centralization | | C3 | Minimal location floor (name-length + lightweight count) | PR3 (modified) | — | No user toggle; add lightweight count col only if none exists | | C4 | Interim ordered-id page cache | PR4 | — | Quick win stopgap | | C5 | Pivot denormalization (cols + backfill + sync) | PR5 | C4 | Durable refactor | | C6 | Composite indexes + pivot-first rewrite | PR6 | C5 | Headline perf win | | C7 | Proximity search (both-sort, default karma) | PR7 | C2, C6, C3 | Uses the minimal floor | | C8 | Followed-only filter | PR8 | C1 | Independent | | C9 | Favorites + home + /settings (FK, quick-select) | PR9 | C3, C8 | Standalone /settings | | C10 | Frontend/UX pass | PR10 | C7, C8, C9 | Quick-select + star-a-location; no quality toggle | | C11 | Location-search centralization | NEW | D0, C2, C6 | Unify call sites onto the geo flow | Quick wins C1–C4 + D0 can start immediately, in parallel; C5→C6 is the durable spine; C7/C9/C10 layer on top. ## Constraints - Build happens in a fresh isolated worktree (`feature/authors-optimization`), never the MAIN checkout. - Each child brief is independently reviewable/revertible; prod migrations run online/off-peak per design §5 (ALGORITHM specified, backfill-before-index). - Design §8 validation plan applies — all perf numbers are derived; validate on prod after each index lands. ## Open question (operator — final gate before scaffolding) Approve this scoped epic plan → scaffold the epic + child briefs (build dispatches into `feature/authors-optimization`)? Or adjust the breakdown/sequencing first?

**Operator refinement (2026-07-04, round 2) — re-sequenced. Full #239 spec rewrite to follow once structure is confirmed.** 1. **Location floor → replaced by a foundational qualification mechanism, sequenced FIRST as new brief #242.** Operator prefers a precomputed, config-driven qualified flag (boolean flag on `locations` + AppSetting-driven conditions + scheduled sweep + AppSetting-change rebuild + Scout→Meilisearch reconciliation) over doc-30's maintained live counts. Includes a low-hanging-fruit cleanup pass. **Former C3 (minimal query-time floor) is REMOVED** — absorbed by #242. The /authors epic now **DEPENDS ON #242** (proximity + typeahead search the qualified set). Operator principle: clean up the foundation before building the layer on top. 2. **App-wide location-search centralization (former C11 + D0 audit) → PULLED OUT of this epic into a SEPARATE later round.** Operator: audit the (messy) search landscape and unify *selectively* — some places (admin views, complex existing search components) may not want it, yet or ever. Do /authors first; then a dedicated audit+refine round for the broader search landscape. 3. **Interim ordered-id page cache (former C4): keep-or-drop is operator's call.** It's a 15-min stopgap that hides the cold dense-location filesort on repeat hits *only until* the durable pivot-first fix (C6) lands — purely temporal value, droppable if we're fine waiting for C6. **Net slimmed epic:** perf foundation (C1/C2/C5/C6) + proximity (C7) + followed (C8) + favorites/settings (C9) + frontend (C10), all built on top of #242's qualified location set. #239's scaffold gate (#67) is paused pending this re-scope. **Reset note:** operator asked me to hold my make-before-break reset until this location/brief refinement is fully planned/decided; honoring that.

Scope is locked (decisions #62–#66 + your cuts folded in). #239 now holds the final agreed scope + a proposed epic → 12 child-brief breakdown, to build in a fresh feature/authors-optimization worktree. Approve → I scaffold the epic + child briefs and the orchestrator dispatches the build into that worktree. Anything to adjust first?

# /authors optimization — scoped epic plan (for operator approval) ## Status Scope locked with operator 2026-07-04 (decisions #62–66 + inline scope notes). This brief now holds the agreed scope + proposed epic/child-brief breakdown. **Awaiting operator's final go to scaffold the epic** (see open question). Build is MUTATING → dispatches into a fresh `feature/authors-optimization` worktree, NOT the MAIN checkout. ## Final agreed scope ### IN - **Perf/data-model foundation** — denormalize sort keys + `is_visible` onto the 7.9M-row `location_reddit_user` pivot + 3 composite covering indexes + pivot-first rewrite → 338ms→sub-5ms dense-location filesort. (Operator: reads are the bottleneck, KEEP.) - **Geo indexes + proximity search** — `(lat,lng)`/`(lat,long)` B-tree indexes; city-centric radius (0/10/25/50/100 mi); **sort offers both karma + distance, default karma** (#63). Uses the minimal location floor (below) instead of a quality gate. - **Minimal, always-on, invisible location floor** (replaces the cut quality feature) — governs which locations surface in typeahead + proximity: **min name length (~≥3 chars: kills `mf`, keeps `PDX`) + min post/author count**. No user toggle, tunable via AppSettings. Discovery only; `resolveFromSlug` reachability untouched. - **Followed-only filter** — warm 60-min cache + `whereIntegerInRaw`; auth-gated pill. - **Favorite locations + home + /settings** — `Location` adopts Markable; **standalone `/settings` page** (#64); **add `users.location_id` FK** ON DELETE SET NULL (#65, confirm not-exists first); reuse `users.location_id` as home. **Low-friction favorite + set-home actions, and favorites+home surfaced as quick-select options in the location search.** - **Frontend/UX pass** — composite location chip, Followed pill, quick-select, star-a-location on /locations + /location/{slug}, /settings chrome. (No quality toggle in the UX.) - **Interim ordered-id page cache** — 15-min stopgap before the durable index lands. - **App-wide location-search centralization** (NEW, operator ask) — audit every place the app does location search/filtering; unify onto the shared geo flow. Starts with a call-site discovery sub-task. ### CUT / DEFERRED (explicitly OUT of this epic) - **User-facing location "quality" toggle + full doc-30 quality UX** — cut. Replaced by the minimal invisible floor above. - **Full location-record qualification/cleanup** — deferred to a separate cycle. - **Legacy followed-users cache-key rename** (`user_followed_reddit_users_{id}`) — separate cleanup pass (#66), not this epic. ## Proposed epic → child-brief breakdown (maps to design README §4, adjusted for cuts) Parent: **Epic: /authors optimization** — dedicated worktree `feature/authors-optimization`. | # | Child brief | From | Depends on | Notes | |---|---|---|---|---| | D0 | Location-search call-site audit + unified geo interface | NEW | — | Discovery; feeds centralization + informs rewrites | | C1 | `whereExists` location rewrite | PR1 | — | Safe quick win | | C2 | Geo lat/lng indexes | PR2 | — | Quick win; unblocks proximity + centralization | | C3 | Minimal location floor (name-length + lightweight count) | PR3 (modified) | — | No user toggle; add lightweight count col only if none exists | | C4 | Interim ordered-id page cache | PR4 | — | Quick win stopgap | | C5 | Pivot denormalization (cols + backfill + sync) | PR5 | C4 | Durable refactor | | C6 | Composite indexes + pivot-first rewrite | PR6 | C5 | Headline perf win | | C7 | Proximity search (both-sort, default karma) | PR7 | C2, C6, C3 | Uses the minimal floor | | C8 | Followed-only filter | PR8 | C1 | Independent | | C9 | Favorites + home + /settings (FK, quick-select) | PR9 | C3, C8 | Standalone /settings | | C10 | Frontend/UX pass | PR10 | C7, C8, C9 | Quick-select + star-a-location; no quality toggle | | C11 | Location-search centralization | NEW | D0, C2, C6 | Unify call sites onto the geo flow | Quick wins C1–C4 + D0 can start immediately, in parallel; C5→C6 is the durable spine; C7/C9/C10 layer on top. ## Constraints - Build happens in a fresh isolated worktree (`feature/authors-optimization`), never the MAIN checkout. - Each child brief is independently reviewable/revertible; prod migrations run online/off-peak per design §5 (ALGORITHM specified, backfill-before-index). - Design §8 validation plan applies — all perf numbers are derived; validate on prod after each index lands. ## Open question (operator — final gate before scaffolding) Approve this scoped epic plan → scaffold the epic + child briefs (build dispatches into `feature/authors-optimization`)? Or adjust the breakdown/sequencing first?

# Explore /authors-optimization docs → build-out decision ## Goal Assess the `docs/authors-optimization/` design (9 docs on `authors-location-optimization-plan` / #238) — what it is and how ready it is — and recommend whether and how to build it out. If green-lit, scaffold the implementation as an epic brief + sequenced child briefs in a dedicated worktree. (Third brief in the #225 → #238 branch campaign.) ## What the design is (refine daemon read README master report, 2026-07-04) A complete optimization + feature design for the `/authors` page — five asks on a perf foundation: 1. **Perf/data-model foundation (doc 10)** — denormalize sort keys + `is_visible` onto the 7.9M-row `location_reddit_user` pivot + 3 composite covering indexes + pivot-first rewrite → the 338.7ms/page dense-location filesort becomes sub-5ms. 2. **Proximity search (doc 20)** — geo B-tree `(lat,lng)` index → city-centric radius (0/10/25/50/100 mi), quality-gated, capped to 64 nearest, cached. 3. **Location quality (doc 30)** — `locations.authors_count` floor (default 5) → clean typeahead (21.8K of 206K locations kept). 4. **Followed-only filter (doc 40)** — warm 60-min followed-users cache + `whereIntegerInRaw`. 5. **Favorite locations + /settings (doc 50)** — `Location` adopts Markable; new `/settings` page; reuse `users.location_id` as home. Frontend/UX layer across all five (docs 60/70): composite location chip, Followed pill, typeahead rebuild, star-a-location, /settings chrome. ## Maturity Execution-ready: adversarially verified (perf/SQL core independently checked, 3 corrections folded in; UX conflicts resolved canonically in README §0); sequenced 10-PR roadmap (§4) with effort/risk/deps; consolidated migration+index list (§5); risk register (§6); validation plan (§8). 7 open product questions for Mike remain (§7). ## Deliverable (this brief) 1. **Confirm the assessment** against the full doc set (README + docs 10–70), not just the README. 2. **Build/no-build recommendation** (expected: BUILD) with the proposed **epic + child-brief breakdown mapped to §4's 10 PRs** (which PRs group, dependency edges). 3. **Surface the 7 §7 product questions** for Mike as decisions (they gate schema/UX shape of several PRs). 4. **If green-lit:** concrete scaffold plan — worktree name (e.g. `feature/authors-optimization`), the epic brief + ordered child briefs, and their dependency edges (PR5→6, PR7 needs 2+6, PR9 needs 3+8, PR10 needs 7/8/9). ## Recommendation (refine daemon) **BUILD.** This is a verified, self-sequencing epic, not a sketch — worth scaffolding as an epic + PR child briefs in a dedicated worktree. PRs 1–4 are safe independent quick wins that can ship in days. ## Constraints - **Read-only exploration.** No code changes. Actually creating the epic/child briefs + worktree is a follow-on once green-lit (orchestrator owns dispatch + worktree creation). ## Open question (operator — fold before planned) Green-light scaffolding the implementation epic now (epic + PR child briefs in a dedicated worktree), or stop at this assessment for now? Default if unanswered: hold at the assessment/recommendation (do not auto-scaffold an epic without the operator's go).

**Operator decision (2026-07-04) — interim location floor = option (b).** Supersedes/refines scope-decision #1's "expose everything unfiltered." Keep a **minimal, always-on, non-user-facing floor** governing which locations surface in the typeahead + proximity results — NOT a user toggle, NOT the full doc-30 quality UX. Operator's stated criteria: - **Min name length** — exclude junk like `mf` (2 chars) while keeping valid short names like `PDX` (3 chars). So ~≥3 chars (exact threshold tunable; watch for any legitimate 2-char names → allowlist if they exist). - **Min post (or author) count** — a low threshold to drop one-off/empty locations. Always-on, invisible to users, tunable via AppSettings. This is a lightweight interim guard **only** — the full location-record qualification/cleanup remains deferred to a separate cycle. **Implementation nuance for the epic:** - Name-length check is **free** (`CHAR_LENGTH(name) >= N`), no schema. - Min-count check needs a location post/author count. **Build step: confirm whether `locations` already carries a denormalized post/author count.** If yes, reuse it. If not, add a **lightweight** denormalized count column (a slice of the former PR3) — WITHOUT the user-facing quality toggle or the `quality_counts_updated_at` staleness ceremony. Keep it minimal. - Applies to discovery surfaces (typeahead + proximity candidate set), not reachability (`resolveFromSlug` stays untouched — existing links keep working).

**Operator scope decisions (2026-07-04, round 1 — stepping through in pieces; more to come on the 7 §7 product questions):** 1. **CUT the location-quality feature (design doc 30 / roadmap PR3) as scoped.** Operator does not want a user-facing "quality" toggle/metric on locations, and does not want users deciding whether to filter. Position: rather than gate locations behind an active/inactive filter, *properly qualify which locations are surfaced* — but that (location-record cleanup) is a **larger separate discussion, explicitly OUT of this flow**. For now: **expose everything reasonable; defer location-record qualification/cleanup to a separate cycle.** If any quality mechanism is ever built, it must be **always-on, never a user toggle**. - ⚠ Consequence to confirm: doc-30's `authors_count` also underpins (a) the **typeahead** usability (206K locations, ~94% junk today) and (b) **proximity's internal quality gate** (doc 20 caps to 64 *quality* locations). Cutting it means the typeahead surfaces locations unfiltered (noisier) and proximity uses nearest-N without a quality gate until the separate cleanup cycle. Need operator's read on whether "expose everything reasonable for now" accepts that interim noise, or wants a minimal *non-user-facing* floor purely to keep the typeahead/proximity sane. 2. **Perf denorm columns + indexes (PR5/PR6): KEEP, operator unconcerned.** Ingest isn't the bottleneck; reads/user requests are — happy to trade write-amplification for read UX, as long as it's functional/usable/efficient. 3. **NEW scope item (operator suggestion): centralize location search/filtering app-wide.** Since we're adding lat/lng indexes + radius infra, audit *everywhere else* the app does location search/filtering and unify it onto the same geo flow/system. Likely warrants its own discovery sub-task (enumerate all location-search/filter call sites) + a centralization workstream in the epic. 4. **/settings page (PR9): KEEP.** Placement flexible — standalone `/settings` OR folded into / consolidated with existing profile pages, operator's fine either way. 5. **Favorites + home location UX (PR9): KEEP + sharpen.** Requirement: **low-friction** favorite-a-location and set-home-location actions, AND favorited + home locations surfaced as **quick-select options in the location search**. (Reuse `users.location_id` for home stands.) **Still open:** operator reviewing the 7 §7 product questions, will return. Holding the full spec rewrite + any epic scaffolding until scope is fully settled.

Operator answered Q62 = "Discuss scope/sequencing first" and asked for an overall bullet list of everything the design touches/changes before scaffolding into an epic — to veto anything unwanted. Refine daemon delivered the full touch-list in-session (schema changes, new user-facing surfaces, modified files, new artisan commands + schedules, caching changes, scope boundaries, and a flagged-for-confirmation list). **Holding scaffolding pending operator's trim/veto decisions — will NOT scaffold the epic until an explicit go.**

# Explore /authors-optimization docs → build-out decision ## Goal Assess the `docs/authors-optimization/` design (9 docs on `authors-location-optimization-plan` / #238) — what it is and how ready it is — and recommend whether and how to build it out. If green-lit, scaffold the implementation as an epic brief + sequenced child briefs in a dedicated worktree. (Third brief in the #225 → #238 branch campaign.) ## What the design is (refine daemon read README master report, 2026-07-04) A complete optimization + feature design for the `/authors` page — five asks on a perf foundation: 1. **Perf/data-model foundation (doc 10)** — denormalize sort keys + `is_visible` onto the 7.9M-row `location_reddit_user` pivot + 3 composite covering indexes + pivot-first rewrite → the 338.7ms/page dense-location filesort becomes sub-5ms. 2. **Proximity search (doc 20)** — geo B-tree `(lat,lng)` index → city-centric radius (0/10/25/50/100 mi), quality-gated, capped to 64 nearest, cached. 3. **Location quality (doc 30)** — `locations.authors_count` floor (default 5) → clean typeahead (21.8K of 206K locations kept). 4. **Followed-only filter (doc 40)** — warm 60-min followed-users cache + `whereIntegerInRaw`. 5. **Favorite locations + /settings (doc 50)** — `Location` adopts Markable; new `/settings` page; reuse `users.location_id` as home. Frontend/UX layer across all five (docs 60/70): composite location chip, Followed pill, typeahead rebuild, star-a-location, /settings chrome. ## Maturity Execution-ready: adversarially verified (perf/SQL core independently checked, 3 corrections folded in; UX conflicts resolved canonically in README §0); sequenced 10-PR roadmap (§4) with effort/risk/deps; consolidated migration+index list (§5); risk register (§6); validation plan (§8). 7 open product questions for Mike remain (§7). ## Deliverable (this brief) 1. **Confirm the assessment** against the full doc set (README + docs 10–70), not just the README. 2. **Build/no-build recommendation** (expected: BUILD) with the proposed **epic + child-brief breakdown mapped to §4's 10 PRs** (which PRs group, dependency edges). 3. **Surface the 7 §7 product questions** for Mike as decisions (they gate schema/UX shape of several PRs). 4. **If green-lit:** concrete scaffold plan — worktree name (e.g. `feature/authors-optimization`), the epic brief + ordered child briefs, and their dependency edges (PR5→6, PR7 needs 2+6, PR9 needs 3+8, PR10 needs 7/8/9). ## Recommendation (refine daemon) **BUILD.** This is a verified, self-sequencing epic, not a sketch — worth scaffolding as an epic + PR child briefs in a dedicated worktree. PRs 1–4 are safe independent quick wins that can ship in days. ## Constraints - **Read-only exploration.** No code changes. Actually creating the epic/child briefs + worktree is a follow-on once green-lit (orchestrator owns dispatch + worktree creation). ## Open question (operator — fold before planned) Green-light scaffolding the implementation epic now (epic + PR child briefs in a dedicated worktree), or stop at this assessment for now? Default if unanswered: hold at the assessment/recommendation (do not auto-scaffold an epic without the operator's go).

The /authors-optimization docs are an execution-ready, adversarially-verified 10-PR roadmap (perf refactor to kill a 338ms filesort + proximity search + quality typeahead + followed-only + favorites/settings), not a sketch. Recommendation is BUILD. Do you want me to green-light scaffolding the implementation now — an epic brief + child briefs per PR in a dedicated worktree — or stop at this assessment for now?

Refine daemon read the master report (`docs/authors-optimization/README.md`) 2026-07-04. **What it is** — a complete optimization + feature design for the `/authors` page: - **Perf/data-model foundation (doc 10):** `/authors` location filter is 338.7ms/page on dense locations (Dallas = 188K pivot rows) — it filesorts a pivot-sourced candidate set by a column on another table. Fix: denormalize sort keys + `is_visible` onto the 7.9M-row `location_reddit_user` pivot, add 3 composite covering indexes, flip the query pivot-first → sub-5ms. - **Proximity search (doc 20):** geo B-tree `(lat,lng)` index → city-centric radius (0/10/25/50/100 mi), quality-gated, capped to 64 nearest, cached. - **Location quality (doc 30):** `locations.authors_count` floor (default 5) → clean typeahead (21.8K of 206K kept). - **Followed-only filter (doc 40):** reuse warm 60-min followed-users cache + `whereIntegerInRaw`. - **Favorite locations + /settings (doc 50):** `Location` adopts Markable; new `/settings` page; reuse `users.location_id` as home. - **Frontend/UX (docs 60/70):** composite location chip, Followed pill, typeahead rebuild, star-a-location, /settings chrome. **Maturity** — execution-ready, high quality: - **Adversarially verified** — perf/SQL/data-model core independently checked (3 load-bearing corrections applied + folded into the roadmap); independent UX pass resolved cross-doc conflicts canonically in README §0 (governs). - **Sequenced 10-PR roadmap** (§4) with effort/risk/dependencies; consolidated migration+index list (§5, ALGORITHM per DDL); risk register (§6); validation plan (§8 — all perf numbers are *derived*, validate on prod after each index lands). - **7 genuine open product questions for Mike** (§7): quality-floor magnitude (5 vs 10), quality-on-by-default, settings route name, distance-vs-karma proximity ranking, reuse `users.location_id` vs new column, FK hardening, legacy cache-key cleanup. **Recommendation — BUILD IT.** This is a verified, self-sequencing epic, not a sketch. Structure: an **epic brief** ("/authors optimization") with **child briefs per PR** matching §4's roadmap, in a **dedicated worktree**. Sequencing: PRs 1–4 = safe independent quick wins (ship first, any order); PR5 → PR6 = durable pivot refactor (indexes build once over populated data); PR7 needs PR2+PR6; PR8 (Followed) independent; PR9 needs PR3+PR8; PR10 = frontend layer over 7/8/9. Gate: the 7 §7 questions should be answered before/at the start of the PRs that depend on them (several set schema/UX shape).

**Operator ask (2026-07-04, on brief #238):** "Please issue a follow up brief to explore the docs that are coming along with authors-location-optimization-plan to see what it's even doing/about and if we should build a brief to address/build out what it describes in a worktree." **Context:** The `authors-location-optimization-plan` branch (subject of #238, merging its design docs to deploy) carries 9 design docs under `docs/authors-optimization/`. This brief explores what they describe and recommends whether/how to build it out. Follows #225 (worktree survey) → #238 (merge-readiness) campaign.