Product Requirements Document
Job Pilot v2
This document defines the features, acceptance criteria, and build phases for the Job Pilot v2 application. Derived from docs/02-prd.md, it serves as the single source of truth for functional requirements and validation rules.
Quick navigation
Project constraints, vision, and hard rules.
HLD, LLD, module tree, data model, contracts.
CLI contracts, safety invariants, test mode.
UI design specs and prototype alignment.
Phased rollout, DoD gates, test strategy.
Logged design decisions and tradeoffs.
Functional Requirements
Priority 0 – Core Modules
P0 features define the essential job‑application workflow. They must be delivered in Phase 1 and are non‑negotiable for the initial release. The total estimated story points for P0 is 65.
- Profile creation & management
- Opportunity discovery & filtering
- Evaluation & scoring
- Application tracker
- Cover‑letter tailoring
- One‑click apply
- Auto‑pilot queue
Priority 1 – Enhancements
P1 features build on top of the core workflow and are scheduled for Phase 2. They enhance the user experience but are not blockers. Estimated story points: 20.
- Interview scheduling & tracking
- Resume template builder
P0 Feature Areas
Core modules essential for the job‑application workflow. Total story points: 65.
P1 Feature Areas
Enhancements scheduled for Phase 2. Total story points: 20.
Acceptance Criteria
Acceptance criteria define the measurable outcomes that a feature must satisfy. They are mapped to each module and validated through unit tests, integration smoke tests (with MOCK_AGENT=1), and manual UI checks.
Below, the criteria for each module are broken down into validation rules, edge cases, and actionable test scenarios. Use the expandable sections to browse the complete specification.
Jump to detailed validation rules →Detailed Validation Rules
Profile
Create and manage personal details, skills, and work history.
Validation Rules
- Email: RFC 5322 format, unique in store.
- Name: required, 2–100 characters.
- Skills: at least 1 skill required before applying.
- All writes are atomic (JSON file collection).
Edge Cases
- Duplicate email attempt returns HTTP 409.
- Empty skills array disables apply button.
Test Scenarios
Given an empty profile, when the user enters email "alice@example.com", then the system saves and returns 201.Given a profile with existing email, when the user tries to create a duplicate, then the system responds with 409 Conflict.Discovery
Search and filter job opportunities.
Validation Rules
- Query: max 200 characters.
- Location: optional, matched against city/state fields.
- Pagination: page size 1–20, default 20.
- Invalid parameters return HTTP 400 with error details.
Edge Cases
- Empty search term returns all opportunities (up to pagination limit).
- Simultaneous rapid requests are throttled to 10 per second per client.
Test Scenarios
Given a search for "React" with location "San Francisco", when there are 3 matching results, then the response includes exactly those 3 opportunities.Given a search with page=0, then the system responds with 400 and message "page must be >= 1".Evaluation
Score opportunities against the profile.
Validation Rules
- Scoring formula: skillMatch(0.4) + seniority(0.3) + culture(0.3).
- Scores are cached and invalidated on profile/opportunity change.
- Maximum score: 1.0; minimum: 0.0.
Edge Cases
- Profile with zero skills yields 0 for skillMatch factor.
- Opportunity with no skills listed is treated as a perfect match for skillMatch to avoid division by zero.
Test Scenarios
Given a profile with skills ["JavaScript","React"], and an opportunity requiring ["JavaScript","React","Node"], then skillMatch is 0.67 (2/3). Overall score displayed with two decimal places.Tracker
Track application statuses with event‑sourced updates.
Validation Rules
- Status transitions allowed: applied→screening→interview→offer→rejected, but not backward without user confirmation.
- Every change appends to the immutable JSONL event log.
- Undo only permitted within 5 seconds of the last change.
Edge Cases
- Attempted undo beyond 5 seconds returns 410 Gone.
- Concurrent writes from two tabs: optimistic lock version check rejects stale updates.
Test Scenarios
Given an application in "applied" status, when the user moves it to "screening", then the log records the change and the UI updates immediately.Tailoring
Generate cover letters via Claude Code CLI.
Validation Rules
- CLI command must follow the TRD contract: `claude-code generate-letter --profile-id=... --job-id=...`.
- With MOCK_AGENT=1, a fixed placeholder letter is returned.
- Generated letters are editable and auto‑saved after 2 seconds of inactivity.
Edge Cases
- CLI unavailable: show graceful fallback message and offer manual editor.
- Very long prompts (>1000 chars) are truncated with warning.
Test Scenarios
In MOCK_AGENT mode, invoking generate-letter returns the phrase "MOCK COVER LETTER" – the UI displays it in the editor.Apply
Submit pre‑filled applications.
Validation Rules
- All required profile fields must be non‑empty before submission.
- Duplicate submissions for the same opportunity id are prevented by server‑side check.
- External API calls are mocked in tests via BrowserClaw MCP stub.
Edge Cases
- Network timeout: retry up to 2 times with exponential backoff.
- Partial fill: missing optional fields are omitted from submission.
Test Scenarios
Given a complete profile and an opportunity id, when the user clicks Apply, then the system creates an entry in the tracker and returns 201.Auto‑Pilot
Automatically apply to top matches.
Validation Rules
- Enabled/disabled toggle stored in user preferences.
- Eligibility: score >= threshold (default 0.7).
- Daily limit: 20 applications; counter reset at midnight UTC.
Edge Cases
- No opportunities meet threshold: shows "No qualifying matches today" in notification.
- User disables auto‑pilot mid‑batch: pending applications are cancelled.
Test Scenarios
Given auto‑pilot on, threshold 0.7, and 5 opportunities with scores [0.8, 0.75, 0.6, 0.9, 0.5], then only the three with score>=0.7 are applied to (order by score descending).Interviews
Schedule and manage interviews.
Validation Rules
- Date/time must be in the future.
- No two interviews overlapping for the same user.
- Notifications via browser push (requires permission).
Edge Cases
- User denies notification permission: reminders shown as in‑app toasts.
- Rescheduling to a busy slot returns 409 with suggestion.
Test Scenarios
Given two interviews scheduled back‑to‑back at 10:00–10:30 and 10:30–11:00, the system allows without overlap error.Resume Templates
Build and export resumes.
Validation Rules
- At least one template must always be available.
- Exported PDF must be printable on A4/US Letter.
- Custom CSS is sanitized to prevent XSS (only safe properties allowed).
Edge Cases
- Empty profile: template shows empty placeholders, export blocked.
- Large custom CSS (>10KB) is rejected with warning.
Test Scenarios
Given a complete profile, the exported PDF contains the user’s name, skills, and work history exactly as entered.Build Phases
Four‑phase delivery plan from scaffold to production‑ready.
Initialize project structure, store adapters, and core server. Validate zero‑npm‑dependency constraint and ensure the application boots on port 7878.
Implement all P0 feature areas (Profile, Discovery, Evaluation, Tracker, Tailoring, Apply, Auto‑Pilot). Deliver the core job‑application flow end‑to‑end.
Implement P1 enhancements: Interviews, Resume Templates. Integrate with existing P0 flow. Verify no regressions.
QA, performance optimization, code review, documentation updates. Final sign‑off readiness.
Module Dependencies
Core P0 modules form a strict sequential chain. P1 features depend on Apply.
Definition of Done
Each phase is complete only when every gate is verified.
No comments yet. Be the first!