tutor-service/.planning/PROJECT.md

# Tutor Platform

## What This Is

Tutor Platform is a web service for software job seekers preparing for
technical interviews. It combines adaptive interview practice, evidence-backed
learner memory, source-backed learning ontology, and game-inspired progression
to make interview readiness visible and repeatable.

The backend is Go because the product will internalize `agent-farm-go` workflow
patterns and call `third-one` with `deepseek-v4-flash` through typed service
boundaries.

## Core Value

The user should feel and prove that they are becoming more interview-ready after
each short practice loop.

## Requirements

### Validated

(None yet; ship to validate.)

### Active

- [ ] Developer job seekers can complete a diagnostic technical interview.
- [ ] Answers are graded with rubrics and preserved as evidence.
- [ ] Learner memory tracks concept mastery, misconceptions, evidence, and
  interventions.
- [ ] The system selects the next best interview challenge from learner state.
- [ ] The user sees a readiness map and meaningful progression after each loop.
- [ ] Uploaded learning materials can become source-backed ontology candidates.
- [ ] Generated learning assets preserve prompt, source, and review lineage.
- [ ] Backend implementation uses Go and keeps `agent-farm-go` workflow patterns
  internalized behind typed interfaces.

### Out of Scope

- Full school LMS replacement; the first product target is job seekers.
- Marketplace course publishing; not needed to prove the learning loop.
- Automatic certification or hiring decisions; readiness is advisory.
- Unreviewed generated canonical content; generated ontology and assets require
  provenance and review state.
- Gambling-like rewards or shame-based leaderboards; progression must be tied to
  learning evidence.

## Context

- Product planning lives in `docs/planning/`.
- OpenSpec change baseline lives in
  `openspec/changes/bootstrap-job-tutor-platform/`.
- The service should use a Go backend.
- Workflow behavior should be configuration-first and inspired by
  `agent-farm-go`.
- LLM execution should use `third-one`, defaulting to `deepseek-v4-flash`.
- The first interview track is Backend Developer Interview.
- Memory should be structured learner state, not a flat RAG transcript.
- Gamification should use Flow, adaptive difficulty, growth lines, and strong
  session endings without exploitative mechanics.

## Constraints

- **Backend stack**: Go, to align with internalized `agent-farm-go` workflow
  patterns.
- **File size**: manually authored source files must stay at or below 600 lines.
- **Design principles**: SOLID, KISS, and YAGNI govern implementation.
- **Workflow state**: product state changes should use typed contracts, not
  freeform prose parsing.
- **Privacy**: learner memory and evidence may become sensitive, especially for
  future student/school expansion.

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Start with software job seekers | Clear, testable interview-practice loop | Pending |
| Use Go backend | Aligns service with internalized `agent-farm-go` substrate | Pending |
| Use `third-one` and `deepseek-v4-flash` by default | Matches current local model/runtime direction | Pending |
| Structured learner memory, not RAG-first | Product value is learner modeling and readiness | Pending |
| Game-inspired progression must be evidence-backed | Creates retention without empty rewards | Pending |
| 600-line source limit | Forces responsibility boundaries early | Pending |
| Backend Developer Interview first track | Gives a broad but testable MVP concept set | Pending |

---
*Last updated: 2026-04-26 after first track and Phase 1 plan were set.*