From 9d30582599223755a5592a46524c106c030ccfd4 Mon Sep 17 00:00:00 2001 From: Wolf Date: Sun, 4 Oct 2026 10:10:38 +0200 Subject: [PATCH] Make the flow the owner's architecture document, and move summarise after the ranking on the top of the feed Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 4 ++++ docs/{ranking-flow.md => architecture.md} | 23 +++++++++++++++-------- 2 files changed, 19 insertions(+), 8 deletions(-) rename docs/{ranking-flow.md => architecture.md} (84%) diff --git a/CLAUDE.md b/CLAUDE.md index bb9fe11..ff3049e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,3 +40,7 @@ Phone and UI patterns come from `../news` (`newsdesk/web/templates/index.html`, # Rule: A larger rework is planned first, as a doc in `docs/` committed on main with work packages that own disjoint files, then built by Opus and Sonnet agents in parallel worktrees and merged into main by the planner. The plan is folded into `decisions.md` and deleted when the work lands. + +# Rule: + +`docs/architecture.md` is the owner's document: the flow from board to feed and the key decisions about it, marked today, decided or open. Keep it short and update it when a key decision is made or lands. The detailed reasoning goes into `decisions.md`. diff --git a/docs/ranking-flow.md b/docs/architecture.md similarity index 84% rename from docs/ranking-flow.md rename to docs/architecture.md index c2e8bfc..46e57cf 100644 --- a/docs/ranking-flow.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ -# Ranking flow +# Architecture -This is how a role gets from a board to the Roles feed, for one search agent. It is the shared picture to change the flow against. Each stage says what the code does **today**, what was **decided** on 2026-10-04 (not built yet) and what is still **open**. +This is the owner's document: how a role gets from a board to the Roles feed, for one search agent, and the key decisions about that flow. It is the picture any change is made against. `decisions.md` is the detailed log behind it. Each stage says what the code does **today**, what was **decided** (since 2026-10-04, not built yet) and what is still **open**. Names: **fetch text** is the second HTTP read of a role's own page, with no model (the code calls it `enrich`). **Extract**, **judge** and **summarise** are the model calls. @@ -19,11 +19,14 @@ Names: **fetch text** is the second HTTP read of a role's own page, with no mode 3 Fetch text ─ the role's own page, for cut roles without text → embed, rescore │ ▼ - 4 Model pass (Haiku), the whole cut ─ extract → rescore → judge, then summarise + 4 Model pass (Haiku), the whole cut ─ extract → rescore → judge │ ▼ 5 Feed ─ two orders: "what I'm looking for" (final score) and "what fits me" (CV match) front-end filters narrow either order + │ + ▼ + 6 After the ranking ─ summarise the top of the feed ``` ## 1 Fetch @@ -70,22 +73,20 @@ Without the Where lines, about four in five model reads go to roles outside DK, ## 4 Model pass -**Today.** These three stages run on Haiku. Each limit is a count *and* a minimum score: at most N roles, each scoring at least X. The count is a ceiling and the score is the real stop. +**Today.** Extract and judge run on Haiku (summarise is in section 6). Each limit is a count *and* a minimum score: at most N roles, each scoring at least X. The count is a ceiling and the score is the real stop. - **Extract** reads at most 500 roles scoring at least 0.55. It fills location, remote area, seniority, languages and deadline. A rescore follows so the gates see these columns. -- **Summarise** reads at most 30 roles scoring at least 0.65, plus the roles you saved or liked. - **Judge** reads at most 150 roles scoring at least 0.55, plus the 50 closest to the CV that those leave out. It scores skills, experience and career 0 to 100, plus a verdict on each must-have. These are weighted 30/25/30 into `cv_score`. -**Decided.** One depth: the analysis cut is the only gate, and every model stage reads all of it. A second score inside the cut would defeat the purpose of the cut. The order is: +**Decided.** One depth: the analysis cut is the only gate, and every scoring model stage reads all of it. A second score inside the cut would defeat the purpose of the cut. The order is: 1. **Extract** reads the whole cut. It is the small, fast call (about 1.5 s a role on the live backend). 2. A rescore applies the gates to what extract filled, mainly location and remote area. The cut is the same gate as before, recomputed with better facts. A role that a rescore moves into the cut is extracted on the next pull. 3. **Judge** reads the cut as recomputed (about 6 s a role). -4. **Summarise** is an afterburner. It does not feed any score. The form wording for the sizes becomes "at most N, each scoring at least X", in place of "the best N down to a score of X". -**Cost.** Every model read happens once per role (judge once per role and CV), so a larger cut costs mostly a one-off catch-up. With a cut of about 650 roles, that catch-up is about 16 minutes of extract and about an hour of judge on the live backend (`claude_code`, the subscription, so no per-token bill). After it, each pull reads only the roles new to the cut. +**Cost.** Every model read happens once per role (judge once per role and CV), so a larger cut costs mostly a one-off catch-up. With a cut of about 650 roles, that catch-up is about 16 minutes of extract and about an hour of judge on the live backend (`claude_code`, the subscription, so no per-token bill). After it, each pull reads only the roles new to the cut. The recurring cost is a re-judge: changing the CV, a prompt, or the like or dislike text changes every judgement's input, so the whole cut is judged again, about an hour for 650 roles. A changed posting text re-judges that role only. **Decided: extract and judge stay two calls.** Extract needs no CV and its location and remote answers feed the rescore before judge reads anything. Judge works per agent and role, with the CV in the system prompt. @@ -100,3 +101,9 @@ The form wording for the sizes becomes "at most N, each scoring at least X", in - What the final score is made of: whether fit stays at 0.6, and whether it reads extracted facts such as seniority. - Location in the feed: does the agent's Where keep hiding roles, or is location only a front-end filter on top of the analysis cut? - A follow-everywhere company group. It is shown as a feed filter, skips the Where lines in the cut, and is fetched across all countries without fetch terms. It would replace three things: favourite as a workaround, All countries and All roles. + +## 6 After the ranking + +**Today.** Summarise reads at most 30 roles scoring at least 0.65, plus the roles you saved or liked. It runs inside the model pass, on the same score. + +**Decided.** Summarise is not part of the preparation or the scoring. It runs once the final scores are set, on the top of the feed by the final score, with its own size on the form (50 to start, as a slider). Roles you saved or liked are summarised too, as today.