mirror of
https://github.com/MadsLorentzen/ai-job-search.git
synced 2026-09-17 00:26:26 +00:00
feat(notion-sync): one-way read-only pipeline view in Notion via MCP (#169)
Adds /notion-sync per the conditions agreed in discussion #166: tool-agnostic sync contract with Notion as the in-tree reference binding, silently optional (covers unconfigured, headless, and unauthenticated states), read-only toward the repo with the gitignored sync-state file as its only local write, write-once page bodies, documents sync as filenames only. Complements /html-report: deep local dashboard vs glanceable anywhere-view.
This commit is contained in:
Adri
@@ -0,0 +1,147 @@
|
||||
# /notion-sync - Push Ranked Jobs and Applications to a Notion Database
|
||||
|
||||
You are publishing a **read-only view** of the job search into the user's Notion workspace: one database row per job, with a detailed page per shortlisted match. The repo files stay the system of record - `job_scraper/seen_jobs.json` owns scraped/ranked jobs and `job_search_tracker.csv` owns applications. Notion is a disposable presentation layer on top of them; nothing ever syncs back.
|
||||
|
||||
This command requires the **Notion MCP server** (OAuth). It reads state, upserts pages, and stops - it never ranks, applies, or edits repo files. Notion is the in-tree reference binding; the sync contract itself is tool-agnostic (see "Adapting to Another Tool" at the end - only the two sections marked *(Notion binding)* are tool-specific).
|
||||
|
||||
## Lane: `/html-report` vs `/notion-sync`
|
||||
|
||||
Both present the same tracker data; they own different moments. `/html-report` is the **deep-review lane**: a self-contained offline dashboard with charts and a filterable table, regenerated at your desk. `/notion-sync` is the **glanceable lane**: the current state of the pipeline, reachable anywhere Notion runs (desktop, web, phone). They compose rather than compete - after `/outcome` records a result, re-run either or both to refresh the views.
|
||||
|
||||
Follow these steps **in order**.
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Parse Input
|
||||
|
||||
`$ARGUMENTS` may contain:
|
||||
|
||||
- Nothing → sync ranked jobs with score ≥ 60 (Good Fit and above) plus every tracked application
|
||||
- `--min-score <N>` → override the score threshold
|
||||
- `--all` → sync every ranked job regardless of score
|
||||
- `--rebuild` → re-fetch and rewrite page bodies too (see Step 5 - normally bodies are write-once)
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Preflight the Connection *(Notion binding)*
|
||||
|
||||
The command is **silently optional**: when the destination is not reachable, the outcome is one clear message and a clean exit - nothing else in the framework notices this command exists.
|
||||
|
||||
1. Check that Notion MCP tools are available in this session (tool names starting with `mcp__notion__` or similar). Determine this from the session's own tool list **only** - never by running shell commands like `claude mcp list`, which would interrupt the user with a permission prompt before the graceful exit. If the tools are not available, stop and tell the user how to connect:
|
||||
> Notion MCP isn't connected. Run `claude mcp add --transport http notion https://mcp.notion.com/mcp`, then start a **new session** (servers added mid-session are only picked up on restart), run `/mcp` there to complete the OAuth login, and re-run `/notion-sync`.
|
||||
2. Verify the connection with one cheap call (e.g. a workspace search). An auth error → tell the user to re-authenticate via `/mcp` and stop. Never retry in a loop.
|
||||
3. The Notion MCP server is interactively authenticated, so "connected but not authenticable right now" (expired OAuth, headless/CI context where the login flow cannot run) gets the same graceful exit as "not configured": state the reason in one line and stop. This includes the configured-but-unauthenticated state where the server exposes only its auth handshake and no data tools - **never initiate the OAuth flow from this command and never ask whether to authenticate now**; the one line points at `/mcp` and the command ends there. Authenticating is the user's move, made outside this command.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Build the Sync Set (local data only - no external calls yet)
|
||||
|
||||
Validate the cheap, local precondition before creating anything external. A run with nothing to sync must exit with **zero side effects** - no database created, no state file written.
|
||||
|
||||
1. Read `job_scraper/seen_jobs.json` and `job_search_tracker.csv` (either may be missing).
|
||||
2. Select `seen_jobs.json` entries with status `ranked` whose `rank_score` meets the threshold from Step 0. `--all` lifts the threshold entirely.
|
||||
3. Every tracker row joins the sync set (an applied-to job always syncs, ranked or not), matched to `seen_jobs.json` entries case-insensitively on company + role where possible. Tracker rows with no `seen_jobs.json` entry sync too - build their Key as `<company>_<role>` lowercased with underscores.
|
||||
4. **Status precedence:** the tracker wins. A job that is `ranked` in `seen_jobs.json` but `interview` in the tracker syncs as `interview`. Jobs only in `seen_jobs.json` keep their stored status.
|
||||
5. **If the sync set is empty** (no ranked entries meet the threshold and there are no tracker rows), say "Nothing to sync - run `/scrape` and `/rank` first" (or, when jobs exist but all score below the threshold, say so and suggest `--min-score`/`--all`) and **stop**.
|
||||
6. State the counts before touching the destination: how many rows will be created or checked, and the threshold in effect.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Load Sync State and Locate the Database *(Notion binding)*
|
||||
|
||||
1. Read `job_scraper/notion_sync.json`. Structure:
|
||||
```json
|
||||
{ "database_id": "...", "database_url": "...", "last_sync": "YYYY-MM-DD" }
|
||||
```
|
||||
2. If it exists, verify the database id still resolves in Notion. If the database was deleted, treat this as a first run.
|
||||
3. **First run:** search the workspace for a database named "Job Search Pipeline". If none exists, ask the user where to create it (top-level page or an existing page they name), then create it with exactly these properties:
|
||||
|
||||
| Property | Type | Values / notes |
|
||||
|----------|------|----------------|
|
||||
| Name | title | `<Role> — <Company>` |
|
||||
| Company | rich text | |
|
||||
| Score | number | 0-100 from `rank_score` |
|
||||
| Verdict | select | Strong Fit / Good Fit / Moderate Fit / Weak Fit / Poor Fit |
|
||||
| Status | select | ranked / applied / interview / offer / hired / rejected / no response / withdrawn / expired |
|
||||
| Fit | select | high / medium / low (scraper quick-fit) |
|
||||
| Deadline | date | omit when unknown |
|
||||
| First seen | date | |
|
||||
| Ranked | date | `rank_date` from `seen_jobs.json`; omit when not ranked |
|
||||
| Applied on | date | tracker `date` column; omit when not in the tracker |
|
||||
| Channel | select | tracker `channel` column (e.g. portal / email / referral); options grow as values appear |
|
||||
| CV file | rich text | tracker `cv_file` column - the filename only, never document content |
|
||||
| Cover letter | rich text | tracker `cover_letter_file` column - the filename only, never document content |
|
||||
| URL | url | posting URL |
|
||||
| Key | rich text | the job's key in `seen_jobs.json` - dedup anchor, never edited by hand |
|
||||
|
||||
The tracker-sourced properties (Applied on, Channel, CV file, Cover letter) stay empty for jobs that have no tracker row - they fill in once `/outcome` records the application. Only filenames ever sync; document contents stay local.
|
||||
|
||||
4. **Existing database with missing properties:** if the located database predates a schema addition (a property from the table above does not exist), add the missing properties to the database before upserting. Never remove or retype existing properties.
|
||||
5. Write `job_scraper/notion_sync.json` with the database id and URL. This file is personal state and is gitignored - never commit it.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Upsert Database Rows
|
||||
|
||||
For each job in the sync set:
|
||||
|
||||
1. Query the database for a page whose `Key` equals the job's key.
|
||||
2. **No match** → create the page with all properties from the Step 3 table, then write its body (Step 5).
|
||||
3. **Match** → update **properties only**: Status, Score, Verdict, Deadline, Ranked, Applied on, Channel, CV file, Cover letter. Properties are the always-current surface (bodies are write-once), so tracker updates recorded by `/outcome` reach the destination exclusively through them. Do not touch the page body - the user may have added their own notes there, and clobbering them breaks trust in the whole view. (`--rebuild` is the sole exception.)
|
||||
4. Never delete or archive pages, even for jobs that turned `expired` - set Status to `expired` instead. Rows the user added to the database by hand (no `Key` value) are invisible to this command.
|
||||
|
||||
Batch politely: if the MCP server rate-limits, back off and continue; report any page that failed rather than retrying indefinitely.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Write the Detail Page (new pages only)
|
||||
|
||||
The page body is what makes a row worth clicking. Build it **only from stored data and actually fetched content**:
|
||||
|
||||
1. **Fit summary** - a short section from `seen_jobs.json` fields: score, verdict, quick-fit level, first-seen and ranked dates. If the job is in the tracker, add the application timeline (date applied, channel, current status, dated notes from the `notes` column) and name the submitted documents from `cv_file`/`cover_letter_file` (filenames only - the documents themselves never sync).
|
||||
2. **The posting** - WebFetch the job URL and write a readable digest: what the role is, key requirements, practical details (location, deadline, salary if stated). If the fetch fails or redirects to a listing page, write "Posting no longer available (checked YYYY-MM-DD)" - **never reconstruct a posting from memory**.
|
||||
3. **Links** - the posting URL; if `documents/applications/<company>_<role>/` exists locally, name it as the local archive path (plain text - the destination cannot link into the filesystem).
|
||||
|
||||
Keep the page under ~40 blocks; this is a briefing, not a mirror of the posting.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Report
|
||||
|
||||
```
|
||||
## Pipeline Sync - YYYY-MM-DD
|
||||
|
||||
Database: <database_url>
|
||||
Synced <N> jobs (threshold: score ≥ <T>): <C> created, <U> updated, <S> unchanged, <F> failed.
|
||||
|
||||
| | Title | Company | Status | Score |
|
||||
|---|-------|---------|--------|-------|
|
||||
| ✚ | ... | ... | ranked | 78 |
|
||||
| ↻ | ... | ... | interview | 71 |
|
||||
```
|
||||
|
||||
List failures with their error and the suggestion to re-run - the upsert is idempotent, so a re-run only touches what failed. Update `last_sync` in the sync-state file.
|
||||
|
||||
Remind the user once (first run only): the repo files remain the source of truth - edits made in the destination never flow back, and `/outcome` is still how application results get recorded.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
1. **One-way, always.** Destination content never flows back into `seen_jobs.json`, the tracker, or any repo file. This command reads repo state and writes the destination - both repo files are read-only to it, and the gitignored sync-state file is its **only** local write.
|
||||
2. **Idempotent upsert on `Key`.** Re-running creates nothing twice; matching is on the stored key, never on fuzzy title comparison.
|
||||
3. **Page bodies are write-once.** Property updates keep rows current; bodies belong to the user after creation. Only `--rebuild` may rewrite them, and it says so before doing it.
|
||||
4. **Never fabricate.** A dead posting URL gets an explicit "unavailable" note, not a reconstruction. Every page claim traces to stored state or fetched content.
|
||||
5. **Job data only.** The candidate profile, behavioral notes, and evaluation framework never sync - this is a pipeline view, not a profile export.
|
||||
6. **Documents never leave the machine.** CVs and cover letters sync as **filenames only** - never upload, attach, or embed the documents themselves, nor HTML/text renditions of their content, into the destination. The local repo and `documents/applications/` archive are the only home for application documents; the row's page names them so the user knows what to open locally.
|
||||
|
||||
---
|
||||
|
||||
## Adapting to Another Tool (forks)
|
||||
|
||||
The sync contract is tool-agnostic; only the two sections marked *(Notion binding)* are tool-specific. A fork targeting a different destination (Airtable, Google Sheets, Linear, ...) keeps Steps 0, 2, 4, 5, and 6 and every Important Rule unchanged - build the same sync set, upsert on the same `Key`, keep bodies write-once and documents local - and swaps only:
|
||||
|
||||
- **Step 1** (connection preflight) for the target tool's MCP server or access check, keeping the silently-optional bar: not configured or not authenticable both end in one message and a clean exit
|
||||
- **Step 3** (locate/create the database) for the equivalent container in the target tool, using the same property table and a renamed sync-state file
|
||||
|
||||
Like the portal skills, tool bindings beyond this Notion reference live in forks, where their maintainers can test them against a live workspace.
|
||||
@@ -21,6 +21,7 @@ venv/
|
||||
# Personal data (never commit these)
|
||||
salary_data.json
|
||||
job_scraper/seen_jobs.json
|
||||
job_scraper/notion_sync.json
|
||||
job_scraper/*.md
|
||||
*_BehavioralReport.pdf
|
||||
linkedin_Profile.pdf
|
||||
|
||||
@@ -133,10 +133,11 @@ This runs the full workflow: evaluate fit, draft CV + cover letter, review with
|
||||
|
||||
## Other commands
|
||||
|
||||
`/setup`, `/scrape`, and `/apply` form the core workflow. Eight more commands extend it once your profile is in place:
|
||||
`/setup`, `/scrape`, and `/apply` form the core workflow. Nine more commands extend it once your profile is in place:
|
||||
|
||||
- **`/interview`** preps you for a scheduled interview on a tracked application. It builds a stage-specific prep pack from the application's archive (the exact posting, the CV and cover letter the interviewer actually read, feedback recorded from earlier rounds), researches the company and interviewers with a verify-before-use rule, maps likely questions to your STAR examples, and offers a mock interview following the roleplay protocol in `07-interview-prep.md`. Gaps get honest bridge answers, never invented experience.
|
||||
- **`/outcome`** records what happened to an application - interview stages, offers, rejections, silence. It archives the submitted CV, cover letter, and posting text into `documents/applications/<company>_<role>/`, keeps `outcome.md` in the format `/setup` Path A parses, and updates the tracker. Once a few applications resolve, it points you back to `/setup` to calibrate the fit framework from what actually got interviews.
|
||||
- **`/notion-sync`** publishes a one-way, read-only view of the pipeline into a Notion database via the official Notion MCP server (OAuth, no API keys) - one row per ranked job plus every tracked application, with a write-once briefing page per row. The repo files stay the system of record: nothing syncs back, and documents sync as filenames only. Complements `/html-report`: that is the deep offline dashboard you regenerate at your desk; this is the glanceable live view from anywhere Notion runs (desktop, web, phone).
|
||||
- **`/rank`** bridges `/scrape` and `/apply`: it batch-scores all newly scraped postings against the fit framework (parallel agents fetch each posting and score the five evaluation dimensions) and returns a ranked shortlist with honest per-job strengths and gaps. Deal-breakers veto, deadlines get urgency flags, dead postings get marked expired. Pick a number and it hands off to the full `/apply` workflow.
|
||||
- **`/expand`** enriches your profile by scanning public sources you've already linked in it (GitHub repos, portfolio site, Kaggle, Google Scholar) and looking up syllabi for named courses and certifications. Discovered competencies are added to your profile with a source tag. Useful right after `/setup` to surface skills that documents alone don't make explicit.
|
||||
- **`/upskill`** analyzes the gap between your profile and your tracked job postings (or a single posting via `/upskill <URL>`). Produces a prioritized heatmap of skill gaps and a learning plan with web-searched study resources and time estimates. Useful for career planning between applications.
|
||||
@@ -162,6 +163,7 @@ ai-job-search/
|
||||
│ │ ├── outcome.md # /outcome record application results, archive materials
|
||||
│ │ ├── interview.md # /interview stage-specific prep pack + mock interview
|
||||
│ │ ├── html-report.md # /html-report generate application tracker dashboard
|
||||
│ │ ├── notion-sync.md # /notion-sync one-way pipeline view in a Notion database
|
||||
│ │ └── reset.md # /reset wipe profile data or documents folder
|
||||
│ ├── skills/
|
||||
│ │ ├── job-application-assistant/ # Core application skill
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
"""Guards for the /notion-sync command spec.
|
||||
|
||||
The command is a markdown spec (the spec IS the implementation), so these
|
||||
tests pin the invariants that would break silently: the header format that
|
||||
lint_skills.py enforces, the gitignore entry that keeps the personal sync
|
||||
state out of version control, and the privacy rule that forbids syncing
|
||||
document content to Notion.
|
||||
"""
|
||||
import subprocess
|
||||
import sys
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import yaml # noqa: F401 - only probing availability for the lint integration test
|
||||
_HAVE_YAML = True
|
||||
except ImportError:
|
||||
_HAVE_YAML = False
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent
|
||||
COMMAND = REPO / ".claude" / "commands" / "notion-sync.md"
|
||||
GITIGNORE = REPO / ".gitignore"
|
||||
|
||||
|
||||
class NotionSyncCommandSpec(unittest.TestCase):
|
||||
def test_command_file_exists_with_lint_compliant_header(self):
|
||||
self.assertTrue(COMMAND.is_file(), "command spec missing")
|
||||
first_line = COMMAND.read_text(encoding="utf-8").splitlines()[0]
|
||||
self.assertTrue(
|
||||
first_line.startswith("# /notion-sync"),
|
||||
f"header must start with '# /notion-sync' (lint_skills.py enforces it), got: {first_line!r}",
|
||||
)
|
||||
|
||||
def test_command_file_is_substantive(self):
|
||||
text = COMMAND.read_text(encoding="utf-8")
|
||||
for section in ("## Step 0", "## Step 4", "## Important Rules"):
|
||||
self.assertIn(section, text, f"spec lost its {section!r} section")
|
||||
|
||||
def test_personal_sync_state_is_gitignored(self):
|
||||
self.assertIn(
|
||||
"job_scraper/notion_sync.json",
|
||||
GITIGNORE.read_text(encoding="utf-8"),
|
||||
"notion_sync.json is personal state and must never be committable",
|
||||
)
|
||||
|
||||
def test_privacy_rule_documents_never_sync(self):
|
||||
text = COMMAND.read_text(encoding="utf-8")
|
||||
self.assertIn(
|
||||
"never upload, attach, or embed",
|
||||
text,
|
||||
"spec lost the rule that CV/cover-letter content never syncs to Notion",
|
||||
)
|
||||
|
||||
@unittest.skipUnless(
|
||||
_HAVE_YAML,
|
||||
"PyYAML not installed (the CI Python-test job omits it; the lint job runs lint_skills.py directly)",
|
||||
)
|
||||
def test_lint_skills_passes(self):
|
||||
result = subprocess.run(
|
||||
[sys.executable, str(REPO / "tools" / "lint_skills.py")],
|
||||
cwd=REPO,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
self.assertEqual(result.returncode, 0, f"lint_skills.py failed:\n{result.stdout}{result.stderr}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user