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

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

### Active

- [ ] Job seekers can use the first web app without API tooling.
- [ ] The web app guides users through diagnostic practice and shows feedback.
- [ ] The web app shows learner memory, readiness, and next challenge after
  practice.
- [ ] Operators can ingest learning material and inspect ontology candidates.
- [ ] Operators can generate source-backed teaching asset prompt candidates.

## Current Milestone: v2 Frontend MVP

**Goal:** Turn the completed backend learning loop into a usable web service
experience for developer job seekers.

**Target features:**

- Web app shell served by the Go backend.
- Diagnostic interview practice UI.
- Learner memory, readiness map, and next challenge views.
- Material ingestion and ontology snapshot UI.
- Teaching asset prompt candidate UI.

### 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 |
| v2 frontend first | The backend loop is proven; the next risk is whether users can operate it as a web service | Active |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition**:

1. Requirements invalidated? Move to Out of Scope with reason.
2. Requirements validated? Move to Validated with phase reference.
3. New requirements emerged? Add to Active.
4. Decisions to log? Add to Key Decisions.
5. "What This Is" still accurate? Update if drifted.

**After each milestone**:

1. Full review of all sections.
2. Core Value check: still the right priority?
3. Audit Out of Scope: reasons still valid?
4. Update Context with current state.

---
*Last updated: 2026-04-26 after v2 Frontend MVP milestone start.*