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

• 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.

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.