diff --git a/docs/decisions.md b/docs/decisions.md index a619e81..dac09b1 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -190,8 +190,12 @@ What was decided for roledesk and the one reason for each. The longer reasoning **`seniority` is read from the title until extract has read the role.** Extract had never run, so the column was empty on all 33,881 open roles and a seniority filter or gate had nothing to read. `seniority.from_title` matches whole words in English, Danish, Swedish, German and French and gives 43% of open roles a level. "X Manager" is a level only where it clearly names someone who runs a team, since a product or account manager is an individual contributor; intern wins over a boss named in the title. Known mistakes: "VP" is always exec, "Field CTO" and "Chief of Staff" get none, "Account Director" is director. Extract overwrites the title's level, a level a board states wins over both. +**Seniority is a ladder of rungs with two tracks.** The first vocabulary was one line (intern to exec) and put a Principal below a Team Lead, and a Staff engineer below any manager, while the owner counts a Principal Solutions Engineer as very senior. From `staff` up, each rung pairs an individual contributor's level with a people lead's, as big tech firms grade them: `staff` with `lead` (a team lead) and `manager`, `principal` (also Senior Staff) with `senior_manager` (also Associate Director, AVP), `distinguished` (Senior Principal, Distinguished, Technical Fellow) with `director` (also Head of), then `exec`. `LADDER` in `app/models.py` gives each word its rung and track, and `roles.seniority` stays one column of words, so gates, `extract` and the host tables work on words. `lead` changed meaning: "Tech Lead", "Lead Engineer" and "Marketing Lead" are `staff`, and only a team lead, supervisor or shift lead is `lead`. In a title, a people level wins over a grade on its own rung, and a grade above it lifts it one rung ("Principal Engineering Manager" is `senior_manager`); a slash is "or" ("Senior/Staff Engineer" is `staff`). Principal sits one rung above Staff, although at some firms it is the top individual grade and at others a senior manager's peer. Migration 25 cleared the model levels the split made ambiguous (staff, lead, manager, director), and prep `VERSION` 2 mapped every open role again. On 2026-09-30 that gave, over 19,230 open roles without copies: staff 1,756, principal 535, distinguished 23, lead 222, manager 736, senior_manager 312, director 883, exec 101, none 9,565. + **A filter that most roles cannot answer keeps the ones that do not say.** The Seniority filter keeps roles with no level unless its box is unticked, since 57% have none. The Pay filter leaves out roles that state no pay unless its box is ticked, since 87% state none and the filter would otherwise do nothing. `GET /api/roles/facets` counts each level and pay state under the other filters, so the rail shows what a click would add or lose. +**The Seniority filter is a range of rungs and a track, not a button per level.** "At least Staff" is a range, and "manager roles only" is the Staff rung on the people track, so From, To and Track (Both, Individual, People) cover what the buttons did. Only a scattered pick such as junior and director is lost. `GET /api/roles` and `/facets` take `level_from`, `level_to` (names in `RUNGS`) and `track`, which `levels_between` turns into the list of words the store filters on. The rungs below Staff have no track and pass either. The facets still count per word; the rail sums them per rung for the track chosen, and names a rung after the track ("Staff / Manager" with both). The page carries `RUNGS` and `LADDER` as JSON, so the words live in `models.py` only. An old `?seniority=` address is ignored. + **Company and Place are chips picked from suggestions.** Only a suggestion becomes a chip, so a filter names something the database holds: a company key, a place token. `GET /api/suggest/companies` and `/api/suggest/places` fold what is typed and match word prefixes, computed per request over 743 companies and 5,600 place lines. `app/static/chips.js` is the input, with no dependency; its tests run with `node --test tests/js/*.test.mjs`. **A filter is a history entry, text is not.** Filters used to replace the entry, so back left the page. Now each filter set pushes one and back takes it off: a tag, the period, a chip, a level, a company. The search box and typed text replace, or back would step through a search a letter at a time, and so do the agent and the order. Every pushed entry carries the address it was pushed over, so closing the reader or taking a company off is `history.back()` when the entry under it is that list, and a new entry otherwise. diff --git a/docs/open.md b/docs/open.md index 2db9368..036c2ab 100644 --- a/docs/open.md +++ b/docs/open.md @@ -5,7 +5,7 @@ What is left after the phone rework of 2026-09-25, for whoever picks the repo up - **The checkout moved.** `CLAUDE.md`, `README.md`, `desk/README.md` and the refresh commands assume `../boilerplate` and `../news` beside the checkout. Keep them beside it in the sandbox or change the paths. `.venv` holds absolute paths, so `uv sync --all-extras` again after the move. - **The boilerplate moved on.** Since roledesk's last refresh (`77052a8`, the schedules fix) it has `4573f6d` (the kit: the layout patterns every app built for itself, as classes) and `1679e88` (deploy from a WSL checkout, the sandbox setup). Refresh `deploy/` and `pipeline/` with `git archive`, and see whether `app/static/app.css` should use the kit's classes instead of its own copies of the same rules. - **Summarising is off** until the switch under Runs (default `summarise.enabled: false`) is used, and needs a model backend, as extract does. The Summarise button on a read page works either way once a backend is configured. -- **The owner's agent has no rule on seniority.** Fit compares subject, not level, so an individual contributor's posting ranks beside a head's. `seniority` is read from the title since 2026-09-29 and filled for 14,646 of 33,881 open roles; a prefer gate on `manager`, `director`, `exec` and `lead` would lift the leadership roles, and extract fills the rest. +- **The owner's agent has no rule on seniority.** Fit compares subject, not level, so an individual contributor's posting ranks beside a head's. Since 2026-09-30 the level is a rung on a ladder with two tracks (`LADDER` in `app/models.py`), filled for half of open roles; a prefer gate still names words (e.g. `principal`, `senior_manager`, `distinguished`, `director`, `exec`). A gate on "at least a rung" would read as the rail's filter does. Extract fills the rest. - **Votes do not train fit.** A vote only moves the rank at read time. Feeding votes into the prompt vectors is worth doing once there are a few hundred. - **76 companies are read by hand**, on the Watchlist with a careers link opened on 2026-09-29: 35 `unread`, 10 `robots`, 9 Teamtailor ones without a career host, 8 `group`, 7 `blocked`, 4 `gone`, 3 `key`. The remaining readers are planned in `docs/plan-hosts-wave-2.md`. - **The hosts added on 2026-09-29 were read from this machine only.** Every Workday tenant is behind Cloudflare; read one Workday and one SuccessFactors board from the deployed server before relying on them. diff --git a/docs/plan-seniority.md b/docs/plan-seniority.md deleted file mode 100644 index 6c5efb9..0000000 --- a/docs/plan-seniority.md +++ /dev/null @@ -1,69 +0,0 @@ -# Plan: seniority as a ladder with two tracks, filtered by range - -Planned 2026-09-30. It is folded into `decisions.md` and deleted when it lands. - -## What the owner asked for - -1. **Seniority is real seniority, not only management.** A Principal Solutions Engineer is very senior, and a Staff engineer is on a par with a manager. The filter must rank individual contributors and people leads on one ladder. -2. **A range instead of level buttons**, e.g. "at least Staff", while still allowing a search for manager roles only, as opposed to senior individual contributor roles. - -The owner agreed on 2026-09-30 to the ladder below, including Principal one rung above Staff and "Marketing Lead"-style titles as individual contributors. - -## Where it stands - -`roles.seniority` is one of intern, junior, mid, senior, staff, lead, manager, director, exec. Read as a ladder, it puts a Principal below a Team Lead. Open roles on 2026-09-30: - -| Level | Roles | What it holds | -|---|---|---| -| staff | 1,589 | 1,115 Staff, 224 Senior Staff, 495 Principal, 18 Senior Principal | -| lead | 1,398 | 206 team leads and supervisors, 72 tech leads, the rest "Lead X" and "X Lead" | -| manager | 1,109 | 258 Senior Managers, 360 Engineering Managers | -| director | 1,002 | 633 Director, 362 Head, 35 Associate Director | -| none | 11,046 | 49% of 22,314 | - -`extract` has given a model level to 495 roles. No agent has a seniority gate. - -## Design - -**The ladder** is in `app/models.py` on main (step 0, done): `SENIORITIES`, `LEVELS`, `RUNGS`, `TRACKS`, `LADDER` and `levels_between(low, high, track)`. - -| Rung (`RUNGS`) | Individual contributor (`ic`) | People lead (`people`) | -|---|---|---| -| intern, junior, mid, senior | the level itself, no track | | -| staff | `staff`: Staff, Tech Lead, Lead X, X Lead | `lead`: Team Lead, Supervisor, Teamleiter; `manager` | -| principal | `principal`: Principal, Senior Staff | `senior_manager`: Senior Manager, Associate Director, AVP | -| distinguished | `distinguished`: Senior Principal, Distinguished, Technical Fellow, SAP Chief Expert | `director`: Director, Head of, Leiter | -| exec | | `exec`: VP, C-level, Managing Director | - -`lead` changes meaning, from any lead to a team lead. Rungs below `staff` have no track and pass either track filter. `roles.seniority` stays one column of words, so gates, `extract` and the host tables keep working on words. The range and the track become a list of words in `levels_between`, and the store's `seniority IN (...)` filter is unchanged. - -**Titles** (`app/seniority.py`). Highest rung wins, as today. On the same rung, people wins over individual contributor, and an individual-contributor grade on a people title lifts it one rung only when the grade is above the title's own rung: - -- "Staff Engineering Manager" is `manager`. -- "Principal Engineering Manager" is `senior_manager`. -- "Principal Product Manager" is `principal`, since a product manager is an individual contributor. -- "Senior Staff Engineer" is `principal`, and "Senior Principal" is `distinguished`. -- "Associate Director" and "Assistant Vice President" are `senior_manager`. "Senior Director" is `director`. -- "Fellow" alone is academic ("Research Fellow", "Postdoctoral Fellow"), so it stays unknown. "Technical Fellow" and "Engineering Fellow" are `distinguished`. -- "Lead Engineer", "Tech Lead", "Marketing Lead" and "Payroll Lead" are `staff`. "Team Lead", "Supervisor", "Shift Leader", "Teamleiter", "chef d'équipe" and "Assistant Store Manager" are `lead`. - -**Mapping again.** `app/prep/stage.py` `VERSION` goes to 2, so the next prep maps every open role again with the new title rules. A migration clears `seniority_model` where it is `staff`, `lead`, `manager` or `director`, since those words split and `extract` reads a role again once its model level is empty. It then sets `roles.seniority` to the first of model, stated and title, as `Store.write_prep` does, so the feed never shows a word the filter does not know. Take the next free migration number when merging, since another session adds migrations too. - -**Filter.** `GET /api/roles` and `/api/roles/facets` take `level_from`, `level_to` (names in `RUNGS`) and `track` (`ic` or `people`) instead of repeated `seniority`, plus `seniority_unknown` as today. `_feed_filters` turns them into `seniority=levels_between(...)`. A bad name is a 422 sentence. The facets keep counting per level word; the rail sums them per rung for the chosen track. - -**Rail.** The Seniority block becomes: -- **From** and **to**, two native selects of the rungs with counts. The rung label follows the track: Staff / Manager, Principal / Senior Manager, Distinguished / Director with both, the side's own name with one. -- **Track:** a three-button group, Both, Individual, People, as the existing `.seg` group. -- **"and roles with no level"** shown once a bound or a track is set, as today. - -The ladder reaches `roles.js` from the page (`pages.py` passes `RUNGS` and `LADDER` as JSON), so the words live in `models.py` only. An old address with `seniority=` is ignored. - -## Work packages - -| WP | Model | Builds | Owns | Needs | -|---|---|---|---|---| -| 0 Ladder | planner | `SENIORITIES`, `RUNGS`, `TRACKS`, `LADDER`, `levels_between` in `app/models.py`; the coverage test of `tests/test_seniority.py` marked xfail until A | done on main | | -| A Levels | Opus | Title rules for the new words and the split of `lead`, with the titles above as cases; host tables (Jobylon "lead" is `staff`, check Personio, SmartRecruiters, Recruitee); `extract`'s prompt describing the ladder and its tracks; prep `VERSION` 2; the migration; the xfail marker removed | `app/seniority.py`, `app/prep/hosts/*.py`, `app/prep/stage.py`, `app/jobs/extract.py`, `app/storage/schema.py`, `tests/test_seniority.py`, `tests/test_prep*.py`, `tests/test_extract.py`, `tests/test_storage.py`, `tests/test_ats_*.py` | 0 | -| B Range | Sonnet | `level_from`, `level_to`, `track` in `app/web/api.py`; the ladder in the page (`app/web/pages.py`, `app/templates/roles.html`); the rail's From, To and Track in `app/static/roles.js` and `app/static/app.css`; tests in `tests/test_web.py`; a screenshot at 390 px and at desktop width | those files | 0 | - -A and B share no file and run in parallel. They merge in the order A, then B. The planner then runs `app prep` on the live database, checks the counts per rung, folds this plan into `decisions.md` and deletes it.