Spec for spec-driven development

Job Tracker Spec

Emily Ruth · October 27, 2026

This spec turns the Job Tracker PRD into testable requirements, acceptance tests and a prioritized backlog for the engineering team. This doc is the source of truth: the spec changes first, then the code.

Conventions Data model Requirements Acceptance tests Design constraints Backlog Open questions

How to use this spec

Requirement IDs: AREA-n (for example, STG-2). Every test and task cites one.
Requirement format: WHEN [trigger], THE SYSTEM SHALL [behavior].
Test format: Given / When / Then, one test per requirement at minimum.
Done means: the task's tests pass and nothing in the regression list breaks.
Scope: the tracker app. Vetting runs in Claude and writes its results to the tracker; the VET requirements define that contract. Out of scope: multi-user accounts, production hosting, and the AI making final decisions.

Data model

Three entities. Every record carries id, version and updatedAt for safe merging (SYNC).

Entity	Fields
Job	title, company, link, posted date, date applied, date rejected, interviewing (bool), follow-up log, interview log, reply log, due date, review-site ratings and counts (2 sites), recommend %, excitement rating, general notes, vetting output
Contact	name, company, phone (international), business email, personal email, LinkedIn, reply log
Company	name, rating, latest vetting date, vetting notes

Logs are lists of {date, note} entries; tables show the newest date.
Company links to jobs and contacts by exact name (see CO-4).

Requirements

ID	Requirement
`UI-1`	THE SYSTEM SHALL show six tabs: Jobs, Applied, Interviewing, Rejected, Contacts, Companies.
`UI-2`	THE SYSTEM SHALL support inline editing, sortable and resizable columns, a pinned header and dark mode.
`UI-3`	WHEN the user opens a job, contact or company, THE SYSTEM SHALL show its full record in a slide-out drawer.
`CAP-1`	WHEN the user runs the bookmarklet on a posting, THE SYSTEM SHALL create a job with its title, company and link.
`STG-1`	WHEN a job gets a date applied, THE SYSTEM SHALL move it to Applied.
`STG-2`	WHEN Interviewing is ticked, THE SYSTEM SHALL move the job to Interviewing.
`STG-3`	WHEN a job gets a date rejected, THE SYSTEM SHALL move it to Rejected.
`STG-4`	WHEN a job is opened or a non-stage field is edited, THE SYSTEM SHALL keep the job on its current tab.
`REM-1`	WHEN an applied, follow-up or interview date is added, THE SYSTEM SHALL set the due date 7 days after the latest one.
`REM-2`	WHEN the due date passes, THE SYSTEM SHALL change its color.
`REM-3`	WHEN a job has had no activity for 30+ days, THE SYSTEM SHALL suggest closing it.
`CO-1`	WHEN a job or contact names a new company, THE SYSTEM SHALL create that company.
`CO-2`	THE SYSTEM SHALL let the user rename, delete or merge companies.
`CO-3`	WHEN a company rating changes, THE SYSTEM SHALL update it on related jobs.
`CO-4`	THE SYSTEM SHALL match companies by exact name.
`VET-1`	WHEN a quick screen runs, THE SYSTEM SHALL check hard gates before scoring, and stop and ask about compromising on a fail.
`VET-2`	WHEN a quick screen scores 55 or higher, THE SYSTEM SHALL offer a full vet.
`VET-3`	WHEN the company was vetted in the last 60 days, THE SYSTEM SHALL reuse that research and check only for news since.
`VET-4`	WHEN a vet finishes, THE SYSTEM SHALL write its output to the job record.
`VET-5`	THE SYSTEM SHALL count a skill only with on-the-job evidence and flag anything not on the resume or confirmed by the user.
`SYNC-1`	WHEN a record is saved, THE SYSTEM SHALL timestamp it and merge by newest.
`SYNC-2`	WHEN the AI writes a record, THE SYSTEM SHALL check its version first and keep the user's edit on conflict.
`SYNC-3`	WHEN cloud sync is unavailable, THE SYSTEM SHALL keep working with local storage only.
`DIG-1`	WHEN the weekday digest runs, THE SYSTEM SHALL email new matches since the last run and skip jobs already passed on.
`BAK-1`	WHEN the user exports, THE SYSTEM SHALL download all data as JSON.

Acceptance tests

Starter set for the highest-risk rules. Add one per remaining requirement as tasks are built.

Test	Req	Given	When	Then
T1	`CAP-1`	A posting page is open	The bookmarklet runs	A new job has the posting's title, company and link
T2	`STG-1`	A job on Jobs	A date applied is entered	The job moves to Applied
T3	`STG-3`	A job on Applied	A date rejected is entered	The job moves to Rejected
T4	`REM-1`	Applied on Oct 1, follow-up on Oct 5	The follow-up is saved	Due date is Oct 12
T5	`CO-1`	No company named Acme	A job for Acme is added	Acme appears on Companies
T6	`VET-1`	A contract-only posting	A quick screen runs	It stops before scoring and asks about compromising
T7	`VET-2`	A quick screen scores 54	The screen finishes	No full vet is offered
T8	`SYNC-2`	The user edits a job while the AI writes to it	Both saves land	The user's edit is kept
T9	`BAK-1`	Any data	The user exports	A JSON file with all jobs, contacts and companies downloads

Regression tests (bugs already fixed; must never return)

Test	Req	Given	When	Then
R1	`SYNC-1`	A job was just added	An older cloud snapshot arrives	The new job is still there
R2	`STG-4`	A job on Rejected	The user opens it	It stays on Rejected
R3	`STG-4`	A job with one stage field set	The user edits a different field	The job stays on its current tab

Design constraints

Rules for every change.

One HTML file, no build step. Keep the app a single self-contained file.
Local first. Browser local storage is the base; cloud sync through Claude Artifacts is optional.
One source of truth for stages. All stage moves (STG-1 to STG-4) go through one function. No stage logic elsewhere.
User edits win. Never overwrite a newer user edit (SYNC-1, SYNC-2).
Small changes. One task per change, its tests updated in the same change.
Spec first. A behavior not in this spec gets added here before it is built.
Keep the demo working. demo.emilyruth.me runs the same code with fictional data.

Backlog

Next release, in priority order. Shipped work is listed below it for traceability.

1. Add automated tests T1 to T9 and R1 to R3.
2. Move all stage logic into one function so R2 and R3 can't recur. (STG-1 to STG-4)

Shipped

Data model and local storage. (SYNC-3)
Six tabs, table features and drawers. (UI-1 to UI-3)
Bookmarklet capture. (CAP-1)
Stage moves. (STG-1 to STG-3)
Due dates and close-out suggestions. (REM-1 to REM-3)
Company creation, rename, delete, merge and rating roll-up. (CO-1 to CO-4)
Timestamped saves, merge by newest and version checks. (SYNC-1, SYNC-2)
Vetting write-back with gates, threshold and 60-day reuse. (VET-1 to VET-5)
JSON export. (BAK-1)
Weekday digest. (DIG-1)

Open questions

Confirm the field lists. Contact name and company, and the company's vetting date and notes, are assumed so VET-3 can work.
Which hard gates besides contract roles belong in VET-1?
Should CO-4 stay exact-match, or add fuzzy matching to cut duplicates?