jobtrackingapp/.gsd/REQUIREMENTS.md

Requirements

This file is the explicit capability and coverage contract for the project.

Active

R002 — Gmail connection, message retrieval, thread import, and linked-thread refresh must help the user pull real correspondence into the right job and keep it current with materially less manual cleanup.

• Class: integration
• Status: active
• Description: Gmail connection, message retrieval, single-message/thread import, and linked-thread refresh must help the user pull real correspondence into the right job, preserve full thread continuity, and automatically surface later inbound or user-sent replies without requiring manual re-import of the thread.
• Why it matters: Gmail import is one of the two clearest current weaknesses and a major trust surface for daily use; one-time import alone is not enough if the thread immediately goes stale.
• Source: user
• Primary owning slice: M001/S01
• Supporting slices: M001/S03, M001/S05
• Validation: remapped after override; previous S01 validation covered ranked import and persisted thread metadata, but the requirement now also includes full-thread continuity and automatic refresh of linked Gmail threads.
• Notes: This requirement was previously treated as validated for one-time import quality. The 2026-03-24 override re-opened it by raising the bar to include ongoing thread sync.

R008 — The app may draft application, reply, and follow-up content, but it must not auto-send emails or auto-apply to jobs.

• Class: constraint
• Status: active
• Description: The app may draft application, reply, and follow-up content, but it must not auto-send emails or auto-apply to jobs.
• Why it matters: The user called auto-sending dangerous and explicitly does not want that behavior.
• Source: user
• Primary owning slice: M001/S03
• Supporting slices: M001/S05
• Validation: mapped
• Notes: This is a durable trust constraint across all milestones.

R009 — Core UX, data model emphasis, and roadmap decisions should optimize for one person managing their own search.

• Class: constraint
• Status: active
• Description: Core UX, data model emphasis, and roadmap decisions should optimize for one person managing their own search.
• Why it matters: Individual-first scope keeps product decisions sharp and prevents premature recruiter/CRM drift.
• Source: user
• Primary owning slice: M001/S04
• Supporting slices: M002/S01, M004/S01
• Validation: mapped
• Notes: Shared/team workflows are not the current product target.

R010 — The app must preserve a coherent history across manual status changes, imported Gmail correspondence, linked-thread updates, reminders, and follow-up work.

• Class: continuity
• Status: active
• Description: The app must preserve a coherent history across manual status changes, imported Gmail correspondence, linked-thread updates, reminders, and follow-up work.
• Why it matters: The product promise is to keep the thread of the job search intact over time, including new Gmail replies that happen after the first import.
• Source: user
• Primary owning slice: M001/S04
• Supporting slices: M001/S01, M001/S03, M001/S05
• Validation: mapped
• Notes: This now explicitly includes automatic continuity for already-linked Gmail threads so the correspondence timeline does not become a stale snapshot.

Validated

R001 — The user finds a job outside the app, imports it into the app, and starts the application workflow from that imported role.

• Class: primary-user-loop
• Status: validated
• Description: The user finds a job outside the app, imports it into the app, and starts the application workflow from that imported role.
• Why it matters: The product is not a job board replacement; the import step is the real start of the user loop.
• Source: user
• Primary owning slice: M001/S01
• Supporting slices: M001/S05
• Validation: S01 completed with a job-scoped Gmail import loop wired into the job workspace: backend GET /api/gmail/job-candidates uses the owned job as context, imports target that job directly, and focused UI verification passed in job-tracker-ui/src/correspondence-gmail-import.test.tsx.
• Notes: Validation is contract/UI-level plus workspace integration. Live user UAT of the broader milestone loop still remains for later slices.

R003 — Tailored CV and cover-letter drafts must feel specific, credible, and good enough that the user wants to start from them.

• Class: differentiator
• Status: validated
• Description: Tailored CV and cover-letter drafts must feel specific, credible, and good enough that the user wants to start from them.
• Why it matters: Draft generation exists already, but the milestone bar is actual usefulness rather than feature presence.
• Source: user
• Primary owning slice: M001/S02
• Supporting slices: M001/S05
• Validation: Validated by M001/S02: backend application-package generation now uses recruiter/job/profile/attachment/imported-correspondence context, focused backend tests pass in an isolated harness, and the Tailored CV workspace test proves generation, editing, save, and saved-state redisplay behavior.
• Notes: S02 proved the application-package drafts are materially more specific and persist as job-tied working material. Broader end-to-end live-loop revalidation still remains in M001/S05.

R004 — The app must generate follow-up and reply drafts from the imported job, saved application material, and correspondence context tied to that job.

• Class: primary-user-loop
• Status: validated
• Description: The app must generate follow-up and reply drafts from the imported job, saved application material, and correspondence context tied to that job.
• Why it matters: Follow-through is part of the core value, not an optional afterthought.
• Source: user
• Primary owning slice: M001/S03
• Supporting slices: M001/S01, M001/S02, M001/S05
• Validation: Validated by M001/S03: follow-up draft generation now consumes imported correspondence plus saved application package material, focused backend follow-up tests pass in an isolated harness, the focused React follow-up test passes, and browser verification on the built branch UI proved the grounded follow-up draft plus manual send/log flow back into correspondence.
• Notes: S03 validated the follow-up half of the requirement. Explicit reply drafting may still be deepened later, but the requirement-level milestone bar is now met for job-grounded follow-up/reply assistance without autonomous sending.

R005 — The first page should give the user a clear overview of jobs, status, readiness, and what needs attention.

• Class: continuity
• Status: validated
• Description: The first page should give the user a clear overview of jobs, status, readiness, and what needs attention.
• Why it matters: The user explicitly wants to start from the job table each day.
• Source: user
• Primary owning slice: M001/S04
• Supporting slices: M001/S05
• Validation: Validated by M001/S04: the job table now exposes actionable urgency chips that route directly into the relevant job workspace tab, focused daily-loop UI tests pass, and browser verification confirmed the table/dashboard/reminders flow routes into the same workspace model.
• Notes: S04 made the table a practical first-stop overview for daily use rather than a passive list.

R006 — The dashboard and follow-up surfaces must clearly show next actions, neglected threads, and jobs that need attention now.

• Class: continuity
• Status: validated
• Description: The dashboard and follow-up surfaces must clearly show next actions, neglected threads, and jobs that need attention now.
• Why it matters: Tracking is only valuable if it turns state into action.
• Source: user
• Primary owning slice: M001/S04
• Supporting slices: M001/S05
• Validation: Validated by M001/S04: dashboard and reminders now expose actionable attention items routed into the existing job workspace, focused daily-loop UI tests pass, and browser verification confirmed those surfaces open the correct job workspace state.
• Notes: S04 made the follow-up/dashboard surfaces show actionable urgency instead of dead-end summaries.

R007 — Each job needs a workspace where the user can update status, review/import correspondence, edit drafts, and prepare follow-ups.

• Class: core-capability
• Status: validated
• Description: Each job needs a workspace where the user can update status, review/import correspondence, edit drafts, and prepare follow-ups.
• Why it matters: The user’s third step in the daily flow is to drop into a specific job and do focused work.
• Source: inferred
• Primary owning slice: M001/S03
• Supporting slices: M001/S02, M001/S04
• Validation: Validated by M001/S03 and M001/S04: the per-job workspace now supports imported correspondence review, package drafting, follow-up drafting, and routed entry from overview surfaces, with focused tests and browser verification covering package and follow-up loops.
• Notes: S01-S04 now make the individual job workspace the real execution surface for import, drafting, and follow-up work. The reopened Gmail continuity work extends what that correspondence review surface must keep current over time.

Deferred

R011 — The app should later expand overview analytics, saved views, and clearer strategy readouts beyond the core daily loop.

• Class: operability
• Status: deferred
• Description: The app should later expand overview analytics, saved views, and clearer strategy readouts beyond the core daily loop.
• Why it matters: This can improve search strategy, but it is not the first trust gap to close.
• Source: inferred
• Primary owning slice: M002/S02
• Supporting slices: none
• Validation: unmapped
• Notes: Deferred because Gmail import and draft quality are higher-value first fixes.

R012 — The app may later add richer message understanding, smarter thread handling, and broader inbox-aware assistance after the first Gmail milestone.

• Class: integration
• Status: deferred
• Description: The app may later add richer message understanding, smarter thread handling, and broader inbox-aware assistance after the first Gmail milestone.
• Why it matters: This extends the correspondence workflow, but it depends on getting the initial import/matching loop right first.
• Source: inferred
• Primary owning slice: M003/S01
• Supporting slices: none
• Validation: unmapped
• Notes: This is the natural next step after M001 proves the core Gmail path, including linked-thread continuity.

R013 — The app may later add broader strategic coaching and more advanced guidance beyond application package and follow-up/reply drafting.

• Class: differentiator
• Status: deferred
• Description: The app may later add broader strategic coaching and more advanced guidance beyond application package and follow-up/reply drafting.
• Why it matters: There is room to deepen the assistant, but the current product bar is a stronger core workflow.
• Source: inferred
• Primary owning slice: M003/S02
• Supporting slices: none
• Validation: unmapped
• Notes: Deferred to avoid scattering the first milestone.

Out of Scope

R014 — The app will not automatically submit applications to external job sites.

• Class: anti-feature
• Status: out-of-scope
• Description: The app will not automatically submit applications to external job sites.
• Why it matters: This prevents product drift into risky, low-trust automation the user explicitly does not want.
• Source: user
• Primary owning slice: none
• Supporting slices: none
• Validation: n/a
• Notes: The app starts after discovery/import, not at job search submission.

R015 — The app will not send replies, follow-ups, or other communication autonomously.

• Class: anti-feature
• Status: out-of-scope
• Description: The app will not send replies, follow-ups, or other communication autonomously.
• Why it matters: Manual control over outbound communication is a hard trust requirement.
• Source: user
• Primary owning slice: none
• Supporting slices: none
• Validation: n/a
• Notes: Drafting is allowed; autonomous sending is not. Automatic thread refresh/import of already-sent Gmail replies is allowed because it reflects history after the user sends manually.

R016 — The product will not optimize for shared pipelines, recruiter operations, or multi-user coaching workflows right now.

• Class: out-of-scope
• Status: out-of-scope
• Description: The product will not optimize for shared pipelines, recruiter operations, or multi-user coaching workflows right now.
• Why it matters: This protects the individual-first product shape.
• Source: user
• Primary owning slice: none
• Supporting slices: none
• Validation: n/a
• Notes: Multi-user admin surfaces may exist technically, but they are not the roadmap center.

R017 — The app will not try to replace external job boards as the main discovery surface.

• Class: out-of-scope
• Status: out-of-scope
• Description: The app will not try to replace external job boards as the main discovery surface.
• Why it matters: The user explicitly described a workflow that starts after finding the job elsewhere.
• Source: user
• Primary owning slice: none
• Supporting slices: none
• Validation: n/a
• Notes: Job import is the bridge from external discovery into the app.

Traceability

ID	Class	Status	Primary owner	Supporting	Proof
R001	primary-user-loop	validated	M001/S01	M001/S05	S01 completed with a job-scoped Gmail import loop wired into the job workspace: backend GET /api/gmail/job-candidates uses the owned job as context, imports target that job directly, and focused UI verification passed in job-tracker-ui/src/correspondence-gmail-import.test.tsx.
R002	integration	active	M001/S01	M001/S03, M001/S05	Remapped after the 2026-03-24 override: ranked import and metadata persistence exist, but the requirement now also includes full-thread continuity and automatic refresh of linked Gmail threads so later inbound/user-sent replies appear without manual re-import.
R003	differentiator	validated	M001/S02	M001/S05	Validated by M001/S02: backend application-package generation now uses recruiter/job/profile/attachment/imported-correspondence context, focused backend tests pass in an isolated harness, and the Tailored CV workspace test proves generation, editing, save, and saved-state redisplay behavior.
R004	primary-user-loop	validated	M001/S03	M001/S01, M001/S02, M001/S05	Validated by M001/S03: follow-up draft generation now consumes imported correspondence plus saved application package material, focused backend follow-up tests pass in an isolated harness, the focused React follow-up test passes, and browser verification on the built branch UI proved the grounded follow-up draft plus manual send/log flow back into correspondence.
R005	continuity	validated	M001/S04	M001/S05	Validated by M001/S04: the job table now exposes actionable urgency chips that route directly into the relevant job workspace tab, focused daily-loop UI tests pass, and browser verification confirmed the table/dashboard/reminders flow routes into the same workspace model.
R006	continuity	validated	M001/S04	M001/S05	Validated by M001/S04: dashboard and reminders now expose actionable attention items routed into the existing job workspace, focused daily-loop UI tests pass, and browser verification confirmed those surfaces open the correct job workspace state.
R007	core-capability	validated	M001/S03	M001/S02, M001/S04	Validated by M001/S03 and M001/S04: the per-job workspace now supports imported correspondence review, package drafting, follow-up drafting, and routed entry from overview surfaces, with focused tests and browser verification covering package and follow-up loops.
R008	constraint	active	M001/S03	M001/S05	mapped
R009	constraint	active	M001/S04	M002/S01, M004/S01	mapped
R010	continuity	active	M001/S04	M001/S01, M001/S03, M001/S05	mapped
R011	operability	deferred	M002/S02	none	unmapped
R012	integration	deferred	M003/S01	none	unmapped
R013	differentiator	deferred	M003/S02	none	unmapped
R014	anti-feature	out-of-scope	none	none	n/a
R015	anti-feature	out-of-scope	none	none	n/a
R016	out-of-scope	out-of-scope	none	none	n/a
R017	out-of-scope	out-of-scope	none	none	n/a

Coverage Summary

• Active requirements: 4
• Mapped to slices: 4
• Validated: 6 (R001, R003, R004, R005, R006, R007)
• Unmapped active requirements: 0