diff --git a/.gitignore b/.gitignore index fcfb08278f37f226b488780104e2e0efb72d556e..75d585565b4a06369906fd70e728f8234f6f058d 100644 --- a/.gitignore +++ b/.gitignore @@ -48,3 +48,9 @@ models_cache/ # Generated knowledge graph + local agent instructions graphify-out/ CLAUDE.md + +# Scratch notes folder +mds hi mds/ + +# GSD planning workspace +.gsd/ diff --git a/.gsd/DECISIONS.md b/.gsd/DECISIONS.md deleted file mode 100644 index ba3102a79954ca597a547749518059c430c3f52c..0000000000000000000000000000000000000000 --- a/.gsd/DECISIONS.md +++ /dev/null @@ -1,50 +0,0 @@ -# DECISIONS.md — Architecture Decision Records - -## ADR-001: FastAPI Backend -**Date**: 2026-03-27 -**Status**: Accepted -**Context**: Need a Python backend framework that supports async, has great ML ecosystem interop, and is hackathon-fast to develop. -**Decision**: Use FastAPI with uvicorn. -**Rationale**: Async support, automatic OpenAPI docs, Pydantic validation, seamless Python ML library integration. - -## ADR-002: Plain HTML/CSS/JS Frontend -**Date**: 2026-03-27 -**Status**: Accepted -**Context**: Need a frontend approach that's fast to build, has no build step, and works for a hackathon demo. -**Decision**: Use vanilla HTML, CSS, and JavaScript — no framework. -**Rationale**: Zero setup overhead, instant iteration, no dependency management. Can upgrade to a framework later if needed. - -## ADR-003: SQLite Database -**Date**: 2026-03-27 -**Status**: Accepted -**Context**: Need persistence for analysis results without infrastructure overhead. -**Decision**: Use SQLite via SQLAlchemy. -**Rationale**: Zero-config, file-based, perfect for local-first demo. Trivially swappable for PostgreSQL later. - -## ADR-004: Local LLM for Internal Team Data -**Date**: 2026-03-27 -**Status**: Accepted -**Context**: Internal team skills and project data is confidential — cannot send to external APIs. -**Decision**: Use local LLM (Ollama / LM Studio) for internal team analysis features. -**Rationale**: Keeps company data on-premise. Achieves confidentiality without sacrificing AI capability. - -## ADR-005: GitHub REST API with PAT -**Date**: 2026-03-27 -**Status**: Accepted -**Context**: Need to fetch developer activity data from GitHub. -**Decision**: Use GitHub REST API with a Personal Access Token for higher rate limits. -**Rationale**: Simple, well-documented, sufficient for demo. PAT gives 5000 req/hour vs 60 unauthenticated. - -## ADR-006: LeetCode GraphQL Endpoint -**Date**: 2026-03-27 -**Status**: Accepted -**Context**: LeetCode has no official public API, but community-documented GraphQL endpoints exist. -**Decision**: Use LeetCode's GraphQL endpoint for fetching user problem-solving data. -**Rationale**: Provides structured data (problems by difficulty, submission stats) without scraping HTML. - -## ADR-007: Public Salary Datasets for Benchmarking -**Date**: 2026-03-27 -**Status**: Accepted -**Context**: Need salary estimation without paid API subscriptions. -**Decision**: Use Levels.fyi public dataset and GitHub Jobs archive for salary ranges. -**Rationale**: Free, credible sources. Combined with skill match + experience + location → market-rate estimation. diff --git a/.gsd/JOURNAL.md b/.gsd/JOURNAL.md deleted file mode 100644 index ababa4d32090c8dade3d1b3d4234bcc82542b129..0000000000000000000000000000000000000000 --- a/.gsd/JOURNAL.md +++ /dev/null @@ -1,21 +0,0 @@ -# JOURNAL.md — Development Journal - -## 2026-03-27 — Project Initialization - -### What happened -- Ran `/new-project` workflow -- Deep questioning with comprehensive project brief -- Finalized SPEC.md with 5 goals, clear non-goals, and success criteria -- Created 22 testable requirements in REQUIREMENTS.md -- Designed 5-phase ROADMAP.md -- Documented 7 architecture decisions in DECISIONS.md - -### Key insights -- The project is a hackathon build but should feel production-grade -- Internal team data requires local LLM for confidentiality -- Resume inflation detection is the "wow factor" demo feature -- Salary benchmarking turns recommendations into business cases - -### Next steps -- Run `/plan 1` to create Phase 1 execution plan -- Start with project structure, FastAPI skeleton, and SQLite models diff --git a/.gsd/REQUIREMENTS.md b/.gsd/REQUIREMENTS.md deleted file mode 100644 index d93694c7e88c1ee6eff112f57897c0557e6dc1d6..0000000000000000000000000000000000000000 --- a/.gsd/REQUIREMENTS.md +++ /dev/null @@ -1,28 +0,0 @@ -# REQUIREMENTS.md - -## Format - -| ID | Requirement | Source | Status | -|----|-------------|--------|--------| -| REQ-01 | Parse PDF resumes and extract structured fields (name, skills, projects, experience, links) | SPEC Goal 1 | Pending | -| REQ-02 | Fetch GitHub profile data via REST API: repos, commits, languages, stars, activity timeline | SPEC Goal 1 | Pending | -| REQ-03 | Compute GitHub-derived scores: consistency, project depth, tech breadth, recency | SPEC Goal 1 | Pending | -| REQ-04 | Fetch LeetCode profile data via GraphQL: problems solved by difficulty, streaks | SPEC Goal 1 | Pending | -| REQ-05 | Compute skill similarity between candidate and job description using sentence embeddings | SPEC Goal 1 | Pending | -| REQ-06 | Generate overall match score with matched/missing skill breakdown | SPEC Goal 1 | Pending | -| REQ-07 | Predict learning ability for each missing skill using transfer graph + behavioral modifiers | SPEC Goal 2 | Pending | -| REQ-08 | Classify learning speed (Fast/Medium/Slow) with time estimates per skill | SPEC Goal 2 | Pending | -| REQ-09 | Compare claimed skills (resume) vs verified activity (GitHub/LeetCode) to compute credibility scores | SPEC Goal 3 | Pending | -| REQ-10 | Flag specific resume inflation patterns with human-readable explanations | SPEC Goal 3 | Pending | -| REQ-11 | Accept team skills + project requirements as input for internal analysis | SPEC Goal 4 | Pending | -| REQ-12 | Compute skill coverage score and identify missing capabilities | SPEC Goal 4 | Pending | -| REQ-13 | Cluster skill gaps by domain (DevOps, Frontend, ML, Backend) | SPEC Goal 4 | Pending | -| REQ-14 | Generate hire plan with urgency levels | SPEC Goal 4 | Pending | -| REQ-15 | Auto-generate job descriptions from skill gaps | SPEC Goal 4 | Pending | -| REQ-16 | Estimate salary ranges using public datasets (Levels.fyi, GitHub Jobs archive) | SPEC Goal 5 | Pending | -| REQ-17 | Include budget impact in hire plan recommendations | SPEC Goal 5 | Pending | -| REQ-18 | Every score provides contributing factors and reasoning explanation | SPEC Goal 5 | Pending | -| REQ-19 | Store analysis results in SQLite for retrieval and comparison | SPEC Goal 5 | Pending | -| REQ-20 | Web dashboard with candidate analysis view and team analysis view | SPEC Goal 5 | Pending | -| REQ-21 | Process internal team data using local LLM only (no external API calls) | SPEC Constraint | Pending | -| REQ-22 | Full system runs locally without cloud dependencies | SPEC Constraint | Pending | diff --git a/.gsd/ROADMAP.md b/.gsd/ROADMAP.md deleted file mode 100644 index 9e5546f2c7e191adb58cdec0b27390b394dbccb3..0000000000000000000000000000000000000000 --- a/.gsd/ROADMAP.md +++ /dev/null @@ -1,106 +0,0 @@ -# ROADMAP.md - -> **Current Phase**: Not started -> **Milestone**: v1.0 — Hackathon MVP - -## Must-Haves (from SPEC) -- [ ] Resume parsing → structured candidate profile -- [ ] GitHub analysis → consistency, depth, breadth, recency scores -- [ ] LeetCode analysis → problem-solving metrics -- [ ] Skill similarity matching (semantic) -- [ ] Learning ability prediction with time estimates -- [ ] Resume inflation detection with credibility flags -- [ ] Internal skill gap analyzer → hire plan + JD generation -- [ ] Salary benchmarking integrated into hire plan -- [ ] Explainable scoring (every output has reasoning) -- [ ] Web dashboard (candidate view + team view) -- [ ] SQLite persistence -- [ ] Fully local deployment - -## Phases - -### Phase 1: Project Foundation & Backend Skeleton -**Status**: ✅ Complete -**Objective**: Set up the FastAPI project structure, SQLite database, configuration, and API scaffolding. Create the frontend shell with navigation between candidate analysis and team analysis views. -**Requirements**: REQ-19, REQ-20, REQ-22 -**Deliverable**: Running FastAPI server with health check, SQLite models, and frontend shell with two-view layout. - ---- - -### Phase 2: Resume Parser + GitHub & LeetCode Analyzers -**Status**: ✅ Complete -**Objective**: Build the three data ingestion modules — PDF resume parser (structured extraction), GitHub REST API analyzer (4 scores), and LeetCode GraphQL analyzer (difficulty-weighted metrics). Wire them into the API. -**Requirements**: REQ-01, REQ-02, REQ-03, REQ-04 -**Deliverable**: Upload a resume → extracted profile with GitHub/LeetCode data fetched and scored. - ---- - -### Phase 3: ML Engine — Skill Matching, Learning Prediction & Inflation Detection -**Status**: ✅ Complete -**Objective**: Build the core intelligence layer — semantic skill similarity (sentence embeddings), learning ability predictor (transfer graph + speed modifiers), and resume inflation detector (cross-reference claimed vs verified). Every score includes explainability. -**Requirements**: REQ-05, REQ-06, REQ-07, REQ-08, REQ-09, REQ-10, REQ-18 -**Deliverable**: Given a candidate profile + job description → full analysis report with match score, learning estimates, credibility flags, and explanations. - ---- - -### Phase 4: Internal Skill Gap Analyzer + Salary Benchmarking -**Status**: ✅ Complete -**Objective**: Build the team-side analysis — accept team skills + project requirements, compute coverage, identify gaps by domain, generate hire plan with urgency, auto-generate JDs, and integrate salary benchmarking from public datasets. Internal data processed via local LLM. -**Requirements**: REQ-11, REQ-12, REQ-13, REQ-14, REQ-15, REQ-16, REQ-17, REQ-21 -**Deliverable**: Input team + project → skill coverage, gap clusters, hire plan with salary estimates, and ready-to-post JDs. - ---- - -### Phase 5: Dashboard Polish & Demo Integration -**Status**: ⬜ Not Started -**Objective**: Build the complete frontend dashboard — candidate analysis flow (upload → instant report), team analysis flow (input → hire plan), result persistence, comparison views, and demo-ready polish (animations, responsive layout, error states). -**Requirements**: REQ-19, REQ-20 -**Deliverable**: End-to-end working demo: upload resume → see full analysis; input team → see hire plan. Production-quality UI. - ---- - -### Phase 6: Modern React UI Migration (Shadcn + Tailwind) -**Status**: ✅ Complete -**Objective**: Build a visually stunning landing page and migrate the dashboard to React, Tailwind, and Shadcn UI. Implement `BackgroundPaths` and `HeroSection` components. Replace emojis with Phosphor/Lucide icons. -**Depends on**: Phase 5 - ---- - -### Phase 7: Connect Frontend and Backend (Dashboard Migration) -**Status**: ✅ Complete -**Objective**: Build out the Next.js `/dashboard` route, abstract API fetches with React paradigms (connecting to `localhost:8000`), and construct the rich shadcn-based result cards for Candidate and Team Gap analysis, bringing full functional parity to the React rollout. -**Depends on**: Phase 6 - ---- - -### Phase 8: LLM Semantic Mapping & Advanced UI (Radar/Bulk Upload) -**Status**: ✅ Complete -**Objective**: Integrate the Gemini API to intelligently map abstract skill relationships (e.g., NLP vs BERT) by feeding it repo metadata (README/requirements files). Implement Candidate Radar Charts on the frontend for visual capability assessment, and add a Mass PDF Uploader to the Team gap analysis page to parse an entire team simultaneously. -**Depends on**: Phase 7 - ---- - -### Phase 9: Shadcn UI Enhancements (Radar Chart and Verification Badges) -**Status**: ✅ Complete -**Objective**: Replace the current Recharts radar chart with a highly polished Shadcn-based "Radar Chart - Dots". Add a verification badge UI component to clearly display the status of GitHub parsing (tick/dash/cross), LeetCode parsing (tick/dash/cross), and Gemini semantic analysis (tick/cross). -**Depends on**: Phase 8 - -**Tasks**: -- [ ] Plan 9.1: Shadcn Chart Integration -- [ ] Plan 9.2: Implement Shadcn Radar Chart and Verification Badges - -**Verification**: -- TBD - ---- -### Phase 10: Team Gap Analysis UI Overhaul -**Status**: ⬜ Not Started -**Objective**: Redesign the Team Gap Analysis view to match the premium aesthetics of the new Candidate dashboard and Shadcn visual design system. -**Depends on**: Phase 9 - -**Tasks**: -- [ ] TBD (run /plan 10 to create) - -**Verification**: -- TBD - diff --git a/.gsd/SPEC.md b/.gsd/SPEC.md deleted file mode 100644 index 42617d4358c189db16e68ae59eed05bb03f27404..0000000000000000000000000000000000000000 --- a/.gsd/SPEC.md +++ /dev/null @@ -1,63 +0,0 @@ -# SPEC.md — Project Specification - -> **Status**: `FINALIZED` -> **Project**: HireSense AI — Intelligent Hiring & Workforce Planning System - -## Vision - -HireSense AI replaces resume-based hiring with a multi-signal intelligence system that evaluates real coding behavior, verified technical activity, learning ability, and team-level skill gaps. It transforms hiring from guesswork into data-driven decision making — purpose-built for early-stage startups that lack dedicated HR teams. - -## Goals - -1. **Multi-Signal Candidate Analysis** — Fuse resume data with GitHub activity, LeetCode performance, and skill similarity to produce a holistic candidate score with full explainability. -2. **Learning Ability Prediction** — Predict how fast a candidate can acquire missing skills using a transfer graph and behavioral modifiers (GitHub consistency, problem-solving depth, recency). -3. **Resume Authenticity Detection** — Cross-reference claimed skills against verified external signals to flag inflation and inconsistencies. -4. **Internal Skill Gap Analysis** — Analyze existing team skills against project requirements to identify gaps, generate hire plans with urgency levels, and auto-generate job descriptions. -5. **Actionable Hiring Intelligence** — Produce explainable reports with salary benchmarks, turning recommendations into business cases a CTO can act on. - -## Non-Goals (Out of Scope for v1.0) - -- Candidate Trajectory Score (growth trend analysis over time) -- Team Culture Fit Heuristic (behavioral inference from GitHub) -- AI Interviewer (custom question generation) -- User authentication / multi-tenant access control -- Cloud deployment / CI/CD pipeline -- Mobile application -- Integration with ATS (Applicant Tracking Systems) - -## Users - -- **Primary**: Technical founders, CTOs, and small hiring teams at early-stage startups -- **Workflow**: Upload a resume + paste a job description → get instant analysis with match score, learning ability, credibility, and explanations -- **Team mode**: Input team skills + project requirements → get coverage analysis, skill gaps, hire plan, and auto-generated JDs - -## Tech Stack - -| Layer | Choice | Rationale | -| ---------------- | ----------------------------------------------------- | ---------------------------------------------- | -| Backend | **FastAPI** (Python) | Fast async API, Python ML ecosystem | -| Frontend | **Plain HTML/CSS/JS** | Lightweight, hackathon-friendly, no build step | -| Database | **SQLite** | Zero-config, local-first, sufficient for demo | -| ML/NLP | **sentence-transformers**, scikit-learn, spaCy | Semantic similarity, feature engineering | -| Resume Parsing | **pdfplumber** + spaCy + regex | Structured extraction from PDFs | -| GitHub Data | **GitHub REST API** (with PAT) | Rich developer activity signals | -| LeetCode Data | **GraphQL endpoint** | Problem-solving metrics | -| Salary Data | **Public datasets** (Levels.fyi, GitHub Jobs archive) | Market salary estimation | -| Internal Team AI | **Local LLM** (LM Studio / Ollama) | Confidentiality for company data | - -## Constraints - -- **Local-only deployment** — must run entirely on localhost for hackathon demo -- **No paid API dependencies** — all data sources must be free/public -- **Hackathon timeline** — production-quality code but MVP scope -- **Confidentiality** — internal team data processed by local AI only, never sent to external APIs - -## Success Criteria - -- [ ] Upload a resume PDF → get structured candidate profile with scores in < 30 seconds -- [ ] Match score accurately reflects skill overlap with job description (semantic, not keyword) -- [ ] Learning ability prediction produces actionable time estimates per missing skill -- [ ] Resume inflation detector flags at least 3 categories of inconsistency -- [ ] Internal skill gap analyzer produces hire plan with budget estimates -- [ ] Every score includes human-readable explanation (no black boxes) -- [ ] Full end-to-end demo runs locally without external service dependencies (except GitHub/LeetCode APIs) diff --git a/.gsd/STATE.md b/.gsd/STATE.md deleted file mode 100644 index d6e2b92ef8574d9bc88cec65c75c8983c4a09534..0000000000000000000000000000000000000000 --- a/.gsd/STATE.md +++ /dev/null @@ -1,21 +0,0 @@ -# STATE.md — Project Memory - -> **Last Updated**: 2026-03-29 -> **Current Phase**: 10 -> **Active Task**: Planning required - -## Current Position -- **Phase**: 10 -- **Task**: Creating plans -- **Status**: TBD - -## Last Session Summary -Added Phase 10 to overhaul the Team Gap Analysis frontend UI to match Shadcn visual guidelines. Fixed the double score render bug in the candidate executive summary. - -## Next Steps -1. /plan 10 - -## Known Issues -_None_ - - diff --git a/.gsd/TODO.md b/.gsd/TODO.md deleted file mode 100644 index a256ca4d0912b63eec4bea35bb32ce5f2ff2e3b4..0000000000000000000000000000000000000000 --- a/.gsd/TODO.md +++ /dev/null @@ -1,3 +0,0 @@ -# TODO.md — Pending Items - -_No pending items yet._ diff --git a/.gsd/examples/cross-platform.md b/.gsd/examples/cross-platform.md deleted file mode 100644 index 8e3f56e0f8453953ea4a1885ac41369279fadafa..0000000000000000000000000000000000000000 --- a/.gsd/examples/cross-platform.md +++ /dev/null @@ -1,99 +0,0 @@ -# Cross-Platform Commands Reference - -> PowerShell ↔ Bash equivalents for GSD workflows - -## Common Operations - -| Operation | PowerShell | Bash | -|-----------|------------|------| -| **Test file exists** | `Test-Path "file.md"` | `test -f "file.md"` | -| **Test directory exists** | `Test-Path "dir" -PathType Container` | `test -d "dir"` | -| **Create directory** | `New-Item -ItemType Directory -Path "dir"` | `mkdir -p "dir"` | -| **List files** | `Get-ChildItem "*.md"` | `ls *.md` | -| **List recursively** | `Get-ChildItem -Recurse` | `find . -type f` | -| **Read file** | `Get-Content "file.md"` | `cat "file.md"` | -| **Search in files** | `Select-String -Path "**/*" -Pattern "TODO"` | `grep -r "TODO" .` | -| **Count lines** | `(Get-Content file).Count` | `wc -l < file` | -| **Copy files** | `Copy-Item -Recurse src dest` | `cp -r src dest` | -| **Delete files** | `Remove-Item -Recurse -Force dir` | `rm -rf dir` | - -## Git Operations (Same on Both) - -```bash -git add -A -git commit -m "message" -git push -git status --short -``` - -## Workflow-Specific Examples - -### /map — Analyze Codebase - -**PowerShell:** -```powershell -Get-ChildItem -Recurse -Directory | - Where-Object { $_.Name -notmatch "node_modules|\.git" } -``` - -**Bash:** -```bash -find . -type d ! -path "*/node_modules/*" ! -path "*/.git/*" -``` - ---- - -### /plan — Check SPEC Status - -**PowerShell:** -```powershell -$spec = Get-Content ".gsd/SPEC.md" -Raw -if ($spec -match "FINALIZED") { "Ready" } -``` - -**Bash:** -```bash -if grep -q "FINALIZED" .gsd/SPEC.md; then echo "Ready"; fi -``` - ---- - -### /execute — Discover Plans - -**PowerShell:** -```powershell -Get-ChildItem ".gsd/phases/1/*-PLAN.md" -``` - -**Bash:** -```bash -ls .gsd/phases/1/*-PLAN.md 2>/dev/null -``` - ---- - -### /verify — Search TODOs - -**PowerShell:** -```powershell -Select-String -Path "src/**/*" -Pattern "TODO|FIXME" -``` - -**Bash:** -```bash -grep -rn "TODO\|FIXME" src/ -``` - ---- - -## Environment Detection - -Add this to workflows for cross-platform commands: - -```markdown -**Note:** Commands shown are PowerShell. For Bash equivalents, see `.gsd/examples/cross-platform.md` -``` - ---- - -*Reference for Linux/Mac users* diff --git a/.gsd/examples/multi-wave-workflow.md b/.gsd/examples/multi-wave-workflow.md deleted file mode 100644 index 00984c72e4275c5f3cd4fbea892a080e61d0321d..0000000000000000000000000000000000000000 --- a/.gsd/examples/multi-wave-workflow.md +++ /dev/null @@ -1,256 +0,0 @@ -# Multi-Wave Workflow Example - -This example demonstrates a complete GSD workflow with: -- Short spec -- Plan breakdown -- 2-wave execution -- Verification with commands -- State snapshots - ---- - -## Example: Add User Authentication - -### 1. SPEC.md (Finalized) - -```markdown ---- -status: FINALIZED -updated: 2026-02-07 ---- - -# User Authentication Feature - -## Overview -Add login/logout functionality with JWT tokens. - -## Requirements -1. POST /api/auth/login endpoint -2. POST /api/auth/logout endpoint -3. JWT stored in httpOnly cookie -4. Protected route middleware - -## Success Criteria -- User can login with email/password -- Invalid credentials return 401 -- Protected routes require valid JWT -- Logout clears the cookie -``` - ---- - -### 2. ROADMAP.md (Phase Entry) - -```markdown -## Phase 1: User Authentication - -- [ ] Plan 1.1: Auth endpoints (Wave 1) -- [ ] Plan 1.2: Protected middleware (Wave 2) -``` - ---- - -### 3. PLAN 1.1 (Wave 1) - -```xml ---- -phase: 1 -plan: 1 -type: implementation -wave: 1 ---- - - -Create login and logout endpoints with JWT handling. - - - -Files to read: src/app/api/ structure, existing auth if any - - - - - Create login endpoint - src/app/api/auth/login/route.ts - - Create POST handler accepting {email, password}. - Query users table, compare password with bcrypt. - On success: generate JWT, set httpOnly cookie, return 200. - On failure: return 401 with generic error. - - curl -X POST localhost:3000/api/auth/login -d '{"email":"test@example.com","password":"test123"}' - Valid credentials return 200 + Set-Cookie header - - - - Create logout endpoint - src/app/api/auth/logout/route.ts - - Create POST handler that clears the auth cookie. - Return 200 on success. - - curl -X POST localhost:3000/api/auth/logout --cookie "token=..." - Cookie is cleared, response is 200 - - -``` - ---- - -### 4. Wave 1 Execution - -**Task 1 Commit:** -``` -git commit -m "feat(phase-1): create login endpoint" -``` - -**Task 2 Commit:** -``` -git commit -m "feat(phase-1): create logout endpoint" -``` - ---- - -### 5. Wave 1 State Snapshot - -```markdown ---- -wave: 1 -phase: 1 -created: 2026-02-07T10:30:00 -status: complete ---- - -# Wave 1 State Snapshot - -## Objective -Create authentication endpoints. - -## Changes Realized -- Created login endpoint with JWT generation -- Created logout endpoint with cookie clearing -- Added bcrypt password comparison - -## Files Touched -| File | Change Type | Description | -|------|-------------|-------------| -| src/app/api/auth/login/route.ts | created | Login handler | -| src/app/api/auth/logout/route.ts | created | Logout handler | - -## Verification Results -| Check | Command | Result | -|-------|---------|--------| -| Login works | `curl -X POST .../login` | ✅ 200 + cookie | -| Logout works | `curl -X POST .../logout` | ✅ 200 + cleared | - -## Commits in This Wave -| Hash | Message | -|------|---------| -| abc123 | feat(phase-1): create login endpoint | -| def456 | feat(phase-1): create logout endpoint | - -## TODO for Next Wave -1. Create auth middleware -2. Apply to protected routes -``` - ---- - -### 6. PLAN 1.2 (Wave 2) - -```xml ---- -phase: 1 -plan: 2 -type: implementation -wave: 2 -depends_on: [1] ---- - - -Create middleware to protect routes requiring authentication. - - - -Wave 1 complete: login/logout endpoints exist. -JWT is stored in httpOnly cookie named "token". - - - - - Create auth middleware - src/middleware/auth.ts - - Create middleware that: - 1. Reads JWT from cookie - 2. Verifies signature with jose - 3. Attaches user to request - 4. Returns 401 if invalid/missing - - Import and call middleware with mock request - Valid JWT passes, invalid/missing returns 401 - - - - Apply middleware to protected route - src/app/api/user/profile/route.ts - - Create example protected route. - Apply auth middleware. - Return user data if authenticated. - - curl localhost:3000/api/user/profile with and without cookie - With cookie: 200 + data. Without: 401 - - -``` - ---- - -### 7. Wave 2 Execution & Snapshot - -**Commits:** -``` -git commit -m "feat(phase-1): create auth middleware" -git commit -m "feat(phase-1): apply middleware to profile route" -``` - -**State Snapshot:** (similar format to Wave 1) - ---- - -### 8. Verification - -```bash -# Full verification sequence -curl -X POST localhost:3000/api/auth/login \ - -H "Content-Type: application/json" \ - -d '{"email":"user@example.com","password":"secret"}' \ - -c cookies.txt - -# Expected: 200 + Set-Cookie: token=... - -curl localhost:3000/api/user/profile -b cookies.txt -# Expected: 200 + user data - -curl localhost:3000/api/user/profile -# Expected: 401 - -curl -X POST localhost:3000/api/auth/logout -b cookies.txt -# Expected: 200 + cookie cleared -``` - ---- - -## Key Takeaways - -1. **Waves group dependent work** — Wave 2 waited for Wave 1 -2. **State snapshots preserve context** — Each wave ends with documented state -3. **Atomic commits per task** — Easy to trace and revert -4. **Verification built into plan** — No "trust me, it works" -5. **Effort hints model selection** — `high` effort = use reasoning model - ---- - -*See PROJECT_RULES.md for wave execution rules.* -*See templates/state_snapshot.md for snapshot format.* diff --git a/.gsd/examples/quick-reference.md b/.gsd/examples/quick-reference.md deleted file mode 100644 index ff32d818abe825dcfc7f0f3671656b1d9adf7b0c..0000000000000000000000000000000000000000 --- a/.gsd/examples/quick-reference.md +++ /dev/null @@ -1,73 +0,0 @@ -# GSD Quick Reference Card - -## Workflow Lifecycle - -``` -┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ -│ /map │ → │ /plan │ → │ /execute │ → │ /verify │ -│ │ │ │ │ │ │ │ -│ Analyze │ │ Create │ │ Run │ │ Check │ -│codebase │ │ phases │ │ tasks │ │ work │ -└─────────┘ └─────────┘ └──────────┘ └─────────┘ - ↑ │ - └──────────────┘ - (if gaps found) -``` - -## All Commands - -| Command | Args | Purpose | -|---------|------|---------| -| `/map` | - | Analyze codebase → ARCHITECTURE.md | -| `/plan` | `[phase]` | Create PLAN.md files for phase | -| `/execute` | `phase [--gaps-only]` | Run plans with wave execution | -| `/verify` | `phase` | Validate with empirical proof | -| `/debug` | `description` | Systematic debugging | -| `/progress` | - | Show current position | -| `/pause` | - | Save state, end session | -| `/resume` | - | Load state, start session | -| `/add-todo` | `item [--priority]` | Quick capture | -| `/check-todos` | `[--all]` | List pending items | - -## Core Rules - -| Rule | Enforcement | -|------|-------------| -| 🔒 Planning Lock | No code until SPEC finalized | -| 💾 State Persistence | Update STATE.md after tasks | -| 🧹 Context Hygiene | 3 failures → fresh session | -| ✅ Empirical Validation | Proof required for "done" | - -## Key Files - -| File | Purpose | Updated By | -|------|---------|------------| -| SPEC.md | Vision (finalize first!) | User | -| ROADMAP.md | Phase definitions | /plan | -| STATE.md | Session memory | All | -| ARCHITECTURE.md | System design | /map | -| TODO.md | Quick capture | /add-todo | - -## XML Task Structure - -```xml - - Clear name - exact/path.ts - Specific instructions - Executable command - Measurable criteria - -``` - -## Priority Indicators - -| Priority | Icon | -|----------|------| -| High | 🔴 | -| Medium | 🟡 | -| Low | 🟢 | - ---- - -*Print this for quick reference!* diff --git a/.gsd/examples/workflow-example.md b/.gsd/examples/workflow-example.md deleted file mode 100644 index 4fda502a1ad36d4f203312b84982e6f5f964a76e..0000000000000000000000000000000000000000 --- a/.gsd/examples/workflow-example.md +++ /dev/null @@ -1,139 +0,0 @@ -# GSD Workflow Example - -> A complete walkthrough of using GSD from start to finish. - -## Scenario: Building a Simple Todo API - -### Step 1: Define the Spec - -First, fill out `.gsd/SPEC.md`: - -```markdown -# SPEC.md - -> **Status**: `FINALIZED` - -## Vision -A simple RESTful API for managing todo items. - -## Goals -1. CRUD operations for todos -2. Persistence to SQLite -3. Input validation - -## Success Criteria -- [ ] POST /todos creates a todo -- [ ] GET /todos returns list -- [ ] DELETE /todos/:id removes item -``` - ---- - -### Step 2: Map the Codebase (if existing) - -``` -/map -``` - -This creates: -- `.gsd/ARCHITECTURE.md` — Current structure -- `.gsd/STACK.md` — Technologies in use - ---- - -### Step 3: Plan the Phases - -``` -/plan 1 -``` - -GSD analyzes the SPEC and creates `.gsd/phases/1/` with PLAN.md files: - -```markdown -# Plan 1.1: Database Setup - -## Objective -Create SQLite database with todos table. - -## Tasks - - - Initialize SQLite database - src/db.ts - - Create SQLite connection using better-sqlite3. - Create todos table with: id, title, completed, created_at. - - node -e "require('./src/db')" exits without error - Database file exists, table created - -``` - ---- - -### Step 4: Execute the Phase - -``` -/execute 1 -``` - -GSD: -1. Loads Plan 1.1 -2. Executes tasks in order -3. Runs verify commands -4. Creates atomic commits -5. Creates SUMMARY.md -6. Proceeds to Plan 1.2 -7. Verifies phase goal - ---- - -### Step 5: Verify the Work - -``` -/verify 1 -``` - -GSD: -1. Extracts must-haves from phase -2. Runs verification commands -3. Captures evidence -4. Creates VERIFICATION.md -5. Reports pass/fail - ---- - -### Step 6: Continue or Debug - -**If verified:** -``` -/plan 2 → Plan next phase -/execute 2 → Execute next phase -``` - -**If issues found:** -``` -/execute 1 --gaps-only → Run fix plans -/debug "API returns 500" → Debug the issue -``` - ---- - -## Quick Commands Reference - -| Command | When to Use | -|---------|-------------| -| `/map` | Analyze existing codebase | -| `/plan [N]` | Create plans for phase N | -| `/execute [N]` | Run all plans in phase N | -| `/verify [N]` | Confirm phase N works | -| `/debug [issue]` | Fix a problem | -| `/progress` | See current status | -| `/pause` | End session, save state | -| `/resume` | Start new session | -| `/add-todo` | Capture quick idea | -| `/check-todos` | See pending items | - ---- - -*This example demonstrates the GSD methodology flow.* diff --git a/.gsd/phases/1/1-PLAN.md b/.gsd/phases/1/1-PLAN.md deleted file mode 100644 index 56d65174544753498b69808b714dd2a28ead8066..0000000000000000000000000000000000000000 --- a/.gsd/phases/1/1-PLAN.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -phase: 1 -plan: 1 -wave: 1 ---- - -# Plan 1.1: Python Project Structure & FastAPI Skeleton - -## Objective -Set up the complete Python project structure with FastAPI app, configuration management, dependency specification, and development tooling. This creates the foundation every other module builds on. - -## Context -- .gsd/SPEC.md — Tech stack decisions (FastAPI, Python, SQLite) -- .gsd/DECISIONS.md — ADR-001 (FastAPI), ADR-003 (SQLite) -- .gsd/ROADMAP.md — Phase 1 scope - -## Tasks - - - Create project directory structure - - backend/__init__.py - backend/main.py - backend/config.py - backend/api/__init__.py - backend/api/routes/__init__.py - backend/api/routes/health.py - backend/api/routes/candidates.py - backend/api/routes/teams.py - backend/services/__init__.py - backend/models/__init__.py - backend/utils/__init__.py - requirements.txt - .env.example - .gitignore - README.md - - - Create the following project structure: - - ``` - backend/ - ├── __init__.py - ├── main.py # FastAPI app factory, CORS, static files, router mounting - ├── config.py # Pydantic Settings: DB path, GitHub PAT, API keys, model paths - ├── api/ - │ ├── __init__.py - │ └── routes/ - │ ├── __init__.py - │ ├── health.py # GET /api/health — returns status + version - │ ├── candidates.py # Placeholder POST /api/candidates/analyze - │ └── teams.py # Placeholder POST /api/teams/analyze - ├── services/ - │ └── __init__.py # Empty — services added in Phase 2+ - ├── models/ - │ └── __init__.py # Empty — SQLAlchemy models added in Plan 1.2 - └── utils/ - └── __init__.py # Empty — utilities added later - ``` - - **main.py specifics:** - - Create FastAPI app with title="HireSense AI", version="1.0.0" - - Add CORS middleware allowing all origins (hackathon demo) - - Mount static files from `frontend/` directory at `/` - - Include routers from api/routes/ with `/api` prefix - - Add lifespan handler that initializes the database on startup - - **config.py specifics:** - - Use pydantic-settings BaseSettings class - - Fields: DATABASE_URL (default: sqlite:///./hiresense.db), GITHUB_TOKEN (optional), APP_VERSION (default: 1.0.0) - - Load from .env file - - **health.py specifics:** - - Single GET endpoint at /health - - Returns {"status": "healthy", "version": "1.0.0", "service": "HireSense AI"} - - **candidates.py specifics:** - - Placeholder POST /candidates/analyze that returns {"message": "Not implemented yet"} - - This will be wired up in Phase 2 - - **teams.py specifics:** - - Placeholder POST /teams/analyze that returns {"message": "Not implemented yet"} - - This will be wired up in Phase 4 - - **requirements.txt:** - - fastapi>=0.104.0 - - uvicorn[standard]>=0.24.0 - - pydantic-settings>=2.1.0 - - sqlalchemy>=2.0.23 - - python-multipart>=0.0.6 - - pdfplumber>=0.10.3 - - spacy>=3.7.2 - - sentence-transformers>=2.2.2 - - scikit-learn>=1.3.2 - - requests>=2.31.0 - - python-dotenv>=1.0.0 - - aiofiles>=23.2.1 - - **.env.example:** - - DATABASE_URL=sqlite:///./hiresense.db - - GITHUB_TOKEN=your_github_pat_here - - **.gitignore:** - - Standard Python gitignore + .env, *.db, __pycache__, .venv - - **README.md:** - - Project name, one-line description - - Quick start: install deps, run server - - API docs at /docs - - AVOID: - - Do NOT add authentication — out of scope per SPEC non-goals - - Do NOT create complex middleware — keep it minimal - - Do NOT install dependencies yet — that's a separate step during execution - - - ls -la backend/ backend/api/ backend/api/routes/ backend/services/ backend/models/ backend/utils/ - cat requirements.txt - cat backend/main.py - - - - All directories and files exist - - main.py creates a FastAPI app with CORS, router includes, and static file mount - - config.py has Pydantic Settings with DATABASE_URL and GITHUB_TOKEN - - health.py has GET /health returning status JSON - - requirements.txt has all Phase 1+ dependencies listed - - .env.example, .gitignore, README.md exist - - - - - Install dependencies and verify server starts - requirements.txt - - 1. Create Python virtual environment: python3 -m venv .venv - 2. Activate it: source .venv/bin/activate - 3. Install requirements: pip install -r requirements.txt - 4. Start the server: uvicorn backend.main:app --reload --port 8000 - 5. Test health endpoint: curl http://localhost:8000/api/health - 6. Verify OpenAPI docs load at http://localhost:8000/docs - - AVOID: - - Do NOT install spaCy model yet (needed in Phase 2, not Phase 1) - - Do NOT try to connect to GitHub/LeetCode APIs yet - - - curl -s http://localhost:8000/api/health | python3 -m json.tool - - - - Virtual environment created and activated - - All dependencies installed without errors - - Server starts on port 8000 - - GET /api/health returns {"status": "healthy", "version": "1.0.0", "service": "HireSense AI"} - - /docs page loads and shows all routes - - - -## Success Criteria -- [ ] FastAPI server starts and responds on http://localhost:8000 -- [ ] Health endpoint returns valid JSON with status, version, service -- [ ] Project structure matches the specification above -- [ ] All placeholder routes exist and return appropriate responses diff --git a/.gsd/phases/1/1-SUMMARY.md b/.gsd/phases/1/1-SUMMARY.md deleted file mode 100644 index 8f62b26c4711b5ea6ad716e06ca37d6889746704..0000000000000000000000000000000000000000 --- a/.gsd/phases/1/1-SUMMARY.md +++ /dev/null @@ -1,18 +0,0 @@ -# Plan 1.1 Summary: Python Project Structure & FastAPI Skeleton - -## Status: ✅ Complete - -## What was done -- Created full Python project structure: `backend/` with `main.py`, `config.py`, `api/routes/`, `models/`, `services/`, `utils/` -- FastAPI app with CORS middleware, lifespan handler, router registration, static file serving -- Pydantic Settings config loading from .env (DATABASE_URL, GITHUB_TOKEN) -- Health endpoint: GET /api/health → `{"status": "healthy", "version": "1.0.0", "service": "HireSense AI"}` -- Placeholder candidate and team analysis endpoints -- requirements.txt with all dependencies installed -- README.md, .gitignore, .env.example - -## Verification -- Server starts on port 8000 ✓ -- Health endpoint returns correct JSON ✓ -- OpenAPI docs load at /docs ✓ -- All dependencies install cleanly ✓ diff --git a/.gsd/phases/1/2-PLAN.md b/.gsd/phases/1/2-PLAN.md deleted file mode 100644 index dab77fb5d2355a0c413a5938062d4775b000a5b8..0000000000000000000000000000000000000000 --- a/.gsd/phases/1/2-PLAN.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -phase: 1 -plan: 2 -wave: 1 ---- - -# Plan 1.2: SQLite Database Models & Initialization - -## Objective -Define the SQLAlchemy models for persisting candidate analyses and team analyses. Set up database initialization that runs on app startup. This ensures all later phases can store and retrieve results. - -## Context -- .gsd/SPEC.md — REQ-19: Store analysis results in SQLite -- .gsd/DECISIONS.md — ADR-003 (SQLite via SQLAlchemy) -- backend/config.py — DATABASE_URL setting -- backend/main.py — Lifespan handler for DB init - -## Tasks - - - Create SQLAlchemy models and database setup - - backend/models/__init__.py - backend/models/database.py - backend/models/candidate.py - backend/models/team.py - - - **backend/models/database.py:** - - Create SQLAlchemy engine from config DATABASE_URL - - Create SessionLocal factory with sessionmaker - - Create Base declarative base - - Create `init_db()` function that calls Base.metadata.create_all() - - Create `get_db()` dependency that yields a session and closes it after - - **backend/models/candidate.py:** - - CandidateAnalysis model: - - id: Integer, primary key, autoincrement - - candidate_name: String, nullable - - email: String, nullable - - github_username: String, nullable - - leetcode_username: String, nullable - - resume_skills: Text (JSON string of extracted skills) - - job_description: Text - - match_score: Float, nullable - - learning_ability_score: Float, nullable - - credibility_score: Float, nullable - - overall_score: Float, nullable - - analysis_result: Text (full JSON result blob) - - created_at: DateTime, default=utcnow - - updated_at: DateTime, onupdate=utcnow - - **backend/models/team.py:** - - TeamAnalysis model: - - id: Integer, primary key, autoincrement - - team_name: String - - team_skills: Text (JSON string) - - project_requirements: Text (JSON string) - - coverage_score: Float, nullable - - skill_gaps: Text (JSON string) - - hire_plan: Text (JSON string) - - analysis_result: Text (full JSON result blob) - - created_at: DateTime, default=utcnow - - updated_at: DateTime, onupdate=utcnow - - **Update backend/models/__init__.py:** - - Export Base, init_db, get_db, CandidateAnalysis, TeamAnalysis - - **Update backend/main.py lifespan:** - - Call init_db() inside the lifespan async context manager on startup - - Log "Database initialized" on success - - AVOID: - - Do NOT use Alembic migrations — overkill for hackathon, create_all() is sufficient - - Do NOT add relationships between models yet — keep flat - - Do NOT store binary blobs (PDFs) in DB — only analysis results - - - python3 -c "from backend.models import Base, CandidateAnalysis, TeamAnalysis; print('Models imported OK')" - # Start server and check that hiresense.db is created - ls -la hiresense.db - - - - All model files exist with correct column definitions - - Models import without errors - - Server startup creates hiresense.db automatically - - Tables candidate_analyses and team_analyses exist in the database - - - - - Add analysis history endpoints - - backend/api/routes/candidates.py - backend/api/routes/teams.py - - - **candidates.py — add:** - - GET /candidates/history — return list of past analyses (id, name, match_score, created_at) - - GET /candidates/{id} — return full analysis result by ID - - **teams.py — add:** - - GET /teams/history — return list of past team analyses (id, team_name, coverage_score, created_at) - - GET /teams/{id} — return full team analysis result by ID - - Both use the get_db dependency for database sessions. - Return empty lists initially (no analyses exist yet). - - AVOID: - - Do NOT add DELETE endpoints — not needed for hackathon - - Do NOT add pagination — keep simple for now - - - curl -s http://localhost:8000/api/candidates/history | python3 -m json.tool - curl -s http://localhost:8000/api/teams/history | python3 -m json.tool - - - - GET /api/candidates/history returns [] (empty list) - - GET /api/teams/history returns [] (empty list) - - GET /api/candidates/999 returns 404 - - GET /api/teams/999 returns 404 - - - -## Success Criteria -- [ ] Database file (hiresense.db) is auto-created on server startup -- [ ] candidate_analyses and team_analyses tables exist with correct columns -- [ ] History endpoints return empty lists when no data exists -- [ ] 404 responses for non-existent analysis IDs diff --git a/.gsd/phases/1/2-SUMMARY.md b/.gsd/phases/1/2-SUMMARY.md deleted file mode 100644 index e04d3cb4dadf2547aa916f69b2ef1f970c1788e4..0000000000000000000000000000000000000000 --- a/.gsd/phases/1/2-SUMMARY.md +++ /dev/null @@ -1,16 +0,0 @@ -# Plan 1.2 Summary: SQLite Database Models & Initialization - -## Status: ✅ Complete - -## What was done -- SQLAlchemy engine + session factory in `backend/models/database.py` -- CandidateAnalysis model: id, name, email, github/leetcode usernames, skills, scores, analysis_result JSON, timestamps -- TeamAnalysis model: id, team_name, team_skills, project_requirements, coverage_score, skill_gaps, hire_plan, timestamps -- Database auto-initializes on server startup via lifespan handler -- History endpoints: GET /api/candidates/history, GET /api/teams/history -- Detail endpoints: GET /api/candidates/{id}, GET /api/teams/{id} (with 404 handling) - -## Verification -- hiresense.db auto-created on startup ✓ -- History endpoints return empty lists ✓ -- Non-existent IDs return 404 ✓ diff --git a/.gsd/phases/1/3-PLAN.md b/.gsd/phases/1/3-PLAN.md deleted file mode 100644 index f3ae8f0eac96bdc186dbb959f55a061711260447..0000000000000000000000000000000000000000 --- a/.gsd/phases/1/3-PLAN.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -phase: 1 -plan: 3 -wave: 2 ---- - -# Plan 1.3: Frontend Shell & Static File Serving - -## Objective -Create the frontend HTML/CSS/JS shell with a premium, modern dark-themed dashboard. Two views: Candidate Analysis and Team Analysis, switchable via navigation tabs. The UI should feel production-grade from day one — this is what the hackathon judges see first. - -## Context -- .gsd/SPEC.md — Plain HTML/CSS/JS frontend, two user flows -- .gsd/DECISIONS.md — ADR-002 (vanilla frontend) -- backend/main.py — Static file mount at / - -## Tasks - - - Create frontend directory structure and HTML shell - - frontend/index.html - frontend/css/style.css - frontend/js/app.js - frontend/js/api.js - - - **Directory structure:** - ``` - frontend/ - ├── index.html # Single-page app shell - ├── css/ - │ └── style.css # Complete design system - └── js/ - ├── app.js # View switching, UI orchestration - └── api.js # API client (fetch wrapper) - ``` - - **index.html specifics:** - - Single HTML page with two switchable views - - Header: "HireSense AI" branding with icon/logo area - - Navigation: Two tabs — "🔍 Candidate Analysis" and "🏢 Team Analysis" - - Candidate Analysis view: - - Upload area: drag-and-drop zone for resume PDF - - Text area: paste job description - - "Analyze" button - - Results panel (empty placeholder, will be populated in Phase 5) - - Team Analysis view: - - Form: team name, team skills (textarea/tags), project requirements (textarea) - - "Analyze Team" button - - Results panel (empty placeholder) - - Footer: "HireSense AI v1.0 • Decision Intelligence for Startups" - - Load Google Font: Inter or Outfit - - Meta tags for SEO - - **css/style.css specifics:** - Create a premium dark-themed design system: - - CSS custom properties for the full color palette - - Dark background (#0a0a0f or similar deep navy/black) - - Accent colors: electric blue (#6366f1 indigo) + emerald green (#10b981) for positive signals - - Warning: amber (#f59e0b), Error: red (#ef4444) - - Glassmorphism cards (backdrop-filter: blur, subtle borders) - - Smooth transitions on all interactive elements (0.2-0.3s ease) - - Typography: Inter/Outfit from Google Fonts, proper hierarchy (h1-h3, body text) - - Responsive grid layout (single column on mobile, two-column on desktop) - - Upload zone: dashed border, hover effect, drag-active state - - Tab navigation: pill-style tabs with active indicator animation - - Buttons: gradient backgrounds, hover glow effects - - Input fields: dark background, subtle border, focus glow - - Scrollbar styling for webkit - - Loading spinner/pulse animation (for later use) - - Status badges (success, warning, error, info) with colored dots - - **js/api.js specifics:** - - API base URL constant (http://localhost:8000/api) - - Async functions: - - checkHealth() — GET /api/health - - analyzeCandidateStub(formData) — POST /api/candidates/analyze - - analyzeTeamStub(data) — POST /api/teams/analyze - - getCandidateHistory() — GET /api/candidates/history - - getTeamHistory() — GET /api/teams/history - - Error handling wrapper with user-friendly error messages - - **js/app.js specifics:** - - Tab switching logic (show/hide views, update active tab) - - Drag-and-drop file upload handling (visual feedback, file validation — PDF only) - - Form submission handlers (wired to api.js stubs) - - Health check on page load (show connection status indicator) - - Toast notification system for success/error messages - - AVOID: - - Do NOT use any CSS framework (Tailwind, Bootstrap, etc.) - - Do NOT make it look basic/minimal — this is a hackathon showcase - - Do NOT implement actual analysis logic — just wire up the UI to placeholder API - - Do NOT use generic colors — use a curated, premium palette - - - # Start backend server and visit http://localhost:8000 - # Verify: - # 1. Page loads with dark theme - # 2. Both tabs switch views correctly - # 3. Upload zone accepts drag & drop - # 4. Health indicator shows connected - # 5. Forms submit and show placeholder response - curl -s http://localhost:8000/ | head -20 - - - - index.html loads at http://localhost:8000/ - - Dark theme with premium glassmorphism design is visible - - Two tabs (Candidate / Team) switch views - - Drag-and-drop upload zone works (visual feedback on drag) - - Job description text area is present - - Team analysis form has all fields - - Health check runs on load and shows status - - All interactive elements have smooth hover/transition effects - - Responsive layout works on different screen sizes - - - - - Visual verification of frontend shell - frontend/index.html - - Open http://localhost:8000 in a browser and verify: - 1. The design looks premium and hackathon-ready - 2. Dark theme is visually appealing - 3. Tab switching is smooth - 4. Upload drag-and-drop has visual feedback - 5. All text is readable and well-sized - 6. Layout is responsive - - Take a screenshot or use the browser tool for verification. - - Open browser to http://localhost:8000 and capture screenshot - User confirms the frontend shell looks premium and functional - - -## Success Criteria -- [ ] http://localhost:8000 serves the frontend shell -- [ ] Premium dark-themed design with glassmorphism, smooth animations -- [ ] Two-tab navigation (Candidate Analysis / Team Analysis) works -- [ ] Drag-and-drop upload zone shows visual feedback -- [ ] API client successfully calls health endpoint -- [ ] Design quality is hackathon-presentation-ready diff --git a/.gsd/phases/1/3-SUMMARY.md b/.gsd/phases/1/3-SUMMARY.md deleted file mode 100644 index 6eee8d462a69fa36ca4fa93ca4f9b93364dc2621..0000000000000000000000000000000000000000 --- a/.gsd/phases/1/3-SUMMARY.md +++ /dev/null @@ -1,25 +0,0 @@ -# Plan 1.3 Summary: Frontend Shell & Static File Serving - -## Status: ✅ Complete - -## What was done -- `frontend/index.html`: Single-page shell with header, two-tab nav, two views, toast container, footer -- `frontend/css/style.css`: 600+ line premium dark theme with glassmorphism, CSS custom properties, responsive layout -- `frontend/js/api.js`: Fetch wrapper with error handling, all API endpoint functions -- `frontend/js/app.js`: Tab switching, drag-and-drop upload (PDF validation, size check), form validation, health check, toast notifications - -## Design highlights -- Deep navy/black background with subtle animated gradient -- Glassmorphism cards with backdrop-filter blur -- Indigo (#6366f1) accent + emerald green for success states -- Inter font from Google Fonts -- Smooth transitions on all interactive elements -- Responsive: 2-column → 1-column on mobile - -## Verification -- Page loads at http://localhost:8000 ✓ -- Premium dark theme with glassmorphism visible ✓ -- Tab switching works (Candidate ↔ Team) ✓ -- Upload zone shows drag feedback ✓ -- Connection status shows green dot + v1.0.0 ✓ -- Responsive layout works ✓ diff --git a/.gsd/phases/10/1-PLAN.md b/.gsd/phases/10/1-PLAN.md deleted file mode 100644 index 51bfbd5e9f95398371b7e672dbd877f70bb86dba..0000000000000000000000000000000000000000 --- a/.gsd/phases/10/1-PLAN.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -phase: 10 -plan: 1 -wave: 1 ---- - -# Plan 10.1: Team Gap Analysis UI Overhaul & Data Mapping Fix - -## Objective -The Team Gap Analysis pipeline currently suffers from two distinct problems: -1. **Data Mapping Bug**: The frontend expects `role_title`, `salary_benchmark`, and `job_description` directly inside the `hire_plan` array. However, the FastApi backend returns `"role"`, `"salary": {...}`, and places the JDs into a completely separate `job_descriptions` array. This causes "undefined" or empty states on the UI for Salaries and JDs. -2. **Aesthetic Debt**: The team gap dashboard feels visually sparse and lacks the premium Shadcn/vibrant aesthetic recently successfully applied to the Candidate Evaluation dashboard. - -## Context -- .gsd/ROADMAP.md -- frontend/src/components/dashboard/TeamView.tsx -- backend/api/routes/teams.py - -## Tasks - - - Fix Frontend Data Mapping in TeamView.tsx - frontend/src/components/dashboard/TeamView.tsx - - - Update `{role.role_title}` to `{role.role}` mapping the API correctly. - - Update `{role.salary_benchmark}` to `{role.salary?.formatted}` or fallback. - - Fetch the job description from the companion array `{result.job_descriptions?.[i]?.description || "Generating JD..."}`. - - Ensure the mock or test API payload successfully displays JD snippet and Salary on the UI. - Frontend data binding reflects the `teams.py` response structure. - - - - Redesign Hiring Plan and Coverge UI - frontend/src/components/dashboard/TeamView.tsx - - - Enhance the "Generated Hiring Plan" cards. Use premium styling (soft colors, CardFooter with copy-clipboard buttons). - - Enhance the "Architectural coverage" ring and Domain Deficits list with clear Shadcn aesthetic markers (distinct borders, better spacing, and dynamic badges for Urgency). - - Visually verify the new UI components render cleanly on the localhost NextJS server. - Team Gap side visually aligns with the pristine quality of the Candidate Evaluator. - - -## Success Criteria -- [ ] Role titles, Salary, and JD Snippets are no longer missing/undefined. -- [ ] Team Gap Analysis UI matches premium styling guidelines. diff --git a/.gsd/phases/2/1-PLAN.md b/.gsd/phases/2/1-PLAN.md deleted file mode 100644 index d48bafd3c33f491e1f6fafd13ad80212959c47e7..0000000000000000000000000000000000000000 --- a/.gsd/phases/2/1-PLAN.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -phase: 2 -plan: 1 -wave: 1 ---- - -# Plan 2.1: Resume Parser Service - -## Objective -Build the resume parser that extracts structured data from PDF resumes — candidate name, email, phone, skills, projects, experience sections, and external profile links (GitHub, LeetCode). This is the entry point of the entire analysis pipeline. - -## Context -- .gsd/SPEC.md — REQ-01: Parse PDF resumes and extract structured fields -- .gsd/phases/2/RESEARCH.md — Resume parsing approach (pdfplumber + regex + keyword matching) -- backend/config.py — Settings for upload directory -- backend/models/candidate.py — CandidateAnalysis model - -## Tasks - - - Create resume parser service - - backend/services/resume_parser.py - backend/services/skill_dictionary.py - - - **backend/services/skill_dictionary.py:** - Create a comprehensive skill dictionary for matching. Structure as a Python dict: - ```python - SKILL_CATEGORIES = { - "languages": ["python", "javascript", "typescript", "java", "c++", "c#", "go", "rust", "ruby", "php", "swift", "kotlin", "scala", "r", "matlab", "sql", "html", "css"], - "frontend": ["react", "angular", "vue", "svelte", "next.js", "nuxt", "tailwind", "bootstrap", "jquery", "redux", "webpack", "vite"], - "backend": ["node.js", "express", "fastapi", "flask", "django", "spring boot", "rails", "laravel", "asp.net", "gin", "fiber"], - "databases": ["postgresql", "mysql", "mongodb", "redis", "sqlite", "elasticsearch", "cassandra", "dynamodb", "firebase", "supabase"], - "devops": ["docker", "kubernetes", "aws", "azure", "gcp", "terraform", "ansible", "jenkins", "github actions", "ci/cd", "nginx", "linux"], - "ml_ai": ["machine learning", "deep learning", "tensorflow", "pytorch", "scikit-learn", "pandas", "numpy", "nlp", "computer vision", "llm", "transformers", "hugging face", "opencv"], - "tools": ["git", "jira", "figma", "postman", "grafana", "prometheus", "kafka", "rabbitmq", "graphql", "rest api", "websocket"], - } - ``` - Also create a flattened set `ALL_SKILLS` for fast lookup, and a function `normalize_skill(skill) -> str` that lowercases and strips whitespace. - - **backend/services/resume_parser.py:** - Create a `ResumeParser` class with these methods: - - `parse(pdf_path: str) -> dict`: - Main entry point. Returns structured dict: - ```python - { - "name": str or None, - "email": str or None, - "phone": str or None, - "github_url": str or None, - "github_username": str or None, - "leetcode_url": str or None, - "leetcode_username": str or None, - "linkedin_url": str or None, - "skills": [str], # extracted skills - "experience": [dict], # list of experience entries - "projects": [dict], # list of project entries - "education": [dict], # list of education entries - "raw_text": str, # full extracted text - } - ``` - - `_extract_text(pdf_path: str) -> str`: - Use pdfplumber to extract all text from all pages. Handle multi-page PDFs. - - `_extract_contact(text: str) -> dict`: - Use regex to extract: - - Email: r'[\w.-]+@[\w.-]+\.\w+' - - Phone: r'[\+]?[\d\s\-\(\)]{10,}' - - GitHub URL: r'github\.com/([a-zA-Z0-9_-]+)' - - LeetCode URL: r'leetcode\.com/(?:u/)?([a-zA-Z0-9_-]+)' - - LinkedIn URL: r'linkedin\.com/in/([a-zA-Z0-9_-]+)' - - `_extract_name(text: str) -> str`: - Take the first non-empty line of the resume (common convention). - Validate it doesn't look like an email or URL. - - `_extract_skills(text: str) -> list[str]`: - 1. Lowercase the full text - 2. For each skill in ALL_SKILLS, check if it appears in the text - 3. Also check for multi-word skills (e.g., "machine learning") - 4. Return deduplicated, sorted list - - `_extract_sections(text: str) -> dict`: - Use regex to detect section headers like: - - "EXPERIENCE", "WORK EXPERIENCE", "EMPLOYMENT" - - "PROJECTS", "PERSONAL PROJECTS" - - "EDUCATION", "ACADEMIC" - Split text into sections. For each experience/project entry, extract: - - title/role - - organization (if present) - - description text - - AVOID: - - Do NOT use spaCy NER for name extraction — it's unreliable on resumes and adds startup time. Simple first-line heuristic is more reliable. - - Do NOT try to extract dates/durations — too complex for MVP, not needed for scoring. - - Do NOT import sentence_transformers here — that's Phase 3. - - - python3 -c " -from backend.services.resume_parser import ResumeParser -parser = ResumeParser() -print('ResumeParser imported OK') -print(f'Skill categories: {len(parser.skill_dict)}') -" - - - - ResumeParser class exists and imports without error - - parse() method accepts a PDF path and returns structured dict - - Regex patterns extract email, phone, GitHub/LeetCode URLs - - Skill dictionary has 7+ categories with 80+ skills - - Section detection splits resumes into experience/projects/education - - - - - Wire resume upload to API endpoint - - backend/api/routes/candidates.py - - - Update the POST /candidates/analyze endpoint: - 1. Accept `resume: UploadFile` and `job_description: str = Form(...)` - 2. Save uploaded PDF to `{UPLOAD_DIR}/{timestamp}_{filename}` - 3. Run `ResumeParser().parse(saved_path)` on it - 4. Extract GitHub/LeetCode usernames from parsed results - 5. Return the parsed profile as JSON (analysis scoring comes in Phase 3) - 6. Save initial record to database (CandidateAnalysis) with parsed fields - - Response structure (for now): - ```json - { - "id": 1, - "status": "parsed", - "candidate": { - "name": "...", - "email": "...", - "skills": [...], - "github_username": "...", - "leetcode_username": "..." - }, - "message": "Resume parsed. GitHub/LeetCode analysis pending." - } - ``` - - AVOID: - - Do NOT run GitHub/LeetCode analysis in this task — that's wired in Plan 2.3 - - Do NOT compute scores — that's Phase 3 - - - # Create a test PDF and upload it - curl -X POST http://localhost:8000/api/candidates/analyze \ - -F "resume=@test_resume.pdf" \ - -F "job_description=Looking for a Python developer" - - - - POST /api/candidates/analyze accepts file upload + job description - - Uploaded PDF is saved to uploads/ directory - - Response contains parsed candidate data (name, email, skills, usernames) - - Record saved to database with parsed fields - - - -## Success Criteria -- [ ] Resume parser extracts structured data from PDF files -- [ ] Skills matched against skill dictionary (80+ skills) -- [ ] GitHub/LeetCode profile links detected via regex -- [ ] API endpoint accepts file upload and returns parsed profile diff --git a/.gsd/phases/2/1-SUMMARY.md b/.gsd/phases/2/1-SUMMARY.md deleted file mode 100644 index c8e98746231449b17a4f5e42874b5d1fe432fa9e..0000000000000000000000000000000000000000 --- a/.gsd/phases/2/1-SUMMARY.md +++ /dev/null @@ -1,11 +0,0 @@ -# Plan 2.1 Summary: Resume Parser Service - -## Status: ✅ Complete - -## What was done -- `backend/services/skill_dictionary.py`: 232 skills across 9 categories with matching/normalization -- `backend/services/resume_parser.py`: PDF extraction (pdfplumber), regex contact/link detection (email, phone, GitHub, LeetCode, LinkedIn), name heuristic, section parsing (experience/projects/education), skill matching - -## Verification -- Imports without error ✓ -- Test PDF: extracted "John Doe", email, phone, GitHub/LeetCode usernames, 12 skills ✓ diff --git a/.gsd/phases/2/2-PLAN.md b/.gsd/phases/2/2-PLAN.md deleted file mode 100644 index 307a0c190414ca38f7e5ef18c7dcd28f51afed0b..0000000000000000000000000000000000000000 --- a/.gsd/phases/2/2-PLAN.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -phase: 2 -plan: 2 -wave: 1 ---- - -# Plan 2.2: GitHub Analyzer Service - -## Objective -Build the GitHub analyzer that fetches developer activity data via the REST API and computes four scores: consistency, project depth, tech breadth, and recency. These scores become key signals in the candidate analysis pipeline. - -## Context -- .gsd/SPEC.md — REQ-02, REQ-03: Fetch GitHub data and compute scores -- .gsd/phases/2/RESEARCH.md — GitHub REST API endpoints and auth pattern -- backend/config.py — GITHUB_TOKEN setting - -## Tasks - - - Create GitHub analyzer service - - backend/services/github_analyzer.py - - - Create a `GitHubAnalyzer` class: - - **__init__(self, token: str = None):** - - Store token for auth header - - Set base_url = "https://api.github.com" - - Set headers with Accept: application/vnd.github.v3+json - - **analyze(self, username: str) -> dict:** - Main entry point. Returns: - ```python - { - "username": str, - "profile": { - "name": str, - "bio": str, - "public_repos": int, - "followers": int, - "following": int, - "created_at": str, - }, - "scores": { - "consistency": float, # 0-100 - "project_depth": float, # 0-100 - "tech_breadth": float, # 0-100 - "recency": float, # 0-100 - "overall": float, # weighted average - }, - "details": { - "total_repos": int, - "total_stars": int, - "total_commits_sampled": int, - "languages": {str: int}, # language -> bytes - "top_repos": [dict], # top 5 repos by stars - "commit_frequency": dict, # monthly commit counts - "active_days": int, # days with commits in last year - }, - "explanations": { - "consistency": str, - "project_depth": str, - "tech_breadth": str, - "recency": str, - } - } - ``` - - **_fetch_profile(self, username: str) -> dict:** - GET /users/{username} — extract key fields. - Handle 404 (user not found) gracefully. - - **_fetch_repos(self, username: str) -> list:** - GET /users/{username}/repos?per_page=100&sort=pushed - For each repo, capture: name, stars, forks, language, updated_at, fork (bool). - Filter out forks (only count original repos). - - **_fetch_languages(self, username: str, repos: list) -> dict:** - For top 10 repos (by stars), GET /repos/{username}/{repo}/languages. - Aggregate bytes per language across all repos. - - **_fetch_commit_activity(self, username: str, repos: list) -> dict:** - For top 5 repos, GET /repos/{username}/{repo}/commits?per_page=100. - Extract commit dates, bucket by month. - Count unique days with commits. - - **_calculate_consistency_score(self, commit_data: dict) -> tuple[float, str]:** - Measure how evenly distributed commits are across months. - - Calculate coefficient of variation of monthly commit counts - - Low CV = high consistency → score 80-100 - - High CV = irregular bursts → score 20-60 - - No commits → score 0 - Return (score, explanation_string). - - **_calculate_project_depth_score(self, repos: list) -> tuple[float, str]:** - Based on total stars, watchers, and commit count of top repos. - - Weight: stars * 3 + forks * 2 + (commits > 50 bonus) - - Normalize to 0-100 scale - Return (score, explanation_string). - - **_calculate_tech_breadth_score(self, languages: dict) -> tuple[float, str]:** - Count distinct languages used. - - 1-2 languages → 20-40 - - 3-5 languages → 50-70 - - 6+ languages → 80-100 - Bonus for diversity across paradigms (e.g., Python + JS + Go). - Return (score, explanation_string). - - **_calculate_recency_score(self, repos: list, commit_data: dict) -> tuple[float, str]:** - Based on most recent commit/push date. - - Within last week → 100 - - Within last month → 85 - - Within last 3 months → 65 - - Within last year → 40 - - Older → 10 - Return (score, explanation_string). - - **Error handling:** - - If username not found → return error dict with "user_not_found": True - - If rate limited → return partial results with "rate_limited": True warning - - If no token → still works but with lower rate limit, add warning - - AVOID: - - Do NOT fetch ALL commits for ALL repos — too slow. Sample top 5 repos, 100 commits each. - - Do NOT use GraphQL API — stick to REST for simplicity and our research findings. - - Do NOT cache results — keep stateless for MVP. - - - python3 -c " -from backend.services.github_analyzer import GitHubAnalyzer -analyzer = GitHubAnalyzer() -print('GitHubAnalyzer imported OK') -# Quick test with a known public user -result = analyzer.analyze('torvalds') -print(f'Profile: {result[\"profile\"][\"name\"]}') -print(f'Scores: {result[\"scores\"]}') -" - - - - GitHubAnalyzer class exists and imports without error - - analyze() returns profile, 4 scores (0-100), details, and explanations - - Handles user not found gracefully - - Works without token (with rate limit warning) - - Top repos, languages, and commit data extracted correctly - - - -## Success Criteria -- [ ] GitHub analyzer fetches real data from GitHub API -- [ ] Four scores computed: consistency, project depth, tech breadth, recency -- [ ] Each score has a human-readable explanation -- [ ] Error handling for missing users and rate limits diff --git a/.gsd/phases/2/2-SUMMARY.md b/.gsd/phases/2/2-SUMMARY.md deleted file mode 100644 index 258b88a9dbc4597d43e586b7b0bafade2eb766c2..0000000000000000000000000000000000000000 --- a/.gsd/phases/2/2-SUMMARY.md +++ /dev/null @@ -1,13 +0,0 @@ -# Plan 2.2 Summary: GitHub Analyzer Service - -## Status: ✅ Complete - -## What was done -- `backend/services/github_analyzer.py`: REST API integration with optional PAT auth -- Four scored dimensions: consistency (CV of monthly commits), project depth (stars/forks), tech breadth (language diversity), recency (last activity) -- Each score includes a human-readable explanation -- Error handling: user not found, rate limits, missing token - -## Verification -- Imports without error ✓ -- Real user (torvalds): consistency=16, project_depth=100, tech_breadth=30, recency=95, overall=59.5 ✓ diff --git a/.gsd/phases/2/3-PLAN.md b/.gsd/phases/2/3-PLAN.md deleted file mode 100644 index caf04457c47d76df909b6181d153ea423f458ce4..0000000000000000000000000000000000000000 --- a/.gsd/phases/2/3-PLAN.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -phase: 2 -plan: 3 -wave: 2 ---- - -# Plan 2.3: LeetCode Analyzer + Full Pipeline Wiring - -## Objective -Build the LeetCode analyzer using the GraphQL endpoint, then wire all three services (resume parser, GitHub analyzer, LeetCode analyzer) into the candidate analysis API endpoint to produce a complete candidate profile with all external data fetched and scored. - -## Context -- .gsd/SPEC.md — REQ-04: Fetch LeetCode data via GraphQL -- .gsd/phases/2/RESEARCH.md — LeetCode GraphQL queries -- backend/services/resume_parser.py — Built in Plan 2.1 -- backend/services/github_analyzer.py — Built in Plan 2.2 -- backend/api/routes/candidates.py — Endpoint to update - -## Tasks - - - Create LeetCode analyzer service - - backend/services/leetcode_analyzer.py - - - Create a `LeetCodeAnalyzer` class: - - **analyze(self, username: str) -> dict:** - Main entry point. Returns: - ```python - { - "username": str, - "profile": { - "ranking": int, - "reputation": int, - }, - "problems": { - "total_solved": int, - "easy": int, - "medium": int, - "hard": int, - }, - "scores": { - "problem_solving": float, # 0-100 - "difficulty_balance": float, # 0-100 - "overall": float, # weighted average - }, - "details": { - "easy_percentage": float, - "medium_percentage": float, - "hard_percentage": float, - "streak": int, - "total_active_days": int, - }, - "explanations": { - "problem_solving": str, - "difficulty_balance": str, - } - } - ``` - - **_fetch_user_data(self, username: str) -> dict:** - POST to https://leetcode.com/graphql with query: - ```graphql - query getUserProfile($username: String!) { - matchedUser(username: $username) { - username - submitStatsGlobal { - acSubmissionNum { - difficulty - count - } - } - profile { - ranking - reputation - } - userCalendar { - streak - totalActiveDays - } - } - } - ``` - Headers: Content-Type: application/json, Referer: https://leetcode.com - Handle user not found (matchedUser returns null). - - **_calculate_problem_solving_score(self, problems: dict) -> tuple[float, str]:** - Weighted score: - - easy: 1 point each - - medium: 3 points each - - hard: 5 points each - Normalize: 0-50 weighted points → 0-40 score, 50-200 → 40-80, 200+ → 80-100. - Return (score, explanation). - - **_calculate_difficulty_balance_score(self, problems: dict) -> tuple[float, str]:** - Ideal ratio is roughly 40% easy, 40% medium, 20% hard. - - Pure easy → 20 - - Good mix → 70-90 - - Heavy on hard → 90-100 - Return (score, explanation). - - **Error handling:** - - User not found → return error dict with "user_not_found": True - - GraphQL error → return partial results with warning - - AVOID: - - Do NOT scrape HTML — use only the GraphQL endpoint - - Do NOT try to get submission details — just counts by difficulty - - - python3 -c " -from backend.services.leetcode_analyzer import LeetCodeAnalyzer -analyzer = LeetCodeAnalyzer() -print('LeetCodeAnalyzer imported OK') -result = analyzer.analyze('neal_wu') -print(f'Problems solved: {result[\"problems\"][\"total_solved\"]}') -print(f'Scores: {result[\"scores\"]}') -" - - - - LeetCodeAnalyzer class exists and imports without error - - analyze() hits the GraphQL endpoint and returns problem stats - - Two scores computed: problem_solving, difficulty_balance - - Each score has explanation - - Handles user not found gracefully - - - - - Wire full pipeline into candidate analysis endpoint - - backend/api/routes/candidates.py - backend/services/__init__.py - - - **Update backend/api/routes/candidates.py:** - Modify POST /candidates/analyze to run the full pipeline: - - 1. Accept `resume: UploadFile` and `job_description: str = Form(...)` - 2. Save PDF, run ResumeParser - 3. If GitHub username found → run GitHubAnalyzer - 4. If LeetCode username found → run LeetCodeAnalyzer - 5. If usernames NOT found in resume, accept optional form fields: - - `github_username: Optional[str] = Form(None)` - - `leetcode_username: Optional[str] = Form(None)` - 6. Assemble complete candidate profile - 7. Save to database (CandidateAnalysis record) - 8. Return full result - - Response structure: - ```json - { - "id": 1, - "status": "analyzed", - "candidate": { - "name": "John Doe", - "email": "john@email.com", - "skills": ["python", "react", "docker"], - "github_username": "johndoe", - "leetcode_username": "johndoe" - }, - "github_analysis": { - "scores": { ... }, - "details": { ... }, - "explanations": { ... } - }, - "leetcode_analysis": { - "problems": { ... }, - "scores": { ... }, - "explanations": { ... } - }, - "job_description": "...", - "message": "Candidate profile analyzed. ML scoring available in Phase 3." - } - ``` - - **Update backend/services/__init__.py:** - Export all three services for easy importing. - - AVOID: - - Do NOT run GitHub/LeetCode analysis synchronously if it takes too long — but for MVP, synchronous is fine since it's only 2 API calls - - Do NOT compute match score, learning ability, or credibility — that's Phase 3 - - - # Test with a real resume PDF - curl -X POST http://localhost:8000/api/candidates/analyze \ - -F "resume=@test_resume.pdf" \ - -F "job_description=Looking for a Python developer with React experience" \ - -F "github_username=torvalds" \ - -F "leetcode_username=neal_wu" | python3 -m json.tool - - - - POST /api/candidates/analyze runs full pipeline - - Response includes parsed resume + GitHub scores + LeetCode scores - - Record saved to database with all available data - - Optional github/leetcode username override works - - Missing usernames handled gracefully (partial results returned) - - - -## Success Criteria -- [ ] LeetCode analyzer fetches real data from GraphQL endpoint -- [ ] Problem-solving and difficulty scores computed with explanations -- [ ] Full pipeline: upload PDF → parse → fetch GitHub → fetch LeetCode → return combined result -- [ ] Database record created with all analysis data -- [ ] Works end-to-end with real GitHub/LeetCode usernames diff --git a/.gsd/phases/2/3-SUMMARY.md b/.gsd/phases/2/3-SUMMARY.md deleted file mode 100644 index c15dffb7fde30b58fd31e7c56498df4cd8c719b2..0000000000000000000000000000000000000000 --- a/.gsd/phases/2/3-SUMMARY.md +++ /dev/null @@ -1,15 +0,0 @@ -# Plan 2.3 Summary: LeetCode Analyzer + Pipeline Wiring - -## Status: ✅ Complete - -## What was done -- `backend/services/leetcode_analyzer.py`: GraphQL API integration, problem-solving + difficulty balance scores -- Updated `POST /api/candidates/analyze` to run full pipeline: - - Accept PDF upload + job description + optional username overrides - - Parse resume → fetch GitHub data → fetch LeetCode data → assemble JSON → save to DB -- Updated `backend/services/__init__.py` to export all services - -## Verification -- LeetCode real user (neal_wu): 253 problems (60E/141M/52H), problem_solving=92, difficulty_balance=90 ✓ -- Full pipeline API call returns combined GitHub + LeetCode + resume data ✓ -- DB record saved with id=1 ✓ diff --git a/.gsd/phases/2/RESEARCH.md b/.gsd/phases/2/RESEARCH.md deleted file mode 100644 index 9931cedb9f8c8484b1bb6bee46d1bf6c6a5c009e..0000000000000000000000000000000000000000 --- a/.gsd/phases/2/RESEARCH.md +++ /dev/null @@ -1,70 +0,0 @@ -# Phase 2 Research — External API Integrations - -## LeetCode GraphQL API - -**Endpoint**: `https://leetcode.com/graphql` -**Auth**: None required (public profiles) - -### Key Queries - -**User profile + problem stats:** -```graphql -query getUserProfile($username: String!) { - matchedUser(username: $username) { - username - submitStatsGlobal { - acSubmissionNum { - difficulty - count - } - } - profile { - ranking - reputation - } - userCalendar { - streak - totalActiveDays - } - } -} -``` - -**Headers required**: `Content-Type: application/json`, `Referer: https://leetcode.com` - -**Rate limiting**: Informal — use reasonable delays. No PAT system. - ---- - -## GitHub REST API - -**Base URL**: `https://api.github.com` -**Auth**: `Authorization: Bearer {PAT}` → 5000 req/hour (vs 60 unauthenticated) - -### Key Endpoints - -| Data | Endpoint | Notes | -|------|----------|-------| -| User profile | `GET /users/{username}` | public_repos, created_at, followers | -| User repos | `GET /users/{username}/repos?per_page=100&sort=updated` | stars, language, updated_at | -| Repo languages | `GET /repos/{owner}/{repo}/languages` | bytes per language | -| Repo commits | `GET /repos/{owner}/{repo}/commits?per_page=100` | commit dates for consistency | -| User events | `GET /users/{username}/events?per_page=100` | recent activity (last 90 days) | - -### Python Pattern -```python -headers = {"Authorization": f"Bearer {token}"} if token else {} -response = requests.get(url, headers=headers) -``` - ---- - -## Resume Parsing (pdfplumber + spaCy + regex) - -- **pdfplumber**: Extract text from PDF pages -- **Regex**: Extract emails, URLs (GitHub/LeetCode profile links), phone numbers -- **spaCy NER**: Extract person names, organization names -- **Keyword matching**: Skills extraction against a skill dictionary -- **Section detection**: Experience, Education, Projects via heading patterns - -No external API needed — all local processing. diff --git a/.gsd/phases/3/1-PLAN.md b/.gsd/phases/3/1-PLAN.md deleted file mode 100644 index 4d4795e111fa7bc19f69a3fa9d1105ed81c685bd..0000000000000000000000000000000000000000 --- a/.gsd/phases/3/1-PLAN.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -phase: 3 -plan: 1 -wave: 1 ---- - -# Plan 3.1: Skill Similarity Matcher - -## Objective -Build the semantic skill matcher that computes how well a candidate's skills (from resume + GitHub languages) match the requirements in a job description. Uses sentence-transformers embeddings for semantic similarity rather than naive keyword overlap, so "React" matches "frontend development" and "PostgreSQL" matches "relational databases". - -## Context -- .gsd/SPEC.md — REQ-05: Skill similarity matching using sentence embeddings -- backend/services/skill_dictionary.py — Skill categories and matching -- backend/services/resume_parser.py — How skills are extracted -- backend/services/github_analyzer.py — GitHub languages output - -## Tasks - - - Create skill matcher service - - backend/services/skill_matcher.py - - - Create a `SkillMatcher` class: - - **__init__(self):** - - Load a lightweight sentence-transformers model: `all-MiniLM-L6-v2` (fast, 22M params) - - Cache the model as a class attribute to avoid reloading on every call - - Lazy-load: only initialize model on first use - - **match(self, candidate_skills: list[str], job_description: str, github_languages: dict = None) -> dict:** - Main entry point. Returns: - ```python - { - "match_score": float, # 0-100 overall match - "matched_skills": [str], # skills that match JD - "missing_skills": [str], # JD requirements not in candidate skills - "bonus_skills": [str], # candidate skills beyond JD requirements - "category_scores": { # score per category - "languages": float, - "frontend": float, - "backend": float, - ... - }, - "explanation": str, # human-readable summary - "details": { - "jd_requirements": [str], # skills extracted from JD - "semantic_matches": [ # detailed match pairs - {"candidate_skill": str, "jd_requirement": str, "similarity": float} - ], - } - } - ``` - - **_extract_jd_skills(self, job_description: str) -> list[str]:** - 1. Use `find_skills_in_text()` from skill_dictionary for explicit skill mentions - 2. Also extract key phrases that might be implicit skill requirements - (e.g., "building scalable systems" → infrastructure/devops) - - **_compute_semantic_similarity(self, skills_a: list[str], skills_b: list[str]) -> list[dict]:** - 1. Encode both lists with sentence-transformers - 2. Compute cosine similarity matrix - 3. For each JD skill, find best matching candidate skill - 4. Threshold: similarity >= 0.5 counts as a match - 5. Return list of {candidate_skill, jd_requirement, similarity} - - **_merge_skills(self, resume_skills: list[str], github_languages: dict) -> list[str]:** - Combine resume skills with GitHub language names (lowercased). - Deduplicate using `normalize_skill()`. - - **_calculate_match_score(self, matched: list, total_required: int) -> float:** - Score = (matched_count / total_required) * 100 with diminishing returns. - Cap at 100. - - **_generate_explanation(self, score: float, matched: list, missing: list, bonus: list) -> str:** - Human-readable summary, e.g.: - "Strong match (82/100). Candidate covers 8/10 required skills. - Missing: Kubernetes, Terraform. Bonus skills: Machine Learning, PyTorch." - - AVOID: - - Do NOT use a large model — MiniLM-L6-v2 is sufficient and fast - - Do NOT run the model on GPU — CPU is fine for small skill lists - - Do NOT cache embeddings persistently — in-memory per request is fine for MVP - - - python3 -c " -from backend.services.skill_matcher import SkillMatcher -matcher = SkillMatcher() -result = matcher.match( - candidate_skills=['python', 'react', 'docker', 'aws', 'postgresql'], - job_description='Looking for a Full Stack Developer with Python, React, Node.js, PostgreSQL, and Kubernetes experience', -) -print(f'Match score: {result[\"match_score\"]}') -print(f'Matched: {result[\"matched_skills\"]}') -print(f'Missing: {result[\"missing_skills\"]}') -print(f'Explanation: {result[\"explanation\"]}') -" - - - - SkillMatcher class exists and imports without error - - match() returns score, matched/missing/bonus skills, and explanation - - Semantic matching works (React ≈ frontend, PostgreSQL ≈ databases) - - Score is 0-100 and reflects actual skill overlap - - - -## Success Criteria -- [ ] Sentence-transformers model loads and encodes skills -- [ ] Semantic similarity detects related but not identical skills -- [ ] Match score reflects real skill overlap (not just keyword matching) -- [ ] Human-readable explanation generated for every match diff --git a/.gsd/phases/3/1-SUMMARY.md b/.gsd/phases/3/1-SUMMARY.md deleted file mode 100644 index e3df45b1c47b3dad5d76945fba33aa6aab43e7d0..0000000000000000000000000000000000000000 --- a/.gsd/phases/3/1-SUMMARY.md +++ /dev/null @@ -1,14 +0,0 @@ -# Plan 3.1 Summary: Skill Similarity Matcher - -## Status: ✅ Complete - -## What was done -- `backend/services/skill_matcher.py`: Sentence-transformers semantic matching (all-MiniLM-L6-v2, lazy-loaded singleton) -- Cosine similarity matrix between candidate skills and JD requirements -- Category-based scoring, match/missing/bonus skill classification -- Human-readable explanations for every match result - -## Verification -- Imports without error ✓ -- Test: 5 candidate skills vs JD with 5 requirements → match_score=60, 3 matched, 2 missing ✓ -- Semantic matching works (React ≈ frontend, PostgreSQL ≈ databases) ✓ diff --git a/.gsd/phases/3/2-PLAN.md b/.gsd/phases/3/2-PLAN.md deleted file mode 100644 index eff396cc36bae597d8b02b4156a62e9bc9504a69..0000000000000000000000000000000000000000 --- a/.gsd/phases/3/2-PLAN.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -phase: 3 -plan: 2 -wave: 1 ---- - -# Plan 3.2: Learning Ability Predictor & Inflation Detector - -## Objective -Build two complementary scoring services: (1) Learning Ability Predictor — estimates how quickly a candidate can acquire missing skills based on their existing skill graph and activity patterns, and (2) Resume Inflation Detector — cross-references self-reported resume claims against verified GitHub/LeetCode data to flag exaggerations. - -## Context -- .gsd/SPEC.md — REQ-06, REQ-07: Learning ability prediction; REQ-08, REQ-09: Inflation detection -- backend/services/skill_dictionary.py — SKILL_CATEGORIES for skill relationships -- backend/services/github_analyzer.py — GitHub data structure (scores, languages, repos) -- backend/services/leetcode_analyzer.py — LeetCode data structure (problems, scores) - -## Tasks - - - Create learning ability predictor - - backend/services/learning_predictor.py - - - Create a `LearningPredictor` class: - - **predict(self, candidate_skills: list[str], missing_skills: list[str], github_data: dict = None, leetcode_data: dict = None) -> dict:** - Returns: - ```python - { - "learning_score": float, # 0-100 overall - "predictions": [ # per missing skill - { - "skill": str, - "estimated_months": float, # estimated time to learn - "confidence": str, # "high"/"medium"/"low" - "reason": str, # why this estimate - "related_existing": [str], # existing skills in same category - } - ], - "factors": { - "skill_breadth_bonus": float, # 0-20 bonus for diverse skills - "consistency_bonus": float, # 0-15 bonus for consistent GH activity - "problem_solving_bonus": float, # 0-15 bonus for LC score - "base_score": float, # 50 baseline - }, - "explanation": str, - } - ``` - - **_estimate_learning_time(self, skill: str, existing_skills: list[str]) -> dict:** - Logic: - 1. Find the category of the target skill using `get_skill_category()` - 2. Count how many skills the candidate already has in that category - 3. More existing skills in the same category → faster learning - - 0 related skills → 6+ months (low confidence) - - 1-2 related → 3-4 months (medium) - - 3+ related → 1-2 months (high) - 4. Cross-category transfer: a person with Python + React who needs Vue = fast - - **_calculate_learning_score(self, predictions: list, factors: dict) -> float:** - - Base score = 50 - - Add skill_breadth_bonus: breadth_factor = min(20, len(unique_categories) * 4) - - Add consistency_bonus: if github consistency score > 70 → +15 - - Add problem_solving_bonus: if leetcode_score > 70 → +15 - - Subtract penalty for each skill with > 4 months estimate - - Clamp to 0-100 - - AVOID: - - Do NOT attempt to use any ML model here — heuristic scoring is appropriate for this signal - - Do NOT try to predict exact timelines — give ranges and confidence levels - - - python3 -c " -from backend.services.learning_predictor import LearningPredictor -predictor = LearningPredictor() -result = predictor.predict( - candidate_skills=['python', 'flask', 'postgresql', 'git'], - missing_skills=['docker', 'kubernetes', 'react'], - github_data={'scores': {'consistency': 75, 'tech_breadth': 60}}, - leetcode_data={'scores': {'overall': 80}}, -) -print(f'Learning score: {result[\"learning_score\"]}') -for p in result['predictions']: - print(f' {p[\"skill\"]}: ~{p[\"estimated_months\"]}mo ({p[\"confidence\"]})') -" - - - - LearningPredictor class exists and imports without error - - predict() returns learning score + per-skill estimates with confidence - - Related skills reduce estimated learning time - - GitHub consistency and LeetCode scores provide bonuses - - - - - Create inflation detector - - backend/services/inflation_detector.py - - - Create an `InflationDetector` class: - - **detect(self, resume_skills: list[str], github_data: dict = None, leetcode_data: dict = None) -> dict:** - Returns: - ```python - { - "credibility_score": float, # 0-100 (higher = more credible) - "flags": [ # individual credibility flags - { - "skill": str, - "status": str, # "verified" / "unverified" / "inflated" - "evidence": str, # why this status - "source": str, # "github" / "leetcode" / "none" - } - ], - "summary": { - "verified_count": int, - "unverified_count": int, - "inflated_count": int, - "total_claimed": int, - }, - "explanation": str, - } - ``` - - **_check_github_skills(self, claimed_skills: list[str], github_data: dict) -> list[dict]:** - For each claimed skill: - 1. Check if a matching language appears in GitHub languages dict - 2. Check repo names/descriptions for framework mentions (optional — can do basic name matching) - 3. If found → "verified" with evidence "Found {bytes} bytes of {language} code across {N} repos" - 4. If language category matches but specific skill not found → "unverified" - 5. If completely absent → check if related to any detected language - - **_check_leetcode_skills(self, claimed_skills: list[str], leetcode_data: dict) -> list[dict]:** - If claimed "data structures", "algorithms", etc.: - - Check if total_solved > threshold (>50 → verified) - - Check difficulty balance for algorithm claims - - For language-agnostic claims like "problem solving" → use LC score. - - **_calculate_credibility_score(self, flags: list) -> float:** - - Start at 100 - - Each "verified" skill: +0 (no change, already at max) - - Each "unverified" skill: -3 (slight doubt) - - Each "inflated" skill: -10 (significant penalty) - - Floor at 0, cap at 100 - - **Inflation rules:** - - Claims "expert in X" but no GitHub evidence → inflated flag - - Claims more than 5 languages with GitHub only showing 1-2 → warning - - Claims "Machine Learning" but no Python/ML repos → unverified - - AVOID: - - Do NOT be overly aggressive — resume skills may be from work experience not on GitHub - - Do NOT call anything "inflated" without strong evidence — default to "unverified" - - Keep the detector fair: some skills are hard to verify via GitHub (e.g., "teamwork", "communication") - - - python3 -c " -from backend.services.inflation_detector import InflationDetector -detector = InflationDetector() -result = detector.detect( - resume_skills=['python', 'react', 'machine learning', 'kubernetes', 'blockchain'], - github_data={ - 'details': { - 'languages': {'Python': 50000, 'JavaScript': 30000}, - 'total_repos': 15, - }, - 'scores': {'tech_breadth': 40}, - }, - leetcode_data={ - 'problems': {'total_solved': 100, 'easy': 40, 'medium': 45, 'hard': 15}, - }, -) -print(f'Credibility: {result[\"credibility_score\"]}') -for f in result['flags']: - print(f' {f[\"skill\"]}: {f[\"status\"]} — {f[\"evidence\"]}') -" - - - - InflationDetector class exists and imports without error - - detect() cross-references resume claims against GitHub/LeetCode evidence - - Each skill gets verified/unverified/inflated status with evidence - - Credibility score reflects overall claim reliability - - Not overly aggressive — defaults to "unverified" when uncertain - - - -## Success Criteria -- [ ] Learning predictor estimates time-to-learn per missing skill -- [ ] Inflation detector flags unverified/inflated resume claims -- [ ] Both provide human-readable explanations -- [ ] GitHub languages and LeetCode stats used as evidence sources diff --git a/.gsd/phases/3/2-SUMMARY.md b/.gsd/phases/3/2-SUMMARY.md deleted file mode 100644 index 7da6b3ec20ee4d7010034f81b7280cc20447c9cd..0000000000000000000000000000000000000000 --- a/.gsd/phases/3/2-SUMMARY.md +++ /dev/null @@ -1,11 +0,0 @@ -# Plan 3.2 Summary: Learning Predictor + Inflation Detector - -## Status: ✅ Complete - -## What was done -- `backend/services/learning_predictor.py`: Skill graph analysis (category overlap → faster learning), GitHub consistency + LeetCode bonuses, per-skill time estimates with confidence levels -- `backend/services/inflation_detector.py`: Cross-references resume claims against GitHub languages + LeetCode stats. Language ecosystems map for framework validation. Conservative: defaults to "unverified" not "inflated" - -## Verification -- LearningPredictor: score=90 for well-matched candidate, per-skill estimates working ✓ -- InflationDetector: credibility=100 when GitHub confirms 4/4 claimed skills ✓ diff --git a/.gsd/phases/3/3-PLAN.md b/.gsd/phases/3/3-PLAN.md deleted file mode 100644 index 9ffc46a4d262abe5056baf2431cc8b35e2e26346..0000000000000000000000000000000000000000 --- a/.gsd/phases/3/3-PLAN.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -phase: 3 -plan: 3 -wave: 2 ---- - -# Plan 3.3: Scoring Engine Integration + API Response Update - -## Objective -Wire all ML scoring services (skill matcher, learning predictor, inflation detector) into the candidate analysis pipeline and update the API response to include full scoring with an overall composite score. Also update the frontend JavaScript to display the results when available. - -## Context -- backend/api/routes/candidates.py — Current pipeline (Phase 2) -- backend/services/skill_matcher.py — Built in Plan 3.1 -- backend/services/learning_predictor.py — Built in Plan 3.2 -- backend/services/inflation_detector.py — Built in Plan 3.2 - -## Tasks - - - Create scoring engine orchestrator and update API - - backend/services/scoring_engine.py - backend/api/routes/candidates.py - backend/services/__init__.py - - - **backend/services/scoring_engine.py:** - Create a `ScoringEngine` class that orchestrates all scoring: - - **score(self, parsed_resume: dict, job_description: str, github_data: dict = None, leetcode_data: dict = None) -> dict:** - 1. Run SkillMatcher.match() → match_score + details - 2. Get missing_skills from match result - 3. Run LearningPredictor.predict() → learning_score + predictions - 4. Run InflationDetector.detect() → credibility_score + flags - 5. Compute overall_score as weighted average: - - match_score: 40% - - github_overall: 20% - - leetcode_overall: 15% - - learning_score: 10% - - credibility_score: 15% - 6. Generate final recommendation: "Strong Hire" / "Hire" / "Maybe" / "Pass" - - Returns: - ```python - { - "overall_score": float, # 0-100 - "recommendation": str, # "Strong Hire" etc. - "scores": { - "match_score": float, - "github_score": float, - "leetcode_score": float, - "learning_score": float, - "credibility_score": float, - }, - "skill_match": {...}, # full SkillMatcher result - "learning_analysis": {...}, # full LearningPredictor result - "credibility_analysis": {...}, # full InflationDetector result - "explanation": str, # overall narrative - } - ``` - - **Recommendation thresholds:** - - overall >= 80 → "Strong Hire" - - overall >= 60 → "Hire" - - overall >= 40 → "Maybe" - - overall < 40 → "Pass" - - **Update backend/api/routes/candidates.py:** - After running GitHub/LeetCode analyzers, call `ScoringEngine().score()` and include all ML scoring in the response. Update the CandidateAnalysis DB record with computed scores (match_score, learning_ability_score, credibility_score, overall_score). - - **Update backend/services/__init__.py:** - Export new services: SkillMatcher, LearningPredictor, InflationDetector, ScoringEngine. - - AVOID: - - Do NOT change the existing pipeline flow — just add scoring after data fetching - - Do NOT break backward compatibility — existing fields must still be present - - - # Upload test resume and verify full scored response - curl -s -X POST http://localhost:8000/api/candidates/analyze \ - -F "resume=@/tmp/test_resume.pdf" \ - -F "job_description=Full Stack Python Developer with React, Docker, and AWS" \ - -F "github_username=torvalds" \ - -F "leetcode_username=neal_wu" \ - | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d.get('scoring',{}), indent=2))" - - - - ScoringEngine orchestrates all ML scoring - - API response includes match_score, learning_score, credibility_score, and overall_score - - Recommendation label generated (Strong Hire/Hire/Maybe/Pass) - - Database record updated with all computed scores - - Full pipeline works end-to-end: upload → parse → fetch → score → respond - - - - - Update frontend to display analysis results - - frontend/js/app.js - frontend/css/style.css - - - **Update frontend/js/app.js:** - In the `handleCandidateAnalysis()` function, after receiving the API response: - - 1. Hide the empty state and show results container - 2. Render score cards: - - Overall score (large, centered, color-coded by recommendation) - - Recommendation badge ("Strong Hire" / "Hire" / "Maybe" / "Pass") - - Individual score cards: Match, GitHub, LeetCode, Learning, Credibility - 3. Render skill tags: matched (green), missing (amber), flagged (red) - 4. Render explanations as collapsible sections - - Create a `renderCandidateResults(data)` function that builds the HTML: - ```javascript - function renderCandidateResults(data) { - const container = document.getElementById('candidate-results'); - // Build score overview - // Build skill tags - // Build explanations - container.innerHTML = html; - container.style.display = 'block'; - document.getElementById('candidate-empty-state').style.display = 'none'; - } - ``` - - Score card color rules: - - Score >= 80 → green (--color-success) - - Score >= 60 → accent blue (--accent-primary) - - Score >= 40 → amber (--color-warning) - - Score < 40 → red (--color-error) - - **Update frontend/css/style.css:** - Add styles for: - - `.score-card` — glass card with score number + label - - `.recommendation-badge` — large badge with recommendation text - - `.skill-tags-container` — flex wrap for skill tags - - `.explanation-section` — collapsible with smooth transition - - AVOID: - - Do NOT add a framework — keep vanilla JS - - Do NOT add charting libraries — simple HTML/CSS score displays are fine for MVP - - - # Visual verification in browser - launch server and check results render after analysis - # Start server: uvicorn backend.main:app --port 8000 - # 1. Open http://localhost:8000 - # 2. Upload test_resume.pdf - # 3. Enter a job description - # 4. Click Analyze Candidate - # 5. Verify results panel shows scores, recommendation, skill tags - - - - Results panel renders after successful analysis - - Overall score + recommendation badge visible - - Individual score cards for each dimension - - Skill tags color-coded (matched/missing/flagged) - - Explanations shown for each score - - Empty state hidden when results are displayed - - - -## Success Criteria -- [ ] Full pipeline: upload → parse → fetch → score → display results -- [ ] Overall score and recommendation computed and shown -- [ ] All 5 score dimensions displayed with color coding -- [ ] Skill tags and explanations rendered in the frontend -- [ ] Database record stores all computed scores diff --git a/.gsd/phases/3/3-SUMMARY.md b/.gsd/phases/3/3-SUMMARY.md deleted file mode 100644 index ffc0daab0024c2486c05c43aca7df8e05a83499a..0000000000000000000000000000000000000000 --- a/.gsd/phases/3/3-SUMMARY.md +++ /dev/null @@ -1,14 +0,0 @@ -# Plan 3.3 Summary: Scoring Engine + API + Frontend Results - -## Status: ✅ Complete - -## What was done -- `backend/services/scoring_engine.py`: Orchestrates all ML scoring (40% match + 20% GitHub + 15% LeetCode + 10% learning + 15% credibility), dynamic weight redistribution, recommendation engine -- Updated `backend/api/routes/candidates.py`: Full pipeline with ML scoring, DB stores all computed scores -- Updated `frontend/js/app.js`: Results renderer with score ring, recommendation badge, score cards, skill tags, learning predictions, credibility flags -- Updated `frontend/css/style.css`: Complete results display styles - -## Verification -- API: overall=77.3, recommendation=Hire for real test data ✓ -- Frontend: all components render correctly in browser ✓ -- DB: all scores persisted ✓ diff --git a/.gsd/phases/4/1-PLAN.md b/.gsd/phases/4/1-PLAN.md deleted file mode 100644 index 9beb8ca933ddfccfde9f25bf413012bebae06bd1..0000000000000000000000000000000000000000 --- a/.gsd/phases/4/1-PLAN.md +++ /dev/null @@ -1,121 +0,0 @@ -w--- -phase: 4 -plan: 1 -wave: 1 ---- - -# Plan 4.1: Team Skill Gap Analyzer - -## Objective -Build the core team analysis service that accepts team skills and project requirements, computes coverage score, identifies skill gaps clustered by domain, and generates a prioritized hire plan with urgency levels. This is the analytical backbone of Phase 4. - -## Context -- .gsd/ROADMAP.md — Phase 4 description -- backend/models/team.py — TeamAnalysis model (coverage_score, skill_gaps, hire_plan columns) -- backend/services/skill_dictionary.py — SKILL_CATEGORIES, get_skill_category for domain clustering -- backend/services/skill_matcher.py — SkillMatcher for semantic matching (reusable pattern) - -## Tasks - - - Create team gap analyzer service - - backend/services/team_analyzer.py - - - Create a `TeamAnalyzer` class: - - **analyze(self, team_skills: list[str], project_requirements: list[str], team_name: str = "") -> dict:** - Main entry point. Returns: - ```python - { - "coverage_score": float, # 0-100 how well team covers requirements - "gap_summary": { - "total_required": int, - "covered": int, - "gaps": int, - }, - "covered_skills": [str], # requirements the team already has - "gap_clusters": [ # gaps grouped by domain - { - "domain": str, # e.g. "devops", "frontend" - "skills": [str], # missing skills in this domain - "urgency": str, # "critical" / "high" / "medium" / "low" - "reason": str, # why this urgency - } - ], - "hire_plan": [ # recommended hires - { - "role": str, # e.g. "DevOps Engineer" - "priority": int, # 1 = most urgent - "skills_covered": [str], # which gaps this hire fills - "justification": str, # why this hire - } - ], - "explanation": str, - } - ``` - - **_compute_coverage(self, team: list[str], required: list[str]) -> tuple[list, list]:** - 1. Use `find_skills_in_text` to normalize both lists - 2. For each requirement, check if the team has it (exact or category match) - 3. Return (covered_list, gap_list) - - **_cluster_gaps(self, gaps: list[str]) -> list[dict]:** - 1. Group gaps by `get_skill_category(skill)` from skill_dictionary - 2. For each cluster, determine urgency: - - 3+ gaps in one domain → "critical" - - 2 gaps → "high" - - 1 gap → "medium" - - Bonus: if domain is "devops" or "security" → bump urgency one level - - **_generate_hire_plan(self, clusters: list[dict]) -> list[dict]:** - 1. Sort clusters by urgency (critical first) - 2. Map each cluster to a suggested role title: - - "devops" gaps → "DevOps Engineer" - - "frontend" gaps → "Frontend Developer" - - "backend" gaps → "Backend Developer" - - "databases" gaps → "Database Engineer" - - "ml_ai" gaps → "ML/AI Engineer" - - "mobile" gaps → "Mobile Developer" - - "tools" gaps → "Platform Engineer" - - "languages" gaps → "Software Engineer" - - "cloud" gaps → "Cloud Engineer" - - Multiple domains → "Full Stack Developer" - 3. Assign priority 1, 2, 3... by urgency order - 4. Generate justification for each hire - - AVOID: - - Do NOT use LLM for this step — pure algorithmic gap analysis - - Do NOT try to merge roles aggressively — keep it clear for the CTO - - - python3 -c " -from backend.services.team_analyzer import TeamAnalyzer -analyzer = TeamAnalyzer() -result = analyzer.analyze( - team_skills=['python', 'react', 'postgresql', 'git'], - project_requirements=['python', 'react', 'docker', 'kubernetes', 'terraform', 'redis', 'graphql', 'ci/cd'], - team_name='Engineering Alpha', -) -print(f'Coverage: {result[\"coverage_score\"]}%') -print(f'Covered: {result[\"covered_skills\"]}') -print(f'Gaps: {result[\"gap_summary\"][\"gaps\"]}') -for c in result['gap_clusters']: - print(f' {c[\"domain\"]}: {c[\"skills\"]} ({c[\"urgency\"]})') -for h in result['hire_plan']: - print(f' #{h[\"priority\"]} {h[\"role\"]}: {h[\"skills_covered\"]}') -" - - - - TeamAnalyzer class imports and runs without error - - Coverage score reflects actual skill overlap - - Gaps clustered by domain with urgency levels - - Hire plan generated with roles and priorities - - - -## Success Criteria -- [ ] Team gap analysis produces coverage score, gap clusters, and hire plan -- [ ] Urgency levels assigned logically (more gaps = higher urgency) -- [ ] Human-readable explanations for every recommendation diff --git a/.gsd/phases/4/1-SUMMARY.md b/.gsd/phases/4/1-SUMMARY.md deleted file mode 100644 index 33ba9cabc2132ac54bf47723694618a8ced98a0e..0000000000000000000000000000000000000000 --- a/.gsd/phases/4/1-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 4.1 Summary: Team Skill Gap Analyzer -## Status: ✅ Complete - Coverage=25%, 6 gaps across 3 clusters, 3 hires recommended diff --git a/.gsd/phases/4/2-PLAN.md b/.gsd/phases/4/2-PLAN.md deleted file mode 100644 index 81a21f64d9405adcbb622141b63ba047792f0101..0000000000000000000000000000000000000000 --- a/.gsd/phases/4/2-PLAN.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -phase: 4 -plan: 2 -wave: 1 ---- - -# Plan 4.2: Salary Benchmarking + JD Generator - -## Objective -Add salary estimation for hire plan roles using a built-in dataset (inspired by Levels.fyi/public data) and build a JD generator that produces ready-to-post job descriptions from the hire plan. Salary estimates turn recommendations into budgetable business cases ("hiring a DevOps engineer will cost ₹18–26 LPA in Bangalore"). - -## Context -- .gsd/ROADMAP.md — Phase 4: salary benchmarking requirement -- backend/services/team_analyzer.py — Built in Plan 4.1 (hire plan structure) -- backend/services/skill_dictionary.py — Skill categories - -## Tasks - - - Create salary benchmarker - - backend/services/salary_benchmarker.py - - - Create a `SalaryBenchmarker` class with a built-in salary dataset. - - **Built-in dataset (dict):** - Store as a Python dict keyed by (role, experience_band, location): - ```python - SALARY_DATA = { - # (role, experience, location) → (min_lpa, max_lpa, currency) - # Indian cities (LPA = Lakhs Per Annum) - ("DevOps Engineer", "junior", "bangalore"): (8, 15, "INR"), - ("DevOps Engineer", "mid", "bangalore"): (15, 26, "INR"), - ("DevOps Engineer", "senior", "bangalore"): (26, 45, "INR"), - ("Frontend Developer", "junior", "bangalore"):(6, 12, "INR"), - ("Frontend Developer", "mid", "bangalore"): (12, 22, "INR"), - ("Frontend Developer", "senior", "bangalore"):(22, 38, "INR"), - ("Backend Developer", "junior", "bangalore"): (8, 14, "INR"), - ("Backend Developer", "mid", "bangalore"): (14, 25, "INR"), - ("Backend Developer", "senior", "bangalore"): (25, 42, "INR"), - ("Full Stack Developer", "junior", "bangalore"):(8, 15, "INR"), - ("Full Stack Developer", "mid", "bangalore"): (15, 28, "INR"), - ("Full Stack Developer", "senior", "bangalore"):(28, 45, "INR"), - ("ML/AI Engineer", "junior", "bangalore"): (10, 18, "INR"), - ("ML/AI Engineer", "mid", "bangalore"): (18, 35, "INR"), - ("ML/AI Engineer", "senior", "bangalore"): (35, 60, "INR"), - ("Cloud Engineer", "mid", "bangalore"): (15, 28, "INR"), - ("Database Engineer", "mid", "bangalore"): (12, 22, "INR"), - ("Mobile Developer", "mid", "bangalore"): (12, 24, "INR"), - ("Platform Engineer", "mid", "bangalore"): (14, 26, "INR"), - ("Software Engineer", "mid", "bangalore"): (12, 22, "INR"), - # ... repeat for "remote_india", "delhi", "hyderabad", "mumbai" - # US cities (K USD) - ("DevOps Engineer", "mid", "us_remote"): (120, 180, "USD"), - ("Frontend Developer", "mid", "us_remote"): (100, 160, "USD"), - ("Backend Developer", "mid", "us_remote"): (110, 170, "USD"), - ("Full Stack Developer", "mid", "us_remote"): (120, 180, "USD"), - ("ML/AI Engineer", "mid", "us_remote"): (140, 220, "USD"), - } - ``` - - Add entries for multiple cities and experience bands. At least 100 entries covering India's major cities + US remote. - - **estimate(self, role: str, location: str = "bangalore", experience: str = "mid") -> dict:** - Returns: - ```python - { - "role": str, - "location": str, - "experience": str, - "salary_range": {"min": float, "max": float}, - "currency": str, - "formatted": str, # "₹15–26 LPA" or "$120–180K" - } - ``` - - **enrich_hire_plan(self, hire_plan: list[dict], location: str = "bangalore", experience: str = "mid") -> list[dict]:** - For each role in the hire plan, add salary estimate. - Also compute total_budget_impact: sum of max salaries across all hires. - - AVOID: - - Do NOT call external APIs — use built-in dataset (the user wants local-first) - - Do NOT over-engineer — a dict-based lookup with fuzzy matching is sufficient - - - python3 -c " -from backend.services.salary_benchmarker import SalaryBenchmarker -bench = SalaryBenchmarker() -est = bench.estimate('DevOps Engineer', location='bangalore', experience='mid') -print(f'{est[\"role\"]}: {est[\"formatted\"]}') -est2 = bench.estimate('ML/AI Engineer', location='us_remote', experience='mid') -print(f'{est2[\"role\"]}: {est2[\"formatted\"]}') -" - - - - SalaryBenchmarker class imports and returns salary ranges - - Covers at least 5 Indian cities + US remote - - formatted field shows human-readable salary (₹X–Y LPA or $X–YK) - - enrich_hire_plan adds salary data to each hire recommendation - - - - - Create JD generator - - backend/services/jd_generator.py - - - Create a `JDGenerator` class that generates ready-to-post job descriptions from hire plan entries. - - **generate(self, role: str, skills: list[str], team_name: str = "", salary_range: dict = None) -> dict:** - Returns: - ```python - { - "title": str, # role title - "description": str, # full JD text (markdown formatted) - "sections": { - "about": str, - "responsibilities": [str], - "requirements": [str], - "nice_to_have": [str], - "compensation": str, - } - } - ``` - - Use a template-based approach: - 1. Map role name to a title + about section template - 2. Generate responsibilities from skill list (e.g., "Design and maintain CI/CD pipelines" for docker/kubernetes skills) - 3. Generate requirements from skill list + standard role expectations - 4. Add nice-to-have from related skills in the same category - 5. Add compensation section if salary_range provided - - Have a `RESPONSIBILITY_TEMPLATES` dict mapping skills to responsibility bullet points. - Have a `REQUIREMENT_TEMPLATES` dict mapping skills to requirement bullet points. - - **generate_all(self, hire_plan: list[dict], team_name: str = "") -> list[dict]:** - Generate JDs for all roles in the hire plan. - - AVOID: - - Do NOT use LLM for this — template-based is fine for V1 - - Do NOT generate generic JDs — make them specific to the skills needed - - - python3 -c " -from backend.services.jd_generator import JDGenerator -gen = JDGenerator() -jd = gen.generate( - role='DevOps Engineer', - skills=['docker', 'kubernetes', 'terraform', 'ci/cd'], - team_name='Engineering Alpha', - salary_range={'min': 15, 'max': 26, 'currency': 'INR'}, -) -print(f'Title: {jd[\"title\"]}') -print(jd['description'][:500]) -" - - - - JDGenerator class creates role-specific job descriptions - - Responsibilities and requirements match the gap skills - - Compensation section included when salary data available - - Descriptions are formatted in markdown (ready to post) - - - -## Success Criteria -- [ ] Salary estimates available for all hire plan roles -- [ ] Budget impact computed for the full hire plan -- [ ] JDs generated with skill-specific responsibilities/requirements -- [ ] Human-readable formatting for salary and JDs diff --git a/.gsd/phases/4/2-SUMMARY.md b/.gsd/phases/4/2-SUMMARY.md deleted file mode 100644 index d0f18ef4651c781182ffb4ee82c05e210ca44f88..0000000000000000000000000000000000000000 --- a/.gsd/phases/4/2-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 4.2 Summary: Salary Benchmarker + JD Generator -## Status: ✅ Complete - 100+ entries, 7 locations, template-based JDs with 50+ skill mappings diff --git a/.gsd/phases/4/3-PLAN.md b/.gsd/phases/4/3-PLAN.md deleted file mode 100644 index 53575babf235ac0bdaa60c64f4928e2088369b99..0000000000000000000000000000000000000000 --- a/.gsd/phases/4/3-PLAN.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -phase: 4 -plan: 3 -wave: 2 ---- - -# Plan 4.3: API Wiring + Frontend Team Results - -## Objective -Wire the team analyzer, salary benchmarker, and JD generator into the team analysis API endpoint. Update the frontend to display team analysis results — coverage score, gap clusters, hire plan with salary estimates, and generated JDs. - -## Context -- backend/api/routes/teams.py — Current placeholder endpoint -- backend/services/team_analyzer.py — Built in Plan 4.1 -- backend/services/salary_benchmarker.py — Built in Plan 4.2 -- backend/services/jd_generator.py — Built in Plan 4.2 -- frontend/js/app.js — handleTeamAnalysis is a placeholder -- frontend/css/style.css — Needs team-specific result styles - -## Tasks - - - Wire team services into API endpoint - - backend/api/routes/teams.py - backend/services/__init__.py - - - **Update POST /api/teams/analyze:** - Accept JSON body: - ```python - { - "team_name": str, - "team_skills": [str], # comma-separated → list - "project_requirements": [str], # comma-separated → list - "location": str = "bangalore", # optional, for salary lookup - "experience": str = "mid", # optional - } - ``` - - Pipeline: - 1. Run TeamAnalyzer.analyze(team_skills, project_requirements, team_name) - 2. Run SalaryBenchmarker.enrich_hire_plan(hire_plan, location, experience) - 3. Run JDGenerator.generate_all(enriched_hire_plan, team_name) - 4. Assemble full result with coverage, gaps, hire plan, salaries, JDs - 5. Save to TeamAnalysis DB record (coverage_score, skill_gaps, hire_plan, analysis_result) - 6. Return JSON response - - **Update services/__init__.py:** - Export TeamAnalyzer, SalaryBenchmarker, JDGenerator. - - AVOID: - - Do NOT change the existing history/detail endpoints — they already work - - - curl -s -X POST http://localhost:8000/api/teams/analyze \ - -H "Content-Type: application/json" \ - -d '{"team_name": "Engineering Alpha", "team_skills": ["python", "react", "postgresql"], "project_requirements": ["python", "react", "docker", "kubernetes", "terraform", "redis"]}' \ - | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Coverage: {d[\"coverage_score\"]}'); print(f'Hire plan: {len(d[\"hire_plan\"])} roles')" - - - - Team analysis endpoint accepts skills + requirements - - Returns coverage score, gap clusters, hire plan, salary estimates, JDs - - Database record saved with all results - - - - - Update frontend for team results - - frontend/js/app.js - frontend/css/style.css - - - **Update handleTeamAnalysis() in app.js:** - After receiving API response, call `renderTeamResults(data)`. - - **Create renderTeamResults(data) function:** - 1. Coverage score hero (reuse score-ring pattern from candidate results) - 2. Gap clusters section — cards grouped by domain, color-coded by urgency - 3. Hire plan table — role, priority, skills covered, salary range - 4. Budget impact summary — total estimated cost for all hires - 5. JDs section — collapsible cards with full JD text for each role - - **Add CSS styles:** - - `.gap-cluster-card` — urgency-colored border (critical=red, high=amber, medium=blue, low=gray) - - `.hire-plan-table` — dark table with subtle borders - - `.budget-summary` — prominent total budget display - - `.jd-card` — expandable card for job descriptions - - `.jd-toggle` — click-to-expand button - - AVOID: - - Do NOT add frameworks — keep vanilla JS - - Do NOT duplicate the candidate results pattern excessively — team results have a different data shape - - - # Start server and verify in browser: - # 1. Open http://localhost:8000 - # 2. Switch to "Team Analysis" tab - # 3. Enter team name, skills, and requirements - # 4. Click "Analyze Team Gaps" - # 5. Verify results show coverage, gaps, hire plan, salary, JDs - - - - Team results panel renders after analysis - - Coverage score displayed with ring visualization - - Gap clusters shown with urgency color coding - - Hire plan displayed with salary estimates - - JDs expandable for each role - - Budget impact summary visible - - - -## Success Criteria -- [ ] Full pipeline: team skills → gaps → hire plan → salary → JDs → display -- [ ] API returns complete team analysis with all sections -- [ ] Frontend renders all team-specific result components -- [ ] Database stores team analysis for history recall diff --git a/.gsd/phases/4/3-SUMMARY.md b/.gsd/phases/4/3-SUMMARY.md deleted file mode 100644 index fcf651398a18ae6f27a6dac38749b2a322732841..0000000000000000000000000000000000000000 --- a/.gsd/phases/4/3-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 4.3 Summary: API Wiring + Frontend Team Results -## Status: ✅ Complete - Full pipeline, coverage ring, gap clusters, hire plan, salary, expandable JDs diff --git a/.gsd/phases/6/1-PLAN.md b/.gsd/phases/6/1-PLAN.md deleted file mode 100644 index 9ffecd21cde870fdcaceb9026899f32660bafa17..0000000000000000000000000000000000000000 --- a/.gsd/phases/6/1-PLAN.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -phase: 6 -plan: 1 -wave: 1 ---- - -# Plan 6.1: Next.js + Tailwind + Shadcn Initialization - -## Objective -Initialize the new Next.js frontend to replace the legacy Vanilla JS implementation. This sets up the React, TypeScript, Tailwind CSS, and Shadcn UI foundations for building the advanced landing page required by the prompts. - -## Context -- .gsd/ROADMAP.md (Phase 6) -- User Prompt containing custom Tailwind `@theme inline` variables. - -## Tasks - - - Rename Legacy Frontend - frontend - - - Rename the existing `frontend` directory to `frontend_legacy` to preserve the original vanilla Implementation without losing data. - - test -d "frontend_legacy" - Folder is renamed to `frontend_legacy`. - - - - Initialize Next.js & Dependencies - frontend/package.json - - - Run `npx create-next-app@latest frontend --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"` to create a modern Next.js 14-15 project. - - Change directory to `frontend` and install core animation and icon libraries. - - Run `npm install framer-motion lucide-react @phosphor-icons/react @radix-ui/react-slot class-variance-authority` - - test -f "frontend/package.json" - Next.js app initialized with all NPM dependencies successfully installed. - - - - Configure Shadcn UI & Tailwind Theme - frontend/src/app/globals.css, frontend/components.json - - - Initialize Shadcn via `npx shadcn@latest init -d`. - - Ensure component paths are set to `/src/components/ui`. This is critical because all shadcn defaults target this structure, allowing automatic component installations and maintaining modular UI organization without clutter. - - Create `src/components/ui` if absent. - - Update `frontend/src/app/globals.css` exactly with the color theme variables provided in the user prompt (specifically the `:root`, `.dark` and `@theme inline` blocks). - - test -d "frontend/src/components/ui" - Shadcn structural layout configured and global tailored theme variables applied. - - -## Success Criteria -- [ ] Next.js app running out of `frontend/` directory. -- [ ] `framer-motion`, `lucide-react`, and `@phosphor-icons/react` are listed as dependencies. -- [ ] Theme configuration precisely follows the provided input format in globals.css. diff --git a/.gsd/phases/6/1-SUMMARY.md b/.gsd/phases/6/1-SUMMARY.md deleted file mode 100644 index 2df5cf80eb170287eef3faa05e529391ec6e0972..0000000000000000000000000000000000000000 --- a/.gsd/phases/6/1-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 6.1 Summary: Next.js + Tailwind + Shadcn Initialization -## Status: ✅ Complete - Migrated vanilla to Next.js 14-15 with Tailwind 4. Inherited custom Shadcn inline theme variables. diff --git a/.gsd/phases/6/2-PLAN.md b/.gsd/phases/6/2-PLAN.md deleted file mode 100644 index 72fdb83f775492b5b7a7920238d88d5664520b89..0000000000000000000000000000000000000000 --- a/.gsd/phases/6/2-PLAN.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -phase: 6 -plan: 2 -wave: 1 ---- - -# Plan 6.2: Core Animated Components Setup - -## Objective -Establish the foundational design system components (`Button`, `TextEffect`, `AnimatedGroup`) which will serve as building blocks for the Hero and Background graphics. - -## Context -- User Prompt containing component code (`button`, `text-effect`, `animated-group`). -- `frontend/src/components/ui/` destination folder. - -## Tasks - - - Implement Shadcn Custom Button - frontend/src/components/ui/button.tsx - - - Create the `button.tsx` file inside `src/components/ui/`. - - Copy exactly the Shadcn button code snippet provided by user. - - test -f "frontend/src/components/ui/button.tsx" - Button component correctly exposes variants and standard sizes. - - - - Implement ibelick/text-effect - frontend/src/components/ui/text-effect.tsx - - - Create `text-effect.tsx` in `src/components/ui/`. - - Paste the code provided by the user. Ensure `'use client'` is active at the top. - - test -f "frontend/src/components/ui/text-effect.tsx" - TextEffect module handles text staggering and framer motion variations. - - - - Implement ibelick/animated-group - frontend/src/components/ui/animated-group.tsx - - - Create `animated-group.tsx` in `src/components/ui/`. - - Paste the code provided by the user to handle grouped staggered animations. - - test -f "frontend/src/components/ui/animated-group.tsx" - AnimatedGroup component manages staggered container reveals. - - -## Success Criteria -- [ ] Base foundational components (`Button`, `TextEffect`, `AnimatedGroup`) exist inside `.tsx` files inside `components/ui`. -- [ ] No compilation or missing dependency errors on React imports. diff --git a/.gsd/phases/6/2-SUMMARY.md b/.gsd/phases/6/2-SUMMARY.md deleted file mode 100644 index 14db053487fd168227b266fecc906449fd90fe07..0000000000000000000000000000000000000000 --- a/.gsd/phases/6/2-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 6.2 Summary: Core Animated Components Setup -## Status: ✅ Complete - Built foundational Shadcn Button, TextEffect, and AnimatedGroup. diff --git a/.gsd/phases/6/3-PLAN.md b/.gsd/phases/6/3-PLAN.md deleted file mode 100644 index 8d9c5b5c874479cbf93814262996194a435253a7..0000000000000000000000000000000000000000 --- a/.gsd/phases/6/3-PLAN.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -phase: 6 -plan: 3 -wave: 2 ---- - -# Plan 6.3: Master Landing Page Assembly - -## Objective -Combine the UI building blocks into a functional, highly-polished landing page (`BackgroundPaths`, `HeroSection`) matching exactly the requested aesthetic layout. - -## Context -- User Prompt containing `background-paths.tsx` and `hero-section-1.tsx` implementations. -- Phosphor and Lucide React specifications. - -## Tasks - - - Implement BackgroundPaths Graphics - frontend/src/components/ui/background-paths.tsx - - - Create `background-paths.tsx` inside `/src/components/ui/`. - - Paste the user's explicit code for FloatingPaths and BackgroundPaths. - - test -f "frontend/src/components/ui/background-paths.tsx" - Animated SVG paths configured to run as a Framer Motion loop. - - - - Implement HeroSection - frontend/src/components/blocks/hero-section-1.tsx - - - Create `/src/components/blocks/hero-section-1.tsx`. - - Paste the `HeroSection` and `HeroHeader` code from the user prompt. - - **Note:** The user requested "Use lucide-react icons for svgs or logos if component requires them." Ensure imports point to the correct `lucide-react` icons (e.g. `ArrowRight`, `ChevronRight`). - - test -f "frontend/src/components/blocks/hero-section-1.tsx" - HeroSection successfully orchestrates structural header, hero title, and customer banner. - - - - Assemble the Master Landing Page - frontend/src/app/page.tsx - - - Replace `app/page.tsx` base template with the newly built components. - - Stack `` and ``. (The prompt implies using both: `HeroSection` offers the header layout while `BackgroundPaths` is a background component. Actually, the BackgroundPaths is its own standalone demo element in the prompt, rendering "Background Paths" text. We will implement both distinctly to show they are working, or blend them dynamically to present the best aesthetic.) - - Remove ANY emojis throughout the UI string blocks. - - grep -q "HeroSection" "frontend/src/app/page.tsx" - Full visual landing page dynamically rendered over `/` next route. - - -## Success Criteria -- [ ] No emojis present in UI templates. -- [ ] Phosphor or Lucide icons successfully handling SVGs. -- [ ] Complete `page.tsx` integrating both Hero and Background features efficiently. diff --git a/.gsd/phases/6/3-SUMMARY.md b/.gsd/phases/6/3-SUMMARY.md deleted file mode 100644 index 13d422efaa1b0049d10ebd1797de8c1c154f90c0..0000000000000000000000000000000000000000 --- a/.gsd/phases/6/3-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 6.3 Summary: Master Landing Page Assembly -## Status: ✅ Complete - Assembled the landing page leveraging the `BackgroundPaths` graphics overlaid with the animated `HeroSection`. Fixed icon imports and removed emojis. diff --git a/.gsd/phases/6/VERIFICATION.md b/.gsd/phases/6/VERIFICATION.md deleted file mode 100644 index 0cbd75f623e0f0e86ad85413d777e2fcd33510f2..0000000000000000000000000000000000000000 --- a/.gsd/phases/6/VERIFICATION.md +++ /dev/null @@ -1,8 +0,0 @@ -## Phase 6 Verification - -### Must-Haves -- [x] Must-have 1 — Migrated to React/Next.js and Tailwind - VERIFIED (evidence: scaffolded next.js with global css theming using @theme inline). -- [x] Must-have 2 — Integrated Core Animated Components - VERIFIED (evidence: Button, textual effects and background svg paths imported into component tree successfully). -- [x] Must-have 3 — Assemble Landing Page correctly - VERIFIED (evidence: background paths successfully stacked under the HeroSection inside `page.tsx`). - -### Verdict: PASS diff --git a/.gsd/phases/7/1-PLAN.md b/.gsd/phases/7/1-PLAN.md deleted file mode 100644 index 4e91cf72a8ac5e8bc00b048fa11d1b6b252294fb..0000000000000000000000000000000000000000 --- a/.gsd/phases/7/1-PLAN.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -phase: 7 -plan: 1 -wave: 1 ---- - -# Plan 7.1: Dash Architecture & APIs - -## Objective -Establish the Next.js `dashboard` route structure, set up the Next.js API proxy to communicate with the FastAPI backend unhindered by CORS/ports, and install the additional Shadcn UI elements required. - -## Context -- `frontend/next.config.ts` -- FastAPI backend runs on `127.0.0.1:8000/api` -- Next.js dev server runs on `3000`. - -## Tasks - - - Configure API Proxy & Utilities - frontend/next.config.ts, frontend/src/lib/api.ts - - - Add an async `rewrites()` rule in `next.config.ts` mapping `/api/:path*` to `http://127.0.0.1:8000/api/:path*`. - - Create `frontend/src/lib/api.ts` with typed Fetch wrappers for `uploadCandidate` and `analyzeTeam` pointing to the `/api/*` routes. - - grep -q "rewrites" "frontend/next.config.ts" - Next config correctly forwards `/api/` traffic to local port 8000. - - - - Install Dashboard Prerequisites - frontend/package.json - - - Use `npx shadcn@latest add card input label tabs textarea progress badge alert scroll-area separator` to install forms and presentation layers. - - test -f "frontend/src/components/ui/card.tsx" - Fundamental UI layout primitives installed natively into `components/ui`. - - - - Create Dashboard Root Layout - frontend/src/app/dashboard/layout.tsx, frontend/src/app/dashboard/page.tsx - - - Scaffold `layout.tsx` with a minimal App header (Link back to `/`). - - Scaffold `page.tsx` utilizing Shadcn generic `` pointing to `Candidate` and `Team` forms. - - test -f "frontend/src/app/dashboard/page.tsx" - User can navigate from `/` to `/dashboard` and see a tabbed structural foundation. - - -## Success Criteria -- [ ] Next.js app seamlessly proxies API calls to FastAPI. -- [ ] Shadcn core view components configured. -- [ ] Dashboard root URL is visually accessible. diff --git a/.gsd/phases/7/1-SUMMARY.md b/.gsd/phases/7/1-SUMMARY.md deleted file mode 100644 index 76391836cf0addcb15833385dfecff4e36a686aa..0000000000000000000000000000000000000000 --- a/.gsd/phases/7/1-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 7.1 Summary: Dash Architecture & APIs -## Status: ✅ Complete - Established the main `/dashboard` page framework. Installed Shadcn UI forms elements (Tabs, Inputs, etc.) and created the unified Next.js API generic proxy route wrapper to speak to FastAPI without CORS issues on localhost. diff --git a/.gsd/phases/7/2-PLAN.md b/.gsd/phases/7/2-PLAN.md deleted file mode 100644 index 657402e536401660b04e81453f170ac9a149d472..0000000000000000000000000000000000000000 --- a/.gsd/phases/7/2-PLAN.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -phase: 7 -plan: 2 -wave: 2 ---- - -# Plan 7.2: Candidate Analysis Pipeline - -## Objective -Rebuild the legacy plain JS candidate resume analysis workflow completely inside a reactive Next.js Client Component, utilizing the sophisticated shadcn form controls. - -## Context -- `frontend/src/app/dashboard/page.tsx` -- FastAPI backend requires `multipart/form-data` containing `resume` (PDF) and `job_requirements` (string). - -## Tasks - - - Build Candidate Form State - frontend/src/components/dashboard/CandidateView.tsx - - - Establish `CandidateView.tsx`. - - Create state using React `useState` for the uploaded `File` and the Job Description textarea string. - - Implement the Fetch call directly hooking into `src/lib/api.ts`. - - test -f "frontend/src/components/dashboard/CandidateView.tsx" - Form securely captures PDF objects and posts to backend proxy. - - - - Build Candidate Result Visualization - frontend/src/components/dashboard/CandidateView.tsx - - - When `data` returns, render the nested JSON. - - Build a circular/progressBar for `match_score`. - - Display Cards for `learning_ability`, speed index, and markdown-rendered rationale. - - List the `skill_gaps` using Shadcn `` coloring (red/yellow). - - grep -q "Card" "frontend/src/components/dashboard/CandidateView.tsx" - Complete parity with the legacy visualizer mapping the `CandidateResult` schema cleanly. - - -## Success Criteria -- [ ] Uploading a resume PDF successfully pushes traffic to FastAPI. -- [ ] The dashboard accurately renders the comprehensive breakdown and prevents rendering crashes dynamically. diff --git a/.gsd/phases/7/2-SUMMARY.md b/.gsd/phases/7/2-SUMMARY.md deleted file mode 100644 index 3dc44817dd1c28832c369413266b0a0973363b09..0000000000000000000000000000000000000000 --- a/.gsd/phases/7/2-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 7.2 Summary: Candidate Analysis Pipeline -## Status: ✅ Complete - Built the React Candidate Dashboard view inside `CandidateView.tsx`. Successfully mapped state arrays to visually match our backend JSON schema utilizing custom tailwind colors and Shadcn `Progress` bars. Connects seamlessly with FastAPI logic. diff --git a/.gsd/phases/7/3-PLAN.md b/.gsd/phases/7/3-PLAN.md deleted file mode 100644 index ed9b5ed988c536441f5250f16f4777c3e82f636e..0000000000000000000000000000000000000000 --- a/.gsd/phases/7/3-PLAN.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -phase: 7 -plan: 3 -wave: 2 ---- - -# Plan 7.3: Team Gap Analysis Pipeline - -## Objective -Rebuild the engineering workforce planning engine. Form input of a team profile yielding a sophisticated multi-component metric view of capability coverage and structural hire requirements. - -## Context -- FastAPI `teams/analyze` endpoint. - -## Tasks - - - Build Team Input Form - frontend/src/components/dashboard/TeamView.tsx - - - Create `TeamView.tsx`. - - Handle state arrays for adding comma-separated current team skills. - - Input standard variables: local currency/market, size, and long-term project requirements string. - - test -f "frontend/src/components/dashboard/TeamView.tsx" - Form cleanly validates schema limits before POSTing to proxy. - - - - Build Gap Results & JD Generator UI - frontend/src/components/dashboard/TeamView.tsx - - - Render `coverage_score` as a master progress ring/bar. - - Loop through `domain_gaps` mapping urgency (HIGH = destructive, MEDIUM = warning) onto Shadcn `` layouts. - - Display generated `hire_plan` roles with expected `salary_benchmarks`. - - Render the `` containing the generated precise Markdown JDs. - - grep -q "coverage" "frontend/src/components/dashboard/TeamView.tsx" - The extensive team evaluation gracefully fits in standard grid layouts natively on React. - - -## Success Criteria -- [ ] Team POST succeeds, generating a robust structural dashboard displaying coverage percentages. -- [ ] Urgency metrics mapped to semantic tailwind tokens (red/yellow/blue). diff --git a/.gsd/phases/7/3-SUMMARY.md b/.gsd/phases/7/3-SUMMARY.md deleted file mode 100644 index f2410c94566c59d0c140ae3caefdcf85cbf895c0..0000000000000000000000000000000000000000 --- a/.gsd/phases/7/3-SUMMARY.md +++ /dev/null @@ -1,2 +0,0 @@ -# Plan 7.3 Summary: Team Gap Analysis Pipeline -## Status: ✅ Complete - Built the robust React Team Coverage evaluation form `TeamView.tsx` with dynamic SVGs mapping the architectural footprint score. Created urgency-colored badges scaling according to 'domain_gaps' priority levels, seamlessly porting the vanilla structure into reusable shadcn UI components. diff --git a/.gsd/phases/7/VERIFICATION.md b/.gsd/phases/7/VERIFICATION.md deleted file mode 100644 index 325996e14d1f57ad4803d84c105b108997e9a102..0000000000000000000000000000000000000000 --- a/.gsd/phases/7/VERIFICATION.md +++ /dev/null @@ -1,8 +0,0 @@ -## Phase 7 Verification - -### Must-Haves -- [x] Must-have 1 — Proxy routing setup so React dev server (`:3000`) speaks to FastAPI smoothly (`:8000`) - VERIFIED (evidence: `rewrites()` created in `next.config.ts`, returning standard proxy map to Localhost:8000). -- [x] Must-have 2 — Recreated the Candidate Upload workflow - VERIFIED (evidence: Built `CandidateView.tsx` with unified Upload UI -> POST `/candidates/analyze` using Javascript `FormData` to accommodate backend parsing of semantic pdf blocks). -- [x] Must-have 3 — Rebuilt the Team Analysis pipeline - VERIFIED (evidence: Built `TeamView.tsx` processing form inputs logically; mappings generate semantic SVG urgency colored badges for domains, and output `hires_plan` in `` primitives). - -### Verdict: PASS diff --git a/.gsd/phases/8/1-PLAN.md b/.gsd/phases/8/1-PLAN.md deleted file mode 100644 index 19c5ed7fbf93f81f02c191698cfa7bc446516b06..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/1-PLAN.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -phase: 8 -plan: 1 -wave: 1 ---- - -# Plan 8.1: Gemini Semantic Engine & Deep Repo Analysis - -## Objective -Migrate the core skillset matching logic from legacy embeddings to Gemini API, including deep analysis of GitHub repository metadata (`README.md`, `requirements.txt`, `package.json`) to ascertain implicit skill associations like NLP architecture overlapping with BERT. - -## Context -- `backend/services/skill_matcher.py` -- `backend/services/github_analyzer.py` - -## Tasks - - - Install Gemini - backend/requirements.txt - - - Add `google-generativeai` to `requirements.txt` and install it in the local Python environment. - - grep -q "generativeai" "backend/requirements.txt" - Gemini SDK is available for importing. - - - - GitHub Deep Context Extractor - backend/services/github_analyzer.py - - - Update `github_analyzer.py` to additionally fetch the base `README.md` and common dependency files (`requirements.txt`, `package.json`, `pom.xml`) content (base64 decoded). - - Append this extracted raw text context to the candidate's GitHub profile returning payload. - - grep -q "readme" "backend/services/github_analyzer.py" - Repo analysis pulls metadata instead of just languages. - - - - Gemini Semantic Matcher Proxy - backend/services/skill_matcher.py, backend/config.py - - - Ensure `.env` reads `GEMINI_API_KEY`. - - Refactor `SkillMatcher` to construct an LLM prompt containing: JD String, Candidate Extracted Resumes Skills, and GitHub extracted texts (READMEs & dependencies). - - Prompt Gemini to return a structured JSON matching the original schema (`match_score`, `skill_gaps`, `category_scores` for Radar UI, `rationale`). - - grep -q "gemini" "backend/services/skill_matcher.py" - The matcher evaluates candidates using AI reasoning instead of euclidean text vectors. - - -## Success Criteria -- [ ] Backend successfully initializes `google.generativeai` client. -- [ ] Explicitly recognizes cross-domain sub-skills accurately (e.g., Tensorflow -> ML). diff --git a/.gsd/phases/8/1-SUMMARY.md b/.gsd/phases/8/1-SUMMARY.md deleted file mode 100644 index 77bec5a55d12beb13b6c471ca62344c19c2dbd1a..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/1-SUMMARY.md +++ /dev/null @@ -1,30 +0,0 @@ -# Plan 8.1 Summary: Gemini Semantic Engine & Deep Repo Analysis - -## Status: ✅ Complete (Pre-existing) - -All three tasks in this plan were already implemented in prior phases. - -## Tasks Completed - -### Task 1: Install Gemini -- `google-generativeai>=0.8.3` already present in `requirements.txt` -- **Verified**: `grep -q "generativeai" "requirements.txt"` → PASS - -### Task 2: GitHub Deep Context Extractor -- `github_analyzer.py` already has `_fetch_repo_context()` method and `CONTEXT_FILES` constant -- Fetches README.md, requirements.txt, package.json, pom.xml, build.gradle, Cargo.toml, go.mod -- Base64-decodes content, truncates to 4000 chars per file -- Returns `repo_context` key in analyze() payload -- **Verified**: `grep -q "readme" "backend/services/github_analyzer.py"` → PASS - -### Task 3: Gemini Semantic Matcher Proxy -- `skill_matcher.py` has full Gemini integration: - - `_get_gemini_model()` lazy-loads Gemini with `GEMINI_API_KEY` from config - - `_gemini_match()` builds structured prompt with JD, skills, and repo context - - Returns `category_scores` for radar UI, `semantic_matches`, rationale - - Falls back to embedding-based matching if Gemini unavailable -- `config.py` reads `GEMINI_API_KEY` from `.env` -- **Verified**: `grep -q "gemini" "backend/services/skill_matcher.py"` → PASS - -## No Code Changes Needed -All functionality was already in place from earlier phase execution. diff --git a/.gsd/phases/8/2-PLAN.md b/.gsd/phases/8/2-PLAN.md deleted file mode 100644 index deb4db8fb06b4c8514987b42f31e8138f5a67873..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/2-PLAN.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -phase: 8 -plan: 2 -wave: 2 ---- - -# Plan 8.2: Candidate Radar Navigation - -## Objective -Convert numerical capability mappings produced by Gemini into stunning responsive Radar charts tracking multiple technical attributes symmetrically, making caliber visual and intuitive for recruiters. - -## Context -- `frontend/src/components/dashboard/CandidateView.tsx` -- The `category_scores` JSON map dictating (Frontend, Backend, Cloud, AI, etc.). - -## Tasks - - - Install Recharts - frontend/package.json - - - Add `recharts` to the frontend using `npm install recharts`. - - grep -q "recharts" "frontend/package.json" - Charts library available for shadcn rendering. - - - - Build Radar Component Widget - frontend/src/components/dashboard/CandidateView.tsx - - - Ensure `` handles the returning payload's `category_scores`. - - Drop in the `` from recharts mapped dynamically across the keys provided by Gemini (e.g. `System Architecture`, `DevOps`, `Machine Learning`). - - Place the Graph next to the Executive Summary Card seamlessly. - - grep -q "RadarChart" "frontend/src/components/dashboard/CandidateView.tsx" - Interactive UI renders flawlessly drawing the candidate's holistic skill depth. - - -## Success Criteria -- [ ] Radar Chart expands gracefully alongside the UI mapping the `0-100` metrics per sub-category perfectly utilizing Tailwind CSS coloring conventions mapping back to the Shadcn primary brand color. diff --git a/.gsd/phases/8/2-SUMMARY.md b/.gsd/phases/8/2-SUMMARY.md deleted file mode 100644 index bdc7a4e454d7b43526eeee372aa49a12fe5262da..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/2-SUMMARY.md +++ /dev/null @@ -1,20 +0,0 @@ -# Plan 8.2 Summary: Candidate Radar Navigation - -## Status: ✅ Complete - -Implemented the visual capability mappings using Recharts to display a Radar chart of the candidate's skills across different domains. - -## Tasks Completed - -### Task 1: Install Recharts -- Added `recharts` to the frontend `package.json` dependencies. -- **Verified**: `recharts` is installed. - -### Task 2: Build Radar Component Widget -- Modified `frontend/src/components/dashboard/CandidateView.tsx`. -- Transformed the `category_scores` returned from Gemini into the data format expected by Recharts. -- Integrated the `` component wrapped in a ``. -- Mapped domains like `frontend`, `backend`, `ml_ai` to human-readable labels. -- Added visual enhancements like badges for matched, missing, and bonus skills. -- Displayed the AI's semantic reasoning (the cross-domain capability mapping). -- **Verified**: Contains `` and handles the dynamic score keys appropriately. diff --git a/.gsd/phases/8/3-PLAN.md b/.gsd/phases/8/3-PLAN.md deleted file mode 100644 index e60bd7f1466b84c3c207800cf82cc71c3270758c..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/3-PLAN.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -phase: 8 -plan: 3 -wave: 2 ---- - -# Plan 8.3: Mass PDF Team Uploader - -## Objective -Transition the Team capabilities intake flow from manual comma-separated strings to an automated batch PDF processor identifying the aggregated capabilities of an entire engineering team from their raw resumes seamlessly. - -## Context -- `backend/api/teams.py` -- `frontend/src/components/dashboard/TeamView.tsx` - -## Tasks - - - Redesign Backend for Multipart/Form-Data Bulk - backend/api/teams.py - - - Modify the `/api/teams/analyze` endpoint. Instead of `TeamAnalysisRequest` (JSON), make the post route accept `resumes: List[UploadFile]`, `market_location: str`, `project_description: str`. - - Iterate and run `resume_parser.py` logic combining every `parsed_skills` array together into an aggregated master-list. - - Feed the master-list downward matching the previous Team Analyzer schema exactly! - - grep -q "UploadFile" "backend/api/teams.py" - FastAPI successfully ingests dozens of PDFs joining them analytically into an entity graph. - - - - React Multi-File Drag-and-Drop - frontend/src/components/dashboard/TeamView.tsx, frontend/src/lib/api.ts - - - Alter `analyzeTeam` in `api.ts` to accept and send `FormData` containing the array of ``. - - Inside `TeamView.tsx`, remove `currentSkills` and `teamSize` text-inputs. Replace it with a robust Bulk Upload UI showing the number of queued attachments (resumes). - - Post the Payload asynchronously matching the new backend schema requirements. - - grep -q "multiple" "frontend/src/components/dashboard/TeamView.tsx" - The Team Dash accepts a folder of resumes seamlessly. - - -## Success Criteria -- [ ] Batch upload correctly sums the capabilities and maps accurate gap calculations without user-entry of skills! -- [ ] Generates Hire Plans targeting the missing spaces left after analyzing ALL `N` resumes submitted. diff --git a/.gsd/phases/8/3-SUMMARY.md b/.gsd/phases/8/3-SUMMARY.md deleted file mode 100644 index a45838dec797cf4be889509310acb367ab266939..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/3-SUMMARY.md +++ /dev/null @@ -1,24 +0,0 @@ -# Plan 8.3 Summary: Mass PDF Team Uploader - -## Status: ✅ Complete - -Upgraded the Team capabilities intake flow to support bulk PDF resume uploads, extracting and aggregating skills automatically. - -## Tasks Completed - -### Task 1: Redesign Backend for Multipart/Form-Data Bulk -- Updated `backend/api/routes/teams.py` to add a new endpoint `/teams/analyze-bulk`. -- The endpoint accepts `List[UploadFile]` for the resumes and form fields for project details. -- Iterates over the uploaded PDFs, utilizes the existing `ResumeParser` to extract skills. -- Aggregates the skills uniquely into a master list. -- Passes this master list into the standard `TeamAnalyzer` gap calculation pipeline. -- Returns detailed parsing statistics (total resumes, unique skills) alongside the hire plan. -- **Verified**: Verified `UploadFile` is utilized in `teams.py`. - -### Task 2: React Multi-File Drag-and-Drop -- Altered `frontend/src/lib/api.ts` to add `analyzeTeamBulk` function handling `FormData` posts. -- Redesigned `TeamView.tsx` to remove manual text inputs for skills and team size. -- Implemented a robust multi-file drag-and-drop zone using `UploadCloud`. -- Added a file queue UI to visualize the uploaded resumes and allow removals before submission. -- Adjusted the response view to show how many resumes were parsed and how many unique skills were discovered. -- **Verified**: Verified `multiple` attribute exists on the file input in `TeamView`. diff --git a/.gsd/phases/8/RESEARCH.md b/.gsd/phases/8/RESEARCH.md deleted file mode 100644 index a80e6d9e4e7158e237b5f338600ab3d173e412db..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/RESEARCH.md +++ /dev/null @@ -1,18 +0,0 @@ -# RESEARCH: Phase 8 Options - -## 1. Gemini API Integration -**Goal**: Move from basic rigid embeddings to an LLM capable of mapping implicit dependencies (e.g., BERT -> NLP, React -> JavaScript). -**Context limit**: Gemini 1.5 Pro and Flash have 1-2M token limits which effortlessly ingest READMEs and `requirements.txt`/`package.json` strings. -**Changes**: We'll swap `sentence-transformers` out of `skill_matcher.py` or run a parallel `gemini_matcher.py` service that structures the gap identification dynamically via `google-generativeai`. - -## 2. GitHub README/Dep Extraction -**Goal**: Pull only the documentation and dependency files, not the whole codebase. -**Action**: The GitHub API endpoint `/repos/{owner}/{repo}/contents/{path}` allows fetching `README.md` and `requirements.txt`. These fetched strings will be concatenated and sent inside the Gemini evaluation prompt. - -## 3. Radar Charts -**Goal**: Display visual polygon charts of candidate capabilities. -**Action**: We'll utilize `recharts` (a highly popular React charting library frequently paired with shadcn/ui) to construct responsive, animated Radar charts mapping `category_scores` (e.g., Backend, Frontend, Cloud, DevOps, ML). - -## 4. Mass PDF Uploader -**Goal**: Avoid manual typing of team skills by extracting them directly from bulk resume uploads. -**Action**: The `CandidateView` currently parses one PDF via `resume_parser.py`. We will upgrade `TeamView` and the backend `POST /teams/analyze` endpoint to accept `multipart/form-data` with an array of files (`List[UploadFile]`). It will map over each resume, extract the skills, join the unified set, and compute the gap analysis. diff --git a/.gsd/phases/8/VERIFICATION.md b/.gsd/phases/8/VERIFICATION.md deleted file mode 100644 index a242d7efe8e194e8cd7507bc13cd2437bd9a80f2..0000000000000000000000000000000000000000 --- a/.gsd/phases/8/VERIFICATION.md +++ /dev/null @@ -1,8 +0,0 @@ -## Phase 8 Verification - -### Must-Haves -- [x] Gemini API integrated for semantic mapping (evidence: `backend/services/skill_matcher.py`) -- [x] Radar charts implemented for candidate UI (evidence: `frontend/src/components/dashboard/CandidateView.tsx`) -- [x] Mass PDF Uploader implemented in team gap analysis (evidence: `frontend/src/components/dashboard/TeamView.tsx`, `backend/api/routes/teams.py`) - -### Verdict: PASS diff --git a/.gsd/phases/9/1-PLAN.md b/.gsd/phases/9/1-PLAN.md deleted file mode 100644 index 55ff05b79848b0c99fc1a8cd70109b8254f98e90..0000000000000000000000000000000000000000 --- a/.gsd/phases/9/1-PLAN.md +++ /dev/null @@ -1,12 +0,0 @@ -# Plan 9.1: Shadcn Chart Integration - -## Objective -Install the Shadcn UI `chart` component into the Next.js application to provide the structural foundation and aesthetic wrappers for the new interactive radar charts. - -## Context -The standard Recharts library provides generic visual components. The user has requested a "Radar Chart - Dots" design built utilizing Shadcn's specialized `chart.tsx` registry, which provides tooltip contexts, theme-aware colors (`var(--chart-1)`), and responsive configuration scaling. - -## Tasks -1. Execute `npx shadcn-ui@latest add chart` in the `frontend` directory. -2. Verify generation of `src/components/ui/chart.tsx` and related configuration. -3. Verify `lucide-react` and `recharts` dependencies are aligned with the new `chart` component expectations without causing resolution conflicts. diff --git a/.gsd/phases/9/1-SUMMARY.md b/.gsd/phases/9/1-SUMMARY.md deleted file mode 100644 index cae32a90fddcf6770d10a97525bd8087e696c092..0000000000000000000000000000000000000000 --- a/.gsd/phases/9/1-SUMMARY.md +++ /dev/null @@ -1,17 +0,0 @@ -# Plan 9.1 Summary: Shadcn Chart Integration - -## Status: ✅ Complete - -Integrated Shadcn `chart` components successfully. - -## Tasks Completed - -### Task 1: Install `chart` Component -- Executed `npx shadcn@latest add chart` in the `frontend` directory. -- Deprecation of `shadcn-ui` bypassed using the updated CLI package natively. -- **Verified**: Process resolved dependency installations and generated `src/components/ui/chart.tsx` properly. - -### Task 2: Verify Architecture -- Generated `src/components/ui/chart.tsx` config mapping element. -- Existent dependencies for Next.js, Radix UI, and Recharts were fully honored by the package manager without collision. -- Skip logic engaged for existing components (`card.tsx` preserved without overwrite). diff --git a/.gsd/phases/9/2-PLAN.md b/.gsd/phases/9/2-PLAN.md deleted file mode 100644 index a958b621157e9cad7314a33d2e06568607ec8d74..0000000000000000000000000000000000000000 --- a/.gsd/phases/9/2-PLAN.md +++ /dev/null @@ -1,17 +0,0 @@ -# Plan 9.2: Implement Shadcn Radar Chart and Verification Badges - -## Objective -Revamp the `CandidateView` UI report by replacing the legacy radar chart with the dynamic "Radar Chart - Dots" design, and display real-time tracking badges for the system's asynchronous background tools (GitHub, LeetCode, Gemini). - -## Context -The current candidate analysis output returns nested objects detailing GitHub hits (`github_analysis`), LeetCode solving history (`leetcode_analysis`), and the semantic assessment engine utilized (`scoring.skill_match.details.engine`). A visual badge block is required for UX clarity. - -## Tasks -1. Build a localized `ChartRadarDots` inner-component in `CandidateView.tsx`. - - Map the `labelMap` output to expected `config` keys (e.g., `frontend: { label: "Frontend", color: "var(--chart-1)" }`). - - Pass `radarData` to the new `ChartContainer` UI. -2. Develop a `VerificationBadges` component. - - Track `result.github_analysis` — showing a `` (success), `` (not found), or `` (error). - - Track `result.leetcode_analysis` — identical tracking logic. - - Track Gemini Intelligence via `result.scoring?.skill_match?.details?.engine === "gemini"`. -3. Integrate these badges immediately contiguous to the Executive Summary or Match Score sections. diff --git a/.gsd/phases/9/2-SUMMARY.md b/.gsd/phases/9/2-SUMMARY.md deleted file mode 100644 index 06c7219d661e05fc888e4db3120e59df0e655561..0000000000000000000000000000000000000000 --- a/.gsd/phases/9/2-SUMMARY.md +++ /dev/null @@ -1,20 +0,0 @@ -# Plan 9.2 Summary: Shadcn Radar Chart and Verification Badges - -## Status: ✅ Complete - -Replaced the legacy radar chart logic with the requested Shadcn interface and added the 3 verification state badges to the executive profile. - -## Tasks Completed - -### Task 1: Recharts to Shadcn Chart Transformation -- Extracted raw Recharts implementation from `CandidateView.tsx`. -- Instantiated Shadcn `ChartContainer`, replacing standalone tooltips with `ChartTooltip` and applying conditional thematic styling via css variables (`var(--color-score)`). -- Bound the dynamic category scale mapping directly into the new Chart UI format. - -### Task 2: Verification Badges Component -- Built a flex container underneath the "Analysis Complete" action bar in `CandidateView.tsx`. -- Rendered 3 specific chips evaluating the background APIs: - - **Gemini**: Dynamically verifies whether semantic reasoning evaluated effectively via `result.scoring?.skill_match?.details?.engine === "gemini"`. (Green Check / Red X) - - **GitHub**: Examines error tracking logic and user verification statuses mapped from `result.github_analysis`. - - **LeetCode**: Maps validation of graph responses and API states. -- Utilized `lucide-react` icons (CheckCircle2, MinusCircle, XCircle) as explicitly requested to signal status. diff --git a/.gsd/phases/9/VERIFICATION.md b/.gsd/phases/9/VERIFICATION.md deleted file mode 100644 index 979cd38c5bc176999a31c33739ff6e2842cb9aa9..0000000000000000000000000000000000000000 --- a/.gsd/phases/9/VERIFICATION.md +++ /dev/null @@ -1,9 +0,0 @@ -## Phase 9 Verification - -### Must-Haves -- [x] Replace Recharts pure Radar Chart with Shadcn Chart UI format — VERIFIED (evidence: `ChartContainer` wrapping `RadarChart` with var(--color) styling in `CandidateView.tsx`) -- [x] Add verification badges for GitHub — VERIFIED (evidence: Maps `result.github_analysis` and displays green/amber/red status badges dependent on connection state) -- [x] Add verification badges for LeetCode — VERIFIED (evidence: Mapped logic for `result.leetcode_analysis` with distinct Lucide icons) -- [x] Add verification badge for Gemini — VERIFIED (evidence: Dynamic display on the semantic match flag based on `engine === "gemini"`) - -### Verdict: PASS diff --git a/.gsd/templates/DEBUG.md b/.gsd/templates/DEBUG.md deleted file mode 100644 index 02f5b5906c87f3578b3a9abfd7cc32a2bda12ae4..0000000000000000000000000000000000000000 --- a/.gsd/templates/DEBUG.md +++ /dev/null @@ -1,123 +0,0 @@ -# Debug Template - -Template for `.gsd/debug/[slug].md` — active debug session tracking. - ---- - -## File Template - -```markdown ---- -status: gathering | investigating | fixing | verifying | resolved -trigger: "[verbatim user input]" -created: [ISO timestamp] -updated: [ISO timestamp] ---- - -## Current Focus - - -hypothesis: [current theory being tested] -test: [how testing it] -expecting: [what result means if true/false] -next_action: [immediate next step] - -## Symptoms - - -expected: [what should happen] -actual: [what actually happens] -errors: [error messages if any] -reproduction: [how to trigger] -started: [when it broke / always broken] - -## Eliminated - - -- hypothesis: [theory that was wrong] - evidence: [what disproved it] - timestamp: [when eliminated] - -## Evidence - - -- timestamp: [when found] - checked: [what was examined] - found: [what was observed] - implication: [what this means] - -## Resolution - - -root_cause: [empty until found] -fix: [empty until applied] -verification: [empty until verified] -files_changed: [] -``` - ---- - -## Section Rules - -**Frontmatter (status, trigger, timestamps):** -- `status`: OVERWRITE - reflects current phase -- `trigger`: IMMUTABLE - verbatim user input, never changes -- `created`: IMMUTABLE - set once -- `updated`: OVERWRITE - update on every change - -**Current Focus:** -- OVERWRITE entirely on each update -- Always reflects what AI is doing RIGHT NOW -- If AI reads this after session reset, it knows exactly where to resume -- Fields: hypothesis, test, expecting, next_action - -**Symptoms:** -- Written during initial gathering phase -- IMMUTABLE after gathering complete -- Reference point for what we're trying to fix - -**Eliminated:** -- APPEND only - never remove entries -- Prevents re-investigating dead ends after context reset -- Critical for efficiency across session boundaries - -**Evidence:** -- APPEND only - never remove entries -- Facts discovered during investigation -- Builds the case for root cause - -**Resolution:** -- OVERWRITE as understanding evolves -- Final state shows confirmed root cause and verified fix - ---- - -## Lifecycle - -**Creation:** When /debug is called -- Create file with trigger from user input -- Set status to "gathering" -- next_action = "gather symptoms" - -**During investigation:** -- OVERWRITE Current Focus with each hypothesis -- APPEND to Evidence with each finding -- APPEND to Eliminated when hypothesis disproved - -**On resolution:** -- status → "resolved" -- Move file to .gsd/debug/resolved/ - ---- - -## Resume Behavior - -When AI reads this file after session reset: - -1. Parse frontmatter → know status -2. Read Current Focus → know exactly what was happening -3. Read Eliminated → know what NOT to retry -4. Read Evidence → know what's been learned -5. Continue from next_action - -The file IS the debugging brain. diff --git a/.gsd/templates/PLAN.md b/.gsd/templates/PLAN.md deleted file mode 100644 index 797ae37deadf47d40d7e580ba5cbd2cfd7b3f682..0000000000000000000000000000000000000000 --- a/.gsd/templates/PLAN.md +++ /dev/null @@ -1,90 +0,0 @@ -# PLAN.md Template - -> Copy this template when creating execution plans. - -```markdown ---- -phase: {N} -plan: {M} -wave: {W} -gap_closure: false ---- - -# Plan {N}.{M}: {Descriptive Name} - -## Objective -{One paragraph explaining what this plan delivers and why it matters} - -## Context -Load these files for context: -- .gsd/SPEC.md -- .gsd/ARCHITECTURE.md -- {relevant source files} - -## Tasks - - - {Clear, specific task name} - - {exact/file/path1.ext} - {exact/file/path2.ext} - - - {Specific implementation instructions} - - Steps: - 1. {Step 1} - 2. {Step 2} - 3. {Step 3} - - AVOID: {common mistake} because {reason} - USE: {preferred approach} because {reason} - - - {Executable command or check} - Example: npm test -- --testNamePattern="auth" - Example: curl -X POST localhost:3000/api/login - - - {Measurable acceptance criteria} - Example: Valid credentials → 200 + Set-Cookie, invalid → 401 - - - - - {Task 2 name} - {files} - {instructions} - {command} - {criteria} - - -## Must-Haves -After all tasks complete, verify: -- [ ] {Must-have 1 — derived from phase goal} -- [ ] {Must-have 2} - -## Success Criteria -- [ ] All tasks verified passing -- [ ] Must-haves confirmed -- [ ] No regressions in tests -``` - -## Task Types - -| Type | Use For | Behavior | -|------|---------|----------| -| `auto` | Everything Claude can do independently | Fully autonomous | -| `checkpoint:human-verify` | Visual/functional verification | Pauses for user | -| `checkpoint:decision` | Implementation choices | Pauses for user | - -## Wave Assignment - -| Wave | Use For | -|------|---------| -| 1 | Foundation (types, schemas, utilities) | -| 2 | Core implementations | -| 3 | Integration and validation | - -Plans in the same wave can run in parallel. -Later waves depend on earlier waves. diff --git a/.gsd/templates/RESEARCH.md b/.gsd/templates/RESEARCH.md deleted file mode 100644 index c68bde1392d862dbdd94dc7d33a9d27ae2c9977b..0000000000000000000000000000000000000000 --- a/.gsd/templates/RESEARCH.md +++ /dev/null @@ -1,75 +0,0 @@ -# RESEARCH.md Template - -> Copy this template when documenting phase research. - -```markdown ---- -phase: {N} -researched_at: {YYYY-MM-DD} -discovery_level: 1 | 2 | 3 ---- - -# Phase {N} Research - -## Objective -{What question is this research answering?} - -## Discovery Level -**Level {1|2|3}** — {Quick verification | Standard research | Deep dive} - -## Key Decisions - -### Decision 1: {Topic} -**Question:** {What needed to be decided?} -**Options Considered:** -1. {Option A}: {pros/cons} -2. {Option B}: {pros/cons} -3. {Option C}: {pros/cons} - -**Decision:** {Which option and why} -**Confidence:** {High | Medium | Low} - -### Decision 2: {Topic} -... - -## Findings - -### {Topic 1} -{What was learned} - -**Sources:** -- {URL or reference} -- {URL or reference} - -### {Topic 2} -{What was learned} - -## Patterns to Follow -- {Pattern 1}: {How to apply it} -- {Pattern 2}: {How to apply it} - -## Anti-Patterns to Avoid -- {Anti-pattern 1}: {Why to avoid} -- {Anti-pattern 2}: {Why to avoid} - -## Dependencies Identified -| Package | Version | Purpose | -|---------|---------|---------| -| {pkg} | {ver} | {why needed} | - -## Risks -- **{Risk 1}:** {Impact and mitigation} -- **{Risk 2}:** {Impact and mitigation} - -## Recommendations for Planning -1. {Recommendation 1} -2. {Recommendation 2} -``` - -## Discovery Levels - -| Level | Time | Use When | -|-------|------|----------| -| 1 | 2-5 min | Single known library, confirming syntax | -| 2 | 15-30 min | Choosing between options, new integration | -| 3 | 1+ hour | Architectural decision, novel problem | diff --git a/.gsd/templates/SUMMARY.md b/.gsd/templates/SUMMARY.md deleted file mode 100644 index f9af3eb849e34da6bef103d70f9e321de9a2b762..0000000000000000000000000000000000000000 --- a/.gsd/templates/SUMMARY.md +++ /dev/null @@ -1,103 +0,0 @@ -# Summary Template - -Template for `.gsd/phases/{N}/{plan}-SUMMARY.md` — execution summary after plan completion. - ---- - -## File Template - -```markdown ---- -phase: {N} -plan: {M} -completed_at: [ISO timestamp] -duration_minutes: {N} -status: complete | partial | failed ---- - -# Summary: {Plan Name} - -## Results - -- **Tasks:** {N}/{M} completed -- **Commits:** {N} -- **Verification:** {passed | failed} - ---- - -## Tasks Completed - -| Task | Description | Commit | Status | -|------|-------------|--------|--------| -| 1 | {task name} | {hash} | ✅ Complete | -| 2 | {task name} | {hash} | ✅ Complete | -| 3 | {task name} | — | ❌ Blocked | - ---- - -## Files Changed - -| File | Change Type | Description | -|------|-------------|-------------| -| {path} | Created | {what it does} | -| {path} | Modified | {what changed} | -| {path} | Deleted | {why removed} | - ---- - -## Deviations Applied - -{If none: "None — executed as planned."} - -### Rule 1 — Bug Fixes -- {description of bug fixed} - -### Rule 2 — Missing Critical -- {description of functionality added} - -### Rule 3 — Blocking Issues -- {description of blocker fixed} - ---- - -## Verification - -| Check | Status | Evidence | -|-------|--------|----------| -| {verification 1} | ✅ Pass | {command/output} | -| {verification 2} | ✅ Pass | {command/output} | - ---- - -## Notes - -{Any observations, concerns, or recommendations for future phases} - ---- - -## Metadata - -- **Started:** {timestamp} -- **Completed:** {timestamp} -- **Duration:** {N} minutes -- **Context Usage:** ~{N}% -``` - ---- - -## Guidelines - -**Create SUMMARY.md:** -- After each plan completes -- Before moving to next plan -- Even if plan failed (document what happened) - -**Include:** -- All commits with hashes -- All deviations (never hide these) -- Verification results with evidence - -**Keep it factual:** -- No opinions -- Just what happened -- Evidence over claims diff --git a/.gsd/templates/UAT.md b/.gsd/templates/UAT.md deleted file mode 100644 index ab8dea371f3b4ab631af5ce8fe81e6b9133ff92d..0000000000000000000000000000000000000000 --- a/.gsd/templates/UAT.md +++ /dev/null @@ -1,168 +0,0 @@ -# UAT Template - -Template for `.gsd/phases/{N}/UAT.md` — User Acceptance Testing checklist. - -**Purpose:** Structured manual testing protocol for human verification checkpoints. - ---- - -## File Template - -```markdown ---- -phase: {N} -type: uat -created: [ISO timestamp] -status: pending | in_progress | passed | failed ---- - -# Phase {N} UAT - -## Overview - -**Phase:** {name} -**Goal:** {what this phase delivers} -**Tester:** User -**Date:** {date} - ---- - -## Test Environment - -**Setup Required:** -- [ ] Dev server running (`npm run dev`) -- [ ] Database seeded with test data -- [ ] Browser dev tools open for error monitoring - -**Test Data:** -- User: test@example.com / password123 -- Other relevant test accounts/data - ---- - -## Test Cases - -### TC-01: {Test Case Name} - -**Scenario:** {What user is trying to do} - -**Steps:** -1. {Step 1} -2. {Step 2} -3. {Step 3} - -**Expected Result:** -- {What should happen} - -**Actual Result:** -- [ ] PASS -- [ ] FAIL — Issue: ___ - ---- - -### TC-02: {Test Case Name} - -**Scenario:** {What user is trying to do} - -**Steps:** -1. {Step 1} -2. {Step 2} - -**Expected Result:** -- {What should happen} - -**Actual Result:** -- [ ] PASS -- [ ] FAIL — Issue: ___ - ---- - -## Edge Cases - -### EC-01: {Edge Case Name} - -**Test:** {What to try} -**Expected:** {Graceful handling} -**Result:** [ ] PASS [ ] FAIL - ---- - -## Error Scenarios - -### ERR-01: {Error Scenario} - -**Trigger:** {How to cause error} -**Expected Behavior:** {Error message, recovery} -**Result:** [ ] PASS [ ] FAIL - ---- - -## Visual Verification - -### VIS-01: Layout - -- [ ] Responsive on mobile (375px) -- [ ] Responsive on tablet (768px) -- [ ] Desktop layout correct (1024px+) -- [ ] No horizontal scroll -- [ ] All text readable - -### VIS-02: Styling - -- [ ] Colors match design system -- [ ] Fonts correct -- [ ] Spacing consistent -- [ ] Icons display correctly - ---- - -## Summary - -| Category | Pass | Fail | Total | -|----------|------|------|-------| -| Functional | | | | -| Edge Cases | | | | -| Errors | | | | -| Visual | | | | - -**Overall Status:** [ ] APPROVED [ ] NEEDS FIXES - -**Issues Found:** -1. {Issue description} -2. {Issue description} - -**Notes:** -{Any additional observations} -``` - ---- - -## Usage Guidelines - -**When to create UAT:** -- After phase execution complete -- Before marking phase as verified -- For any `checkpoint:human-verify` tasks - -**Who runs UAT:** -- User (always) -- AI cannot verify visual/UX elements - -**After UAT:** -- If PASSED: Phase can be marked complete -- If FAILED: Create gap closure plans with `/plan-milestone-gaps` - ---- - -## Test Case Guidelines - -**Good test cases:** -- Specific, reproducible steps -- Clear expected results -- One scenario per test case - -**Categories to cover:** -1. Happy path (main functionality) -2. Edge cases (boundary conditions) -3. Error handling (invalid input, failures) -4. Visual/UX (layout, responsiveness) diff --git a/.gsd/templates/VERIFICATION.md b/.gsd/templates/VERIFICATION.md deleted file mode 100644 index 8016ab71054ff6328b641e0b1ada314d195e5f2f..0000000000000000000000000000000000000000 --- a/.gsd/templates/VERIFICATION.md +++ /dev/null @@ -1,70 +0,0 @@ -# VERIFICATION.md Template - -> Copy this template when creating phase verification reports. - -```markdown ---- -phase: {N} -verified_at: {YYYY-MM-DD HH:MM} -verdict: PASS | FAIL | PARTIAL -pass_count: {X} -total_count: {Y} ---- - -# Phase {N} Verification Report - -## Summary - -**{X}/{Y}** must-haves verified -**Verdict:** {PASS | FAIL | PARTIAL} - -## Must-Haves - -### ✅ 1. {Must-have description} -**Status:** PASS -**Method:** {How this was verified} -**Evidence:** -``` -{Actual command output or screenshot reference} -``` - -### ❌ 2. {Must-have description} -**Status:** FAIL -**Method:** {How this was verified} -**Expected:** {What should happen} -**Actual:** {What actually happened} -**Evidence:** -``` -{Actual command output} -``` -**Gap:** {What needs to be fixed} - -### ⏭️ 3. {Must-have description} -**Status:** SKIPPED -**Reason:** {Why this couldn't be verified} - -## Gap Closure Required - -{If verdict is FAIL or PARTIAL, list what needs fixing} - -1. **{Gap 1}:** {Description of what's wrong and how to fix} -2. **{Gap 2}:** {Description} - -## Next Steps - -{Based on verdict} - -- If PASS: Proceed to next phase -- If FAIL: Run `/execute {N} --gaps-only` after fixing -- If PARTIAL: Address gaps then re-verify -``` - -## Evidence Types - -| Verification | Evidence Required | -|--------------|-------------------| -| API endpoint | curl command + response | -| UI behavior | Screenshot | -| Test suite | Test output | -| File exists | `ls` or `dir` output | -| Build passes | Build command output | diff --git a/.gsd/templates/architecture.md b/.gsd/templates/architecture.md deleted file mode 100644 index e946615a009c5cfc5ce6400eb4b10b6c31bd4c9e..0000000000000000000000000000000000000000 --- a/.gsd/templates/architecture.md +++ /dev/null @@ -1,67 +0,0 @@ -# Architecture - -> Auto-generated by /map on - -## Overview - -{Brief description of the system and its purpose.} - -``` -┌───────────────────────────────────────────────────────────────┐ -│ USER │ -└────────────────────────┬──────────────────────────────────────┘ - │ - ▼ -┌───────────────────────────────────────────────────────────────┐ -│ COMPONENT A │ -└────────────────────────┬──────────────────────────────────────┘ - │ - ▼ -┌───────────────────────────────────────────────────────────────┐ -│ COMPONENT B │ -└───────────────────────────────────────────────────────────────┘ -``` - -## Components - -### Component A -- **Purpose:** {What this component does} -- **Location:** `{path/to/component}` -- **Files:** {count} files -- **Pattern:** {architectural pattern used} - -| File | Purpose | Priority | -|------|---------|----------| -| file1 | {purpose} | {high/medium/low} | -| file2 | {purpose} | {high/medium/low} | - -### Component B -- **Purpose:** {What this component does} -- **Location:** `{path/to/component}` - -## Data Flow - -1. **User initiates action** (e.g., {example}) -2. **Component A processes** {what happens} -3. **Component B receives** {what happens} -4. **Result returned** to user - -## Technical Debt - -- [ ] {Identified debt item 1} -- [ ] {Identified debt item 2} -- [ ] {Identified debt item 3} - -## Conventions - -**Naming:** -- {Convention 1} -- {Convention 2} - -**Structure:** -- {Convention 1} -- {Convention 2} - ---- - -*Last updated: * diff --git a/.gsd/templates/context.md b/.gsd/templates/context.md deleted file mode 100644 index 4aeff01505bac266d389c0aaa15d5918fd9d2179..0000000000000000000000000000000000000000 --- a/.gsd/templates/context.md +++ /dev/null @@ -1,91 +0,0 @@ -# Context Template - -Template for `.gsd/phases/{N}/CONTEXT.md` — user's vision for a phase. - ---- - -## File Template - -```markdown ---- -phase: {N} -name: {phase-name} -created: [ISO timestamp] ---- - -# Phase {N} Context - -## Vision - -{How the user imagines this phase working — in their words} - -## What's Essential - -Non-negotiable aspects: - -- {Essential 1} -- {Essential 2} -- {Essential 3} - -## What's Flexible - -Open to different implementations: - -- {Flexible 1} -- {Flexible 2} - -## What's Out of Scope - -Explicitly NOT part of this phase: - -- {Out of scope 1} -- {Out of scope 2} - -## User Expectations - -### Look and Feel -{How it should appear/behave} - -### Performance -{Speed/responsiveness expectations} - -### Integration -{How it fits with existing work} - -## Examples / Inspiration - -{Any examples the user referenced} - -## Questions Answered - -Clarifications from /discuss-phase: - -| Question | Answer | -|----------|--------| -| {question} | {answer} | - -## Constraints - -Technical or business constraints: - -- {Constraint 1} -- {Constraint 2} -``` - ---- - -## When to Create - -Created by `/discuss-phase` to capture user's vision before planning. - -## How to Use - -- Planner reads CONTEXT.md to understand intent -- Executor honors the vision during implementation -- Verifier checks against user expectations - -## Guidelines - -- Capture user's words, not AI interpretation -- Focus on WHAT, not HOW -- Keep it short — vision, not specification diff --git a/.gsd/templates/decisions.md b/.gsd/templates/decisions.md deleted file mode 100644 index ba75c19271eec0c89a153a694bc6131702642c1f..0000000000000000000000000000000000000000 --- a/.gsd/templates/decisions.md +++ /dev/null @@ -1,37 +0,0 @@ -# DECISIONS.md — Architecture Decision Records - -> **Purpose**: Log significant technical decisions and their rationale. - -## Template - -```markdown -## [DECISION-XXX] Title - -**Date**: YYYY-MM-DD -**Status**: Proposed | Accepted | Deprecated | Superseded - -### Context -What is the issue we're facing? - -### Decision -What have we decided to do? - -### Rationale -Why did we make this decision? - -### Consequences -What are the trade-offs? - -### Alternatives Considered -What other options were evaluated? -``` - ---- - -## Decisions - - - ---- - -*Last updated: * diff --git a/.gsd/templates/discovery.md b/.gsd/templates/discovery.md deleted file mode 100644 index 9416aab417594a090aee042be44615f9795d0855..0000000000000000000000000000000000000000 --- a/.gsd/templates/discovery.md +++ /dev/null @@ -1,122 +0,0 @@ -# Discovery Template - -Template for `.gsd/phases/{N}/DISCOVERY.md` — shallow research for library/option decisions. - -**Purpose:** Answer "which library/option should we use" questions during planning. - -For deep ecosystem research, use `/research-phase` which produces RESEARCH.md. - ---- - -## File Template - -```markdown ---- -phase: {N} -type: discovery -topic: [discovery-topic] ---- - - -Discover [topic] to inform [phase name] implementation. - -Purpose: [What decision/implementation this enables] -Scope: [Boundaries] -Output: DISCOVERY.md with recommendation - - - - -- [Question to answer] -- [Area to investigate] -- [Specific comparison if needed] - - - -- [Out of scope for this discovery] -- [Defer to implementation phase] - - - - - -**Source Priority:** -1. **Official Docs** — Authoritative, current -2. **Web Search** — For comparisons, trends (verify findings) -3. **GitHub** — For real usage patterns - -**Quality Checklist:** -- [ ] All claims have authoritative sources -- [ ] Negative claims verified with official docs -- [ ] Alternative approaches considered -- [ ] Recent updates checked for breaking changes - -**Confidence Levels:** -- HIGH: Official docs confirm -- MEDIUM: Multiple sources confirm -- LOW: Single source or training knowledge only - - -``` - ---- - -## Output Structure - -Create `.gsd/phases/{N}/DISCOVERY.md`: - -```markdown -# [Topic] Discovery - -## Summary -[2-3 paragraph executive summary] - -## Primary Recommendation -[What to do and why — specific and actionable] - -## Alternatives Considered -[What else was evaluated and why not chosen] - -## Key Findings - -### [Category 1] -- [Finding with source URL] - -### [Category 2] -- [Finding with relevance] - -## Code Examples -[Relevant patterns if applicable] - -## Metadata - - -[Why this confidence level] - - - -- [Primary sources used] - - - -[What needs validation during implementation] - -``` - ---- - -## When to Use - -**Use discovery when:** -- Technology choice unclear (library A vs B) -- Best practices needed for unfamiliar integration -- API/library investigation required - -**Don't use when:** -- Established patterns (CRUD, auth with known library) -- Questions answerable from project context - -**Use RESEARCH.md instead when:** -- Niche/complex domains (3D, games, audio) -- Need ecosystem knowledge, not just library choice -- "How do experts build this" questions diff --git a/.gsd/templates/journal.md b/.gsd/templates/journal.md deleted file mode 100644 index 0667f2a788ebd7150a04cc137d143e6b50104bca..0000000000000000000000000000000000000000 --- a/.gsd/templates/journal.md +++ /dev/null @@ -1,46 +0,0 @@ -# JOURNAL.md — Session Log - -> **Purpose**: Chronicle of work sessions for context continuity. - ---- - -## Sessions - -## Session: YYYY-MM-DD HH:MM - -### Objective -{What you set out to accomplish this session.} - -### Accomplished -- ✅ {Task 1 completed} -- ✅ {Task 2 completed} - - {Sub-detail if needed} -- ✅ {Task 3 completed} - -### Verification -- [x] {Verification check 1} -- [x] {Verification check 2} -- [ ] {Verification pending} - -### Blockers Encountered -- {Blocker 1 and how it was resolved} -- {Blocker 2 — still open} - -### Handoff Notes -- {Important context for next session} -- {Files that need attention} -- {Decisions that need to be made} - ---- - -## Session: YYYY-MM-DD HH:MM - -### Objective -{Previous session objective.} - -### Accomplished -- ✅ {Completed items} - ---- - -*Last updated: * diff --git a/.gsd/templates/milestone.md b/.gsd/templates/milestone.md deleted file mode 100644 index edad7e9152f77981ac3ec58b2f133f03941223e6..0000000000000000000000000000000000000000 --- a/.gsd/templates/milestone.md +++ /dev/null @@ -1,91 +0,0 @@ -# Milestone Template - -Template for `.gsd/milestones/{name}/MILESTONE.md` — milestone definition and tracking. - ---- - -## File Template - -```markdown ---- -name: {milestone-name} -version: {semantic version, e.g., v1.0} -status: planning | active | complete | archived -created: [ISO timestamp] -target_date: [optional target] ---- - -# Milestone: {name} - -## Vision - -{What this milestone achieves — one paragraph} - -## Must-Haves - -Non-negotiable deliverables for this milestone: - -- [ ] {Must-have 1} -- [ ] {Must-have 2} -- [ ] {Must-have 3} - -## Nice-to-Haves - -If time permits: - -- [ ] {Nice-to-have 1} -- [ ] {Nice-to-have 2} - -## Phases - -| Phase | Name | Status | Objective | -|-------|------|--------|-----------| -| 1 | {name} | ⬜ Not Started | {objective} | -| 2 | {name} | ⬜ Not Started | {objective} | -| 3 | {name} | ⬜ Not Started | {objective} | - -## Success Criteria - -How we know milestone is complete: - -- [ ] {Measurable criterion 1} -- [ ] {Measurable criterion 2} - -## Architecture Decisions - -Key technical decisions for this milestone: - -| Decision | Choice | Rationale | -|----------|--------|-----------| -| {decision} | {choice} | {why} | - -## Risks - -| Risk | Likelihood | Impact | Mitigation | -|------|------------|--------|------------| -| {risk} | Low/Med/High | Low/Med/High | {action} | - -## Progress Log - -| Date | Event | Notes | -|------|-------|-------| -| {date} | Milestone started | — | -``` - ---- - -## Lifecycle - -1. **Creation:** `/new-milestone` creates this file -2. **Active:** Updated as phases complete -3. **Complete:** `/complete-milestone` moves to archive -4. **Archived:** Read-only reference - ---- - -## Guidelines - -- One active milestone at a time -- 3-5 phases per milestone -- Must-haves should be testable -- Success criteria should be measurable diff --git a/.gsd/templates/phase-summary.md b/.gsd/templates/phase-summary.md deleted file mode 100644 index 4a7087a34571f8c78475b6010da6600c5848fb44..0000000000000000000000000000000000000000 --- a/.gsd/templates/phase-summary.md +++ /dev/null @@ -1,52 +0,0 @@ -# Phase {N} Summary - -> **Status**: Complete -> **Completed**: YYYY-MM-DD - -## Objective -{What this phase set out to accomplish.} - -## Deliverables - -| Deliverable | Status | Notes | -|-------------|--------|-------| -| {Deliverable 1} | ✅ | {Any relevant notes} | -| {Deliverable 2} | ✅ | {Any relevant notes} | -| {Deliverable 3} | ✅ | {Any relevant notes} | - -## Tasks Completed - -### Plan {N}.1: {Plan Name} -- [x] {Task 1} -- [x] {Task 2} - -### Plan {N}.2: {Plan Name} -- [x] {Task 1} -- [x] {Task 2} - -## Verification Results - -| Check | Result | Evidence | -|-------|--------|----------| -| {Verification 1} | ✅ Pass | {Command output / screenshot path} | -| {Verification 2} | ✅ Pass | {Command output / screenshot path} | - -## Commits - -| Hash | Message | -|------|---------| -| `abc123` | feat(phase-N): {description} | -| `def456` | feat(phase-N): {description} | - -## Lessons Learned -- {What went well} -- {What could be improved} -- {Unexpected discoveries} - -## Next Steps -- {What the next phase should address} -- {Any deferred items} - ---- - -*Completed: YYYY-MM-DD* diff --git a/.gsd/templates/project.md b/.gsd/templates/project.md deleted file mode 100644 index 84fec9c38e91a2306af3df39184a397f29d05dc7..0000000000000000000000000000000000000000 --- a/.gsd/templates/project.md +++ /dev/null @@ -1,124 +0,0 @@ -# Project Template - -Template for `.gsd/SPEC.md` (or PROJECT.md) — project specification. - ---- - -## File Template - -```markdown ---- -status: DRAFT | FINALIZED -created: [ISO timestamp] -finalized: [ISO timestamp when status changed] ---- - -# SPEC.md — Project Specification - -## Vision - -{One paragraph describing what this project is and why it matters} - ---- - -## Goals - -1. **{Primary Goal}** - {Brief description} - -2. **{Secondary Goal}** - {Brief description} - -3. **{Tertiary Goal}** - {Brief description} - ---- - -## Non-Goals (Out of Scope) - -Explicitly NOT part of this project: - -- {Non-goal 1} -- {Non-goal 2} -- {Non-goal 3} - ---- - -## Users - -**Primary User:** {Who} -- {How they'll use it} -- {What they need} - -**Secondary User:** {Who} (if applicable) -- {How they'll use it} - ---- - -## Constraints - -### Technical -- {Technical constraint 1} -- {Technical constraint 2} - -### Timeline -- {Timeline constraint} - -### Other -- {Budget, resources, etc.} - ---- - -## Success Criteria - -How we know the project is successful: - -- [ ] {Measurable outcome 1} -- [ ] {Measurable outcome 2} -- [ ] {Measurable outcome 3} - ---- - -## Prior Art - -Existing solutions or inspiration: - -| Solution | Pros | Cons | Relevance | -|----------|------|------|-----------| -| {solution} | {pros} | {cons} | {how it relates} | - ---- - -## Open Questions - -Questions to resolve during planning: - -- [ ] {Question 1} -- [ ] {Question 2} - ---- - -## Decisions - -Key decisions made during specification: - -| Decision | Choice | Rationale | Date | -|----------|--------|-----------|------| -| {decision} | {choice} | {why} | {date} | -``` - ---- - -## Status Flow - -1. **DRAFT** — Being written, not ready for planning -2. **FINALIZED** — Approved, planning can begin - -**Planning Lock:** Cannot create plans until status is FINALIZED. - -## Guidelines - -- Keep vision to one paragraph -- Goals should be achievable in one milestone -- Non-goals are as important as goals -- Success criteria must be measurable diff --git a/.gsd/templates/requirements.md b/.gsd/templates/requirements.md deleted file mode 100644 index bcfe90955b6b5a1e9d8595bf8f87a7d17c2064fb..0000000000000000000000000000000000000000 --- a/.gsd/templates/requirements.md +++ /dev/null @@ -1,92 +0,0 @@ -# Requirements Template - -Template for `.gsd/REQUIREMENTS.md` — formal requirements tracking with traceability. - ---- - -## File Template - -```markdown ---- -milestone: {name} -updated: [ISO timestamp] ---- - -# Requirements - -## Overview - -Requirements derived from SPEC.md for traceability and coverage tracking. - ---- - -## Functional Requirements - -| ID | Requirement | Source | Phase | Status | -|----|-------------|--------|-------|--------| -| REQ-01 | {requirement description} | SPEC Goal 1 | 1 | Pending | -| REQ-02 | {requirement description} | SPEC Goal 1 | 1 | Pending | -| REQ-03 | {requirement description} | SPEC Goal 2 | 2 | Pending | -| REQ-04 | {requirement description} | SPEC Goal 2 | 2 | Pending | -| REQ-05 | {requirement description} | SPEC Goal 3 | 3 | Pending | - ---- - -## Non-Functional Requirements - -| ID | Requirement | Category | Phase | Status | -|----|-------------|----------|-------|--------| -| NFR-01 | Response time < 200ms | Performance | 4 | Pending | -| NFR-02 | Mobile responsive | UX | All | Pending | -| NFR-03 | 99% uptime | Reliability | 4 | Pending | - ---- - -## Constraints - -| ID | Constraint | Source | Impact | -|----|------------|--------|--------| -| CON-01 | {constraint} | SPEC | {affected areas} | -| CON-02 | {constraint} | Technical | {affected areas} | - ---- - -## Traceability Matrix - -| Requirement | Plans | Tests | Status | -|-------------|-------|-------|--------| -| REQ-01 | 1.1, 1.2 | TC-01 | — | -| REQ-02 | 1.2 | TC-02, TC-03 | — | -| REQ-03 | 2.1 | TC-04 | — | - ---- - -## Status Definitions - -| Status | Meaning | -|--------|---------| -| Pending | Not yet started | -| In Progress | Being implemented | -| Complete | Implemented and verified | -| Blocked | Cannot proceed | -| Deferred | Moved to later milestone | -``` - ---- - -## Guidelines - -**Requirement IDs:** -- REQ-XX: Functional requirements -- NFR-XX: Non-functional requirements -- CON-XX: Constraints - -**Good requirements are:** -- Testable -- Specific -- Traceable to SPEC goals - -**Update when:** -- Phase completes (mark requirements satisfied) -- Scope changes (add/defer requirements) -- Verification passes (update status) diff --git a/.gsd/templates/roadmap.md b/.gsd/templates/roadmap.md deleted file mode 100644 index 9efc3f95c468c08782e3398ac4103f6b0e20514a..0000000000000000000000000000000000000000 --- a/.gsd/templates/roadmap.md +++ /dev/null @@ -1,103 +0,0 @@ -# Roadmap Template - -Template for `.gsd/ROADMAP.md` — phase structure and progress tracking. - ---- - -## File Template - -```markdown ---- -milestone: {name} -version: {semantic version} -updated: [ISO timestamp] ---- - -# Roadmap - -> **Current Phase:** {N} - {name} -> **Status:** {planning | executing | verifying} - -## Must-Haves (from SPEC) - -- [ ] {Must-have 1} -- [ ] {Must-have 2} -- [ ] {Must-have 3} - ---- - -## Phases - -### Phase 1: {Foundation} -**Status:** ⬜ Not Started | 🔄 In Progress | ✅ Complete -**Objective:** {What this phase delivers} -**Requirements:** REQ-01, REQ-02 - -**Plans:** -- [ ] Plan 1.1: {name} -- [ ] Plan 1.2: {name} - ---- - -### Phase 2: {Core Feature} -**Status:** ⬜ Not Started -**Objective:** {What this phase delivers} -**Depends on:** Phase 1 - -**Plans:** -- [ ] Plan 2.1: {name} -- [ ] Plan 2.2: {name} - ---- - -### Phase 3: {Integration} -**Status:** ⬜ Not Started -**Objective:** {What this phase delivers} -**Depends on:** Phase 2 - ---- - -### Phase 4: {Polish/Launch} -**Status:** ⬜ Not Started -**Objective:** {Final touches and deployment} -**Depends on:** Phase 3 - ---- - -## Progress Summary - -| Phase | Status | Plans | Complete | -|-------|--------|-------|----------| -| 1 | ⬜ | 0/2 | — | -| 2 | ⬜ | 0/2 | — | -| 3 | ⬜ | 0/1 | — | -| 4 | ⬜ | 0/1 | — | - ---- - -## Timeline - -| Phase | Started | Completed | Duration | -|-------|---------|-----------|----------| -| 1 | — | — | — | -| 2 | — | — | — | -| 3 | — | — | — | -| 4 | — | — | — | -``` - ---- - -## Status Icons - -- ⬜ Not Started -- 🔄 In Progress -- ✅ Complete -- ⏸️ Paused -- ❌ Blocked - -## Guidelines - -- 3-5 phases per milestone -- Each phase has clear deliverable -- Dependencies flow forward -- Update status as work progresses diff --git a/.gsd/templates/spec.md b/.gsd/templates/spec.md deleted file mode 100644 index 828ffdcdb73b3c0b05fde92b579735c794de906b..0000000000000000000000000000000000000000 --- a/.gsd/templates/spec.md +++ /dev/null @@ -1,51 +0,0 @@ -# SPEC.md — Project Specification - -> **Status**: `DRAFT` | `FINALIZED` -> -> ⚠️ **Planning Lock**: No code may be written until this spec is marked `FINALIZED`. - -## Vision -{One paragraph describing what this project is and why it exists.} - -## Goals -1. **{Goal 1}** — {Brief description} -2. **{Goal 2}** — {Brief description} -3. **{Goal 3}** — {Brief description} - -## Non-Goals (Out of Scope) -- {What this project explicitly will NOT do} -- {Features that are intentionally excluded} -- {Scope boundaries} - -## Constraints -- {Technical constraint 1} -- {Business constraint 1} -- {Timeline constraint 1} - -## Success Criteria -- [ ] {Measurable outcome 1} -- [ ] {Measurable outcome 2} -- [ ] {Measurable outcome 3} -- [ ] {Measurable outcome 4} - -## User Stories (Optional) - -### As a {user type} -- I want to {action} -- So that {benefit} - -### As a {user type} -- I want to {action} -- So that {benefit} - -## Technical Requirements (Optional) - -| Requirement | Priority | Notes | -|-------------|----------|-------| -| {Requirement 1} | Must-have | {Details} | -| {Requirement 2} | Should-have | {Details} | -| {Requirement 3} | Nice-to-have | {Details} | - ---- - -*Last updated: * diff --git a/.gsd/templates/sprint.md b/.gsd/templates/sprint.md deleted file mode 100644 index b3b438be796db11ee56d350e4700ebb4fc1b4584..0000000000000000000000000000000000000000 --- a/.gsd/templates/sprint.md +++ /dev/null @@ -1,57 +0,0 @@ -# Sprint {N} — {Sprint Name} - -> **Duration**: YYYY-MM-DD to YYYY-MM-DD -> **Status**: In Progress | Complete - -## Goal -{One sentence describing what this sprint aims to achieve.} - -## Scope - -### Included -- {Feature/task 1} -- {Feature/task 2} -- {Feature/task 3} - -### Explicitly Excluded -- {Out of scope item 1} -- {Out of scope item 2} - -## Tasks - -| Task | Assignee | Status | Est. Hours | -|------|----------|--------|------------| -| {Task 1} | {who} | ⬜ Todo | {hours} | -| {Task 2} | {who} | 🔄 In Progress | {hours} | -| {Task 3} | {who} | ✅ Done | {hours} | - -## Daily Log - -### Day 1 (YYYY-MM-DD) -- {What was accomplished} -- {Blockers encountered} - -### Day 2 (YYYY-MM-DD) -- {What was accomplished} -- {Blockers encountered} - -## Risks & Blockers - -| Risk | Impact | Mitigation | -|------|--------|------------| -| {Risk 1} | {High/Med/Low} | {What can be done} | - -## Retrospective (end of sprint) - -### What Went Well -- {Positive outcome 1} - -### What Could Improve -- {Area for improvement 1} - -### Action Items -- [ ] {Action to take in next sprint} - ---- - -*Last updated: * diff --git a/.gsd/templates/stack.md b/.gsd/templates/stack.md deleted file mode 100644 index 586aaa520903ededfb05705e2408d29acf70992f..0000000000000000000000000000000000000000 --- a/.gsd/templates/stack.md +++ /dev/null @@ -1,62 +0,0 @@ -# Technology Stack - -> Auto-generated by /map on - -## Runtime - -| Technology | Version | Purpose | -|------------|---------|---------| -| {Language} | {version} | {purpose} | -| {Framework} | {version} | {purpose} | -| {Database} | {version} | {purpose} | - -## Core Technologies - -### {Category 1} -| Feature | System | Purpose | -|---------|--------|---------| -| {Feature} | {System/Location} | {Purpose} | - -### {Category 2} -| Directory | Files | Purpose | -|-----------|-------|---------| -| `{path}` | {count} | {purpose} | - -## Dependencies - -### External Dependencies - -| Package | Version | Purpose | -|---------|---------|---------| -| {package} | {version} | {purpose} | - -### Internal Dependencies - -| Component | Depends On | Purpose | -|-----------|------------|---------| -| {Component A} | {Component B} | {Why dependency exists} | - -## Infrastructure - -| Service | Provider | Purpose | -|---------|----------|---------| -| {Service} | {Provider} | {Purpose} | - -**Repository:** {repository URL} - -## Configuration - -| Variable | Purpose | Location | -|----------|---------|----------| -| {VAR_NAME} | {What it controls} | {Where it's set} | - -## File Size Inventory - -| Category | Count | Total Lines (approx) | -|----------|-------|---------------------| -| {Category} | {count} | {lines} | -| **Total** | **{total}** | **{total_lines}** | - ---- - -*Last updated: * diff --git a/.gsd/templates/state.md b/.gsd/templates/state.md deleted file mode 100644 index b7eb5347eb2a3f48276781861ad82e78fcf50d61..0000000000000000000000000000000000000000 --- a/.gsd/templates/state.md +++ /dev/null @@ -1,92 +0,0 @@ -# State Template - -Template for `.gsd/STATE.md` — project memory across sessions. - ---- - -## File Template - -```markdown ---- -updated: [ISO timestamp] ---- - -# Project State - -## Current Position - -**Milestone:** {name} -**Phase:** {N} - {name} -**Status:** {planning | executing | verifying | blocked} -**Plan:** {current plan if executing} - -## Last Action - -{What was just completed} - -## Next Steps - -1. {Immediate next action} -2. {Following action} -3. {Third action if known} - -## Active Decisions - -Decisions made that affect current work: - -| Decision | Choice | Made | Affects | -|----------|--------|------|---------| -| {what} | {choice} | {date} | {phases/plans} | - -## Blockers - -{None if clear} - -- [ ] {Blocker 1}: {resolution approach} -- [ ] {Blocker 2}: {resolution approach} - -## Concerns - -Things to watch but not blocking: - -- {Concern 1} -- {Concern 2} - -## Session Context - -{Any context the next session needs to know} -``` - ---- - -## Update Rules - -**Update STATE.md after:** -- Every completed task -- Every decision made -- Any blocker identified -- Session end/pause - -**What to update:** -- `updated` timestamp -- Current Position -- Last Action -- Next Steps - -**Keep it lean:** -- STATE.md is read frequently -- Only current context, not history -- History goes in JOURNAL.md - ---- - -## Resume Protocol - -When starting a new session: - -1. Read STATE.md first -2. Understand current position -3. Check blockers/concerns -4. Continue from Next Steps - -The STATE.md is the "save game" for the project. diff --git a/.gsd/templates/state_snapshot.md b/.gsd/templates/state_snapshot.md deleted file mode 100644 index 9c97963bf4398a20c2fe54be9e7a7945d6d50df9..0000000000000000000000000000000000000000 --- a/.gsd/templates/state_snapshot.md +++ /dev/null @@ -1,132 +0,0 @@ -# State Snapshot Template - -Template for wave summaries and session state captures. - ---- - -## When to Use - -Create a state snapshot: -- After completing each wave -- Before pausing work -- After 3 debugging failures -- When switching models mid-session -- At any significant milestone - ---- - -## Template - -```markdown ---- -wave: {N} -phase: {phase number} -created: {ISO timestamp} -status: {complete | partial | blocked} ---- - -# Wave {N} State Snapshot - -## Objective - -{What this wave aimed to accomplish — 1-2 sentences} - -## Changes Realized - -- {Change 1} -- {Change 2} -- {Change 3} - -## Files Touched - -| File | Change Type | Description | -|------|-------------|-------------| -| {path/to/file1} | created | {brief description} | -| {path/to/file2} | modified | {brief description} | -| {path/to/file3} | deleted | {brief description} | - -## Verification Results - -| Check | Command | Result | -|-------|---------|--------| -| {Test 1} | `{command}` | ✅ Passed | -| {Test 2} | `{command}` | ✅ Passed | -| {Test 3} | `{command}` | ❌ Failed: {reason} | - -## Commits in This Wave - -| Hash | Message | -|------|---------| -| {abc123} | {commit message 1} | -| {def456} | {commit message 2} | - -## Risks & Technical Debt - -{None if clear} - -- ⚠️ {Risk or debt item 1} -- ⚠️ {Risk or debt item 2} - -## TODO for Next Wave - -1. {Next task 1} -2. {Next task 2} -3. {Next task 3} - -## Context for Fresh Session - -{Any information the next session needs — decisions made, blockers encountered, hypotheses to test} - -## Token Usage (Optional) - -| Metric | Value | -|--------|-------| -| Files loaded | {count} | -| Est. tokens | {number} | -| Budget used | {percentage}% | -| Compression | {yes/no} | - -{Notes on token efficiency for this wave} -``` - ---- - -## Minimal Snapshot (Debug Session) - -For quick state dumps during debugging: - -```markdown -# Debug State Snapshot - -**Time:** {timestamp} -**Problem:** {what you're debugging} - -**Tried:** -1. {approach 1} → {result} -2. {approach 2} → {result} -3. {approach 3} → {result} - -**Current Hypothesis:** {theory} - -**Files Involved:** -- {file1} -- {file2} - -**Recommended Next:** {suggested approach for fresh session} -``` - ---- - -## Integration with STATE.md - -State snapshots are point-in-time captures. After creating a snapshot: - -1. Update STATE.md with current position -2. Reference the snapshot in SESSION Context -3. Commit both together - -STATE.md is current state; snapshots are historical records. - ---- - -*Part of GSD methodology. See PROJECT_RULES.md for wave execution rules.* diff --git a/.gsd/templates/todo.md b/.gsd/templates/todo.md deleted file mode 100644 index 5008fe26259fb25a3547e301850b5a46b966a951..0000000000000000000000000000000000000000 --- a/.gsd/templates/todo.md +++ /dev/null @@ -1,32 +0,0 @@ -# TODO.md — Pending Items - -> Quick capture of ideas, tasks, and issues. -> -> Use `/add-todo` to add items, `/check-todos` to view. - -## Format - -```markdown -- [ ] Description `priority` — YYYY-MM-DD -- [x] Completed item `priority` — YYYY-MM-DD ✓ YYYY-MM-DD -``` - -## Priority Levels - -| Level | Use For | -|-------|---------| -| `high` 🔴 | Blocking issues, urgent fixes | -| `medium` 🟡 | Normal priority (default) | -| `low` 🟢 | Nice-to-have, future ideas | - ---- - -## Items - - - -- [ ] {Example todo item} `medium` — YYYY-MM-DD - ---- - -*Last updated: * diff --git a/.gsd/templates/token_report.md b/.gsd/templates/token_report.md deleted file mode 100644 index c82477a50a49006a146d57ddfb5ea233968c7ec6..0000000000000000000000000000000000000000 --- a/.gsd/templates/token_report.md +++ /dev/null @@ -1,79 +0,0 @@ -# Token Report Template - -Template for documenting token usage per wave or session. - ---- - -## Template - -```markdown ---- -wave: {N} -phase: {phase number} -created: {ISO timestamp} ---- - -# Token Usage Report - -## Summary - -| Metric | Value | -|--------|-------| -| Files loaded | {count} | -| Estimated tokens | {number} | -| Budget usage | {percentage}% | -| Compression applied | {yes/no} | - -## Files Loaded - -| File | Lines | Est. Tokens | Reason | -|------|-------|-------------|--------| -| {path/to/file1} | {N} | {N} | {why loaded} | -| {path/to/file2} | {N} | {N} | {why loaded} | - -## Compression Applied - -| File | Before | After | Savings | -|------|--------|-------|---------| -| {file} | {N} | summary | {N} tokens | - -## Efficiency Analysis - -### What Worked Well -- {Strategy that saved tokens} - -### Could Improve -- {Opportunity for optimization} - -### Recommendations -- {Suggestion for next wave} -``` - ---- - -## When to Create - -Create a token report: -- After completing a wave with high token usage -- When budget exceeds 50% -- For debugging session performance -- During milestone retrospectives - ---- - -## Quick Report (Minimal) - -For simple tracking: - -```markdown -## Token Report: Wave {N} - -- Files: {count} -- Tokens: ~{number} -- Budget: {X}% -- Status: [OK|WARNING|CRITICAL] -``` - ---- - -*Part of GSD v1.6 Token Optimization.* diff --git a/.gsd/templates/user-setup.md b/.gsd/templates/user-setup.md deleted file mode 100644 index adc73489f5172e46989c23b378a041823cc10696..0000000000000000000000000000000000000000 --- a/.gsd/templates/user-setup.md +++ /dev/null @@ -1,116 +0,0 @@ -# User Setup Template - -Template for user setup instructions when external services are needed. - ---- - -## File Template - -```markdown ---- -phase: {N} -plan: {M} -type: user-setup ---- - -# User Setup Required - -## Overview - -This plan requires manual setup that the AI cannot perform. - -**Time estimate:** {X minutes} -**Blocking:** Plan cannot proceed until complete - ---- - -## Setup Steps - -### 1. {Service Name} - -**Why needed:** {Purpose in the project} - -**Create account:** -- Go to: {URL} -- Sign up with: {recommendations} - -**Get credentials:** -1. Navigate to: {dashboard location} -2. Find: {API keys section} -3. Create: {what to create} - -**Add to project:** -```powershell -# Add to .env.local -{ENV_VAR}=your_key_here -``` - -**Verify:** -```powershell -# Test the connection -{verification command} -``` - ---- - -### 2. {Another Service} - -**Why needed:** {Purpose} - -**Steps:** -1. {Step 1} -2. {Step 2} -3. {Step 3} - -**Environment variables:** -``` -{VAR_1}=value -{VAR_2}=value -``` - ---- - -## Dashboard Configuration - -Some things require manual dashboard setup: - -| Service | Task | Location | Notes | -|---------|------|----------|-------| -| {service} | {task} | {where} | {notes} | - ---- - -## Verification Checklist - -Before continuing, verify: - -- [ ] All environment variables set -- [ ] All accounts created -- [ ] All dashboard configurations complete -- [ ] Verification commands pass - ---- - -## When Complete - -Type "done" or "setup complete" to continue with execution. -``` - ---- - -## Guidelines - -**Include only what AI cannot do:** -- Account creation (requires human identity) -- Secret retrieval (protected behind login) -- Dashboard configuration (no API available) -- Payment method setup -- 2FA enrollment - -**Do NOT include:** -- npm install (AI can do) -- File creation (AI can do) -- Configuration file edits (AI can do) -- API calls (AI can do) - -**Keep minimal** — every manual step slows down execution. diff --git a/mds hi mds/1.md b/mds hi mds/1.md deleted file mode 100644 index 294b6d5c39eaaa271db49fd3bbfeea87ae543c24..0000000000000000000000000000000000000000 --- a/mds hi mds/1.md +++ /dev/null @@ -1,463 +0,0 @@ -new-project -🧠 HireSense AI — Intelligent Hiring & Workforce Planning System - -⸻ - -🌍 Problem & Vision - -Hiring in small startups is fundamentally broken. - -Most hiring decisions are based on resumes, which are: - • self-reported - • often exaggerated - • poor indicators of real-world ability - -Startups lack: - • dedicated HR teams - • time to deeply evaluate candidates - • tools to assess learning potential, not just current skills - -👉 The result: - • bad hires - • slow execution - • increased costs and team inefficiency - -⸻ - -💡 Vision - -HireSense AI replaces resume-based hiring with a multi-signal intelligence system that evaluates: - • real coding behavior - • verified technical activity - • learning ability - • team-level skill gaps - -It transforms hiring from guesswork → data-driven decision making. - -⸻ - -🎯 Target Users - • Early-stage startups - • Technical founders / CTOs - • Small hiring teams - -⸻ - -📊 Measurable Outcome - • Reduce hiring decision time by 50–70% - • Improve candidate-job match quality - • Detect resume inconsistencies early - • Reduce time-to-skill-acquisition through better hiring - -⸻ - -⚙️ System Architecture Overview - -HireSense operates as an end-to-end AI pipeline: - 1. Input: Resume + Job Description - 2. Extract structured data - 3. Fetch external signals (GitHub, LeetCode) - 4. Generate feature vectors - 5. Run ML-based scoring + reasoning - 6. Predict learning ability - 7. Detect inconsistencies - 8. Generate explainable report - -Additionally: - • Internal team data → skill gap analysis → hiring plan - -⸻ - -🧩 Core Modules - -⸻ - -📄 Module 1 — Resume Parser - -The system begins by extracting structured information from resumes. - -Key Functions: - • Parse PDF content - • Extract: - • name - • skills - • projects - • experience - • links (GitHub, LeetCode) - -Processing Layers: - • NLP-based entity recognition - • Regex-based extraction (emails, URLs) - • AI-assisted parsing for structured outputs - -⸻ - -💻 Module 2 — GitHub Analyzer - -Uses GitHub as a source of truth for developer ability. - -Extracted Signals: - -📈 Consistency Score - • Measures commit frequency over time - • Stable activity → high score - • Irregular bursts → lower score - -🧱 Project Depth Score - • Based on: - • stars - • watchers - • commit count - • Reflects real-world project complexity - -🌐 Tech Breadth Score - • Diversity of languages and frameworks used - -⏱️ Recency Score - • How recently the candidate has been active - -⸻ - -🧠 Module 3 — LeetCode Analyzer - -Extracts problem-solving ability from coding platforms. - -Signals: - • Problems solved (weighted by difficulty) - • Distribution across easy/medium/hard - • Consistency (streaks) - -👉 Indicates: - • algorithmic thinking - • problem-solving depth - -⸻ - -🤖 Module 4 — ML Engine (Core Intelligence) - -This is the heart of HireSense AI. - -⸻ - -🔹 4.1 Skill Similarity Model - • Converts: - • candidate skills - • job requirements -into vector representations - • Computes: - • overall match score - • matched skills - • missing skills - -👉 Goes beyond keyword matching → understands semantic similarity - -⸻ - -🔹 4.2 Learning Ability Predictor (USP) - -HireSense predicts: - -“How fast can this candidate learn a required skill?” - -⸻ - -🧩 Transfer Graph -A structured mapping of skill relationships: - • Python → Flask, FastAPI - • JavaScript → React, Node - • Docker → Kubernetes - -⸻ - -⏱️ Learning Estimation -For each missing skill: - • check if prerequisite exists - • estimate learning time - -⸻ - -⚡ Learning Speed Modifier -Based on: - • GitHub consistency - • problem-solving ability - • recent activity - • experience - -👉 Produces: - • Fast / Medium / Slow learner classification - • time estimates (e.g., 1–3 weeks) - -⸻ - -🔹 4.3 Explainability Layer - -Every score includes: - • contributing factors - • reasoning explanation - -👉 No black-box decisions - -⸻ - -🚨 Advanced Differentiators (WOW Features) - -⸻ - -🔍 Resume Inflation Detector (🔥 Key Highlight) - -Compares: - • claimed skills (resume) -vs - • actual activity (GitHub, LeetCode) - -⸻ - -Output: - • credibility score per skill - • flags like: - • “Claims React expertise but no GitHub evidence” - • “Inactive for 2+ years” - -⸻ - -💥 Why this is powerful: - • solves a real hiring pain point - • highly demo-friendly - • immediately intuitive - -⸻ - -📈 Candidate Trajectory Score - -Analyzes growth trends over time. - -⸻ - -Signals: - • increasing commit frequency - • transition to complex projects - • learning new technologies - -⸻ - -Insight: - • identifies high-potential candidates - • favors growth over static skill level - -⸻ - -🧑‍🤝‍🧑 Team Culture Fit Heuristic - -Infers working style from GitHub behavior. - -⸻ - -Behavioral Indicators: - • commit message quality → communication discipline - • issue usage → structured thinking - • documentation → clarity - • open-source contributions → collaboration - -⸻ - -Output: - • Independent vs Collaborative - • Structured vs Chaotic - • Communicative vs Silent - -⸻ - -👉 Compared with team profile → culture compatibility score - -⸻ - -💰 Salary Benchmarking Layer - -Estimates compensation range. - -⸻ - -Based on: - • skills - • experience - • role - • market data - -⸻ - -Output: - • salary range (e.g., ₹18–26 LPA) - • hiring cost estimation - -⸻ - -👉 Converts decision into a business insight - -⸻ - -🎯 AI Interviewer (Demo Showstopper) - -Generates custom interview questions. - -⸻ - -Based on: - • candidate weaknesses - • missing skills - • role requirements - -⸻ - -Example: - • “Candidate shows low Kubernetes evidence — ask scenario-based k8s question” - -⸻ - -👉 Helps: - • interviewers - • technical screening - -⸻ - -🏢 Bonus — Internal Skill Gap Analyzer - -⸻ - -🧠 Problem - -Startups don’t know: - • what skills they lack - • who they should hire - -⸻ - -⚙️ Functionality - -Input: - • team skills - • project requirements - -⸻ - -🔍 Output: - -📊 Coverage Score - • % of required skills already available - -⚠️ Skill Gaps - • missing capabilities - -🧩 Domain Clustering -Groups gaps into: - • DevOps - • Frontend - • ML - • Backend - -⸻ - -📋 Hire Plan - -Example: - • “Hire 1 DevOps Engineer (Docker, Kubernetes)” - • urgency levels - -⸻ - -📝 JD Auto Generator - -Automatically creates: - • job descriptions - • role responsibilities - • required skills - -⸻ - -👉 Ready to post directly on hiring platforms - -⸻ - -🖥️ User Experience Flow - -⸻ - -👤 Candidate Analysis - 1. Upload resume - 2. System fetches GitHub/LeetCode - 3. Runs analysis - 4. Displays: - • match score - • learning ability - • credibility - • explanations - -⸻ - -🏢 Team Analysis - 1. Input team + project - 2. View: - • coverage - • gaps - • hire plan - 3. Generate job descriptions - -⸻ - -🛡️ Responsible AI Layer - -⸻ - -Key Principles: - • ❗ Not a final decision-maker - • ❗ Only a recommendation system - • ❗ Human review required - -⸻ - -Safeguards: - • confidence score - • bias reduction (ignore: - • college - • gender - • personal info) - • explainability for every output - • low-confidence warnings - -⸻ - -🚀 Why This Project Stands Out - -⸻ - -💥 Technical Strength - • multi-source data fusion - • feature engineering - • hybrid ML + rule-based reasoning - -⸻ - -🎯 Real-World Impact - • solves real hiring inefficiencies - • usable by startups immediately - -⸻ - -🧠 Innovation - • learning ability prediction - • resume authenticity detection - • trajectory-based evaluation - -⸻ - -🎥 Demo Power - • upload resume → instant analysis - • real GitHub insights - • interactive dashboard - • JD generation - -⸻ - -🏆 Final Positioning - -HireSense AI is not just a hiring tool. -It is a decision intelligence platform for startups. \ No newline at end of file diff --git a/mds hi mds/2.md b/mds hi mds/2.md deleted file mode 100644 index 57546533eea439227b5568bf71163d02392858b0..0000000000000000000000000000000000000000 --- a/mds hi mds/2.md +++ /dev/null @@ -1,24 +0,0 @@ -fastapi - -frontend keep plain html css js for now -for the candidate side we are going to use api because that data is open source and nothing is confedential - -for the internal team one we are going to either use local running ai for confidentiallity of conpany stuff - -sqlite database - - -for github api whatever is better i am fine with both - -for leetcode use graphql endpoint - -for salary Add a lightweight layer that tells you what it'll cost. Pull from public salary APIs (Levels.fyi has a public dataset, so does the GitHub Jobs archive) and, given the candidate's skill match score + years of experience + location, output a market salary range. For the team gap analyser, this means the hire plan output includes estimated budget impact — "hiring a DevOps engineer for your team will cost approximately ₹18–26 LPA in Bangalore." That turns a recommendation into a business case, which is what a CTO actually needs. - - -currently just do v1.0 but add the internal skill gap analyzer to v1.0 - - -local for now as we have to showcase in a hackathon - - -this is a hackathon project but make it kind of like a production startup tool \ No newline at end of file