Idea: /notion-sync — a read-only pipeline view in an external tracker (Notion as reference binding)

[AdriBarda]

Hi Mads! Sanity-check before opening a PR, since this involves a specific external tool.

What this operationalizes

The framework already writes rich pipeline state that nothing presents: /rank stores scores in seen_jobs.json, and /outcome writes every application to job_search_tracker.csv. Reading either away from a terminal is impractical — checking "which deadlines are close?" or "what did I apply to last week?" from a phone means opening a shell.

/notion-sync connects those two outputs to a portable presentation layer — a Notion database reachable anywhere Notion runs (desktop, web, mobile) — without modifying either file. It is read-only toward the repo and one-way toward Notion: nothing ever syncs back. The framework stays the brain; this is just a screen.

Changes

• .claude/commands/notion-sync.md — new slash command
• tests/test_notion_sync_command.py — Python guards (see below)
• README.md — command documented in "Other commands" and the file tree
• .gitignore — adds job_scraper/notion_sync.json (personal sync state, same rationale as job_search_tracker.csv)

What /notion-sync does

Reads seen_jobs.json + job_search_tracker.csv and upserts a "Job Search Pipeline" database via the official Notion MCP server (OAuth — no API keys, no dependencies; degrades to a clear "connect Notion MCP first" message when unconfigured).

• One row per ranked job (score ≥ 60 by default; --min-score / --all) plus every tracked application
• Idempotent upsert keyed on the seen_jobs.json key — re-runs create nothing twice
• Tracker status wins over stored status; tracker columns (Applied on, Channel, CV file, Cover letter) fill in once /outcome records an application
• Page bodies are write-once briefings — user notes never clobbered; properties are the always-current surface
• In-place schema migration when an existing database predates newer spec versions
• Documents never leave the machine — CV/cover-letter filenames only; no uploads, attachments, or content renditions

Isn't this the portal floodgate?

Fair concern: one tool's sync could invite every tool's sync. The spec handles it the way the repo handles portals:

• The sync contract (sync-set, upsert, precedence, write-once, privacy rules) is tool-agnostic
• Only Steps 1 and 3 bind to Notion; a fork for Airtable/Sheets/Linear swaps just those two
• Notion is the in-tree reference binding, like linkedin-search is for portals

The fork-adaptation note sits at the bottom of the spec (following setup.md's Design Principles precedent) — happy to move it to the README or drop it.

Tests

python -m unittest tests.test_notion_sync_command -v

Covers: command file exists with the header lint_skills.py enforces; the spec keeps its load-bearing sections; job_scraper/notion_sync.json is gitignored; the documents-never-sync privacy rule is present; python tools/lint_skills.py exits 0. Full suite passes: Ran 114 tests — OK.

Validation

Exercised end-to-end against a live pipeline: first-run database creation, idempotent re-run, in-place schema migration on an existing database, and a real application flowing /outcome → tracker → columns. Run reports available for the PR.

The ask

Branch ready: feat/notion-sync (4 files, +203). Does this fit — or would you prefer a different shape (flag-gated, different name, or fork-only)?

Related: this sits in the same presentation-layer space as #131 (/html-report) — I see them as complementary (static local dashboard vs. live remote view on mobile), but happy to align if you'd rather converge on one pattern.

[MadsLorentzen]

This is how to propose a feature here - you found the admission test and brought a candidate that genuinely passes it: /rank scores in seen_jobs.json are exactly "data something writes but nothing reads," and "check my pipeline from a phone" has no answer in the framework today. The privacy line (filenames only, documents never leave the machine), the one-way flow, and the OAuth-via-MCP no-keys approach are all the right instincts. And you pre-empted the floodgate concern with the same move this repo uses for portals - tool-agnostic contract, one in-tree reference binding - which is precisely the answer I would have given.

One thing changed since you wrote this, and it's the main thing your spec should now address explicitly: /html-report merged this morning (#131). It renders the same tracker into a self-contained local HTML dashboard - stat cards, funnel, filterable table. So the pitch for /notion-sync is no longer "nothing presents this data"; it's "nothing presents it away from your machine." I think that case still stands - a dashboard you regenerate at your desk and a live pipeline row you check from your phone between errands are different tools for different moments - but the spec should say so and position the two against each other: what belongs in /html-report's lane (deep review, charts, fully offline) versus yours (current state, anywhere, glanceable). If the positioning is honest, they compose rather than compete; /outcome even gets a natural "refresh both" mention.

Conditions for the PR, none of which should surprise you since your spec already promises most of them:

1. Silently optional - the freehire bar. No Notion configured means one clear message and a clean exit; nothing else in the framework may notice the command exists. That includes headless/CI contexts: the Notion MCP server is interactively authenticated, so "connected but not authenticable right now" needs the same graceful exit as "not configured."
2. No new dependencies, no API keys - official Notion MCP only, as you propose.
3. Read-only toward the repo stays absolute - the sync-state file (notion_sync.json) is the single thing it may write, gitignored like the tracker.
4. The contract/binding split is real in the file layout - the tool-agnostic sync contract stated separately from the Notion-specific steps, so an Airtable/Sheets fork swaps two sections and nothing else. Other bindings live in forks, like portals.
5. One concern per PR - the command + its tests + README row; nothing else.

Command #12 is a real cost - the lifecycle is feature-complete and every added command dilutes discoverability a little - but "the pipeline, reachable from anywhere the terminal isn't" earns the slot if the /html-report positioning holds up. PR welcome on that shape.

[AdriBarda]

Hi Mads! Thanks for the fast read and the clear bar — PR is up: #169, on the shape you described.

The /html-report positioning is now explicit in the spec. It opens with a "Lane" section making exactly the split you drew:

• /html-report — deep review: charts, fully offline, regenerated at your desk
• /notion-sync — the glanceable check between errands: current state, anywhere Notion runs

You were right about the natural composition too: "after /outcome records a result, re-run either or both" is now a sentence in the spec, and the README row cross-references the two the same way. The PR's pitch follows your correction as well — not "nothing presents this data" but "nothing presents it away from your machine."

The conditions — no surprises, as you predicted:

• Contract/binding split, real in the layout: only Steps 1 and 3 carry a (Notion binding) marker; everything else reads destination-neutral, and the fork-adaptation section names the exact two swaps for an Airtable/Sheets fork.
• Read-only stayed absolute: notion_sync.json is the single local write, stated as Rule 1.
• No new deps, no keys: official Notion MCP over OAuth, nothing else.
• One concern: command + tests + README row, plus the one gitignore line the read-only condition implies. Rebased on top of feat(html-report): add /html-report command for application tracker dashboard #131 — both commands' tests run together in the suite.

One condition earned its keep in a way worth reporting: "connected but not authenticable." I tested the three connection states in fresh sessions before opening the PR, and the spec that looked clean on paper failed twice:

1. Claude tried to verify the server's absence by running claude mcp list — a permission prompt exactly where the silent exit should be
2. When it found the server unauthenticated, it helpfully offered to drive the OAuth flow itself
3. Bonus find: the connect instructions were missing the session restart claude mcp add requires, so a user following them literally hit a dead end

All three are fixed in the spec, details in #169's verification section. Your freehire bar was doing more work than either of us could see from the text.

Validation held up end-to-end on my live pipeline: first-run creation, idempotent re-run, in-place schema migration on a populated database, and a real application flowing /outcome → tracker → columns. Filenames only — documents never left the machine.