santifer--career-ops/modes/titles.md

Mode: titles — Adjacent Job-Title Suggestions

Purpose

The scanner only surfaces what portals.yml title_filter.positive matches — and that list is written from the titles the user already knows to search for. The same job ships under many names (Solutions Architect / Forward Deployed Engineer / Customer Engineer), so the search is silently narrower than the CV justifies. This mode reads the CV and proposes adjacent titles the user isn't searching for yet — then, only after explicit confirmation, writes the accepted keywords into title_filter.positive so the very next scan casts the wider net.

patterns Step 1b makes the same kind of retargeting recommendation ("consider adding archetype X and reweighting portals.yml title_filter.positive"), but only after ≥5 progressed applications and only from interview-session signal. This mode is the day-zero, CV-driven complement. It is also the inverse of upskill: upskill finds skills missing for current targets; this finds new targets reachable from current skills.

Inputs

• cv.md — the only source of evidence for suggestions (required)
• config/profile.yml — archetypes (name / level / fit) for what's already targeted
• modes/_profile.md — target roles, framing, and any deal-breakers the user has recorded
• portals.yml — the current title_filter.positive (and negative) keywords
• Optional: if data/applications.md has ≥5 entries progressed beyond Evaluated, note which suggestions the outcome data supports (e.g. an axis that is already converting) — cross-reference patterns rather than duplicating its analysis.

The Three Axes

Classify every suggestion on exactly one axis, and say which:

• Lateral — same work, different label. The core recall win: the user already does this job; the market just posts it under a name they don't search for.
• Stretch — one level up or larger scope than the CV's strongest evidence. Plausible, but a hiring manager would probe the gap.
• Pivot — an adjacent function reachable from existing CV evidence (e.g. heavy client-facing delivery work → pre-sales engineering).

Output Contract (per suggestion)

For each suggested title, show exactly:

• Title — the market title as actually posted, not an invented hybrid
• Axis — Lateral / Stretch / Pivot
• CV evidence — 1–2 lines from cv.md quoted verbatim. If you cannot quote it, do not suggest it.
• Honest gap note — what a hiring manager would question; "none" is allowed for Lateral suggestions but must be earned
• Market-reality note — how common the title is, where it tends to be posted, seniority skew, or noise level

Aim for 5–10 suggestions, Lateral first. Fewer good suggestions beat a padded list — this system optimizes for quality, not quantity.

Filters (apply BEFORE showing suggestions)

1. Dedup against existing coverage. Mirror the matcher semantics in scan.mjs (buildTitleFilter / compileKeyword): the scanner lowercases both sides and keeps a job when any positive keyword is a case-insensitive substring of the title (2–3 letter keywords match on word boundaries instead). So drop any candidate title that an existing positive keyword already substring-matches — it is already covered, and suggesting it adds zero new recall.
2. Deal-breaker filter. Never suggest titles that violate the deal-breakers recorded in modes/_profile.md (e.g. "no people management" rules out Engineering Manager; "no on-site" rules out field roles). Titles matching title_filter.negative keywords are also off the table — the user already excluded them.
3. Never invent experience. Every suggestion must be traceable to quoted cv.md lines — the source-of-truth boundary applies to suggestions exactly as it does to CV content. Keywords get reformulated, never fabricated. If the evidence isn't in cv.md, ask the user; don't stretch a quote to fit.

Confirm Gate — Writing Accepted Titles (HARD RULE)

When the user accepts one or more suggestions:

1. Derive keywords, not raw titles. The filter matches substrings, so the keyword should be the shortest phrase that still identifies the role family ("Forward Deployed" covers Forward Deployed Engineer/Architect/Lead).
2. Attach a breadth warning to any substring-dangerous keyword: because matching is substring-based, a short or generic keyword floods the scan. Propose "Solutions Architect", never bare "Architect" — bare "Architect" would also match Data Architect, Enterprise Architect, Security Architect. If the user insists on a broad keyword, warn once and comply.
3. Skip keywords that duplicate existing coverage (same dedup rule as above); preserve the casing style already used in the user's portals.yml.
4. Show the exact YAML diff against portals.yml title_filter.positive before touching anything.
5. Never write to portals.yml without explicit user confirmation. "Show me the diff" is not a yes. Silence is not a yes.
6. portals.yml (user layer) is the only file this mode writes by default. This mode proposes no negative keywords — precision guards for noisy keywords are deferred to #1353's seniority-tier helper.
7. Separately-confirmed exception: accepted titles can additionally become fit: adjacent archetypes in config/profile.yml (an existing schema field — see config/profile.example.yml). Mention that this is possible, but do it only if the user asks — never write archetypes by default. When the user does ask, that write gets its own YAML diff and its own separate confirmation; never bundle the portals.yml and config/profile.yml writes into one confirmation.

After the Write

• Suggest /career-ops scan — the wider filter only pays off on the next scan.
• Suggest upskill scoped to a Stretch title the user liked, to see the gap map between the CV and that next-level target.

Error Handling

• cv.md missing → stop and point at onboarding (node doctor.mjs --json). There is no evidence base to suggest from, and inventing one is forbidden.
• portals.yml missing, or title_filter.positive empty → offer to create it from templates/portals.example.yml first, then re-run this mode. (An empty positive list means the scanner matches everything — nothing to broaden.)
• config/profile.yml or modes/_profile.md missing → hard stop: do not generate suggestions. Point at onboarding (node doctor.mjs --json) and stop, then re-run this mode once both files exist — the same fix-first-then-re-run behavior as a missing portals.yml above. Deal-breakers live in modes/_profile.md — suggestions generated without them can propose exactly what the user excluded.