tutor-service/.planning/REQUIREMENTS.md

# Requirements: Tutor Platform

**Defined:** 2026-04-26
**Core Value:** The user should feel and prove that they are becoming more
interview-ready after each short practice loop.

## v1 Requirements

### Backend and Workflow

- [x] **BACK-01**: Backend service is implemented in Go.
- [x] **BACK-02**: Backend exposes typed interfaces for tutor workflows.
- [x] **BACK-03**: Backend integrates internalized `agent-farm-go` workflow
  patterns without ad hoc handler shellouts.
- [x] **BACK-04**: Workflow LLM execution uses `third-one` with configurable
  runtime and default `deepseek-v4-flash`.
- [x] **BACK-05**: Manually authored source files stay at or below 600 lines.

### Interview Practice

- [x] **INT-01**: User can select target role, stack, and interview timeline.
- [x] **INT-02**: User can complete a diagnostic technical interview.
- [x] **INT-03**: System can generate role-specific interview questions.
- [x] **INT-04**: System can grade user answers against explicit rubrics.
- [x] **INT-05**: System can ask targeted follow-up questions for weak answers.
- [x] **INT-06**: System preserves original answers and grading evidence.

### Learner Memory

- [x] **MEM-01**: System stores learner profile with role, stack, timeline, and
  preferences.
- [x] **MEM-02**: System stores concept mastery states with evidence.
- [x] **MEM-03**: System stores recurring misconceptions with supporting
  answers.
- [x] **MEM-04**: System stores intervention history and review schedule.
- [x] **MEM-05**: Temporary session context does not become durable memory
  without evidence.

### Progression

- [x] **PROG-01**: User can see a role-specific readiness map.
- [x] **PROG-02**: Concepts have challenge ladders from definition to interview
  pressure.
- [x] **PROG-03**: System selects next challenge based on learner memory and
  grading evidence.
- [x] **PROG-04**: System unlocks boss-style integrated questions after
  prerequisite stability.
- [x] **PROG-05**: Streaks and rewards avoid punitive or gambling-like mechanics.

### Ontology and Learning Materials

- [ ] **ONTO-01**: User or operator can upload learning materials.
- [ ] **ONTO-02**: System creates source-backed ontology candidate nodes and
  edges.
- [ ] **ONTO-03**: System detects missing prerequisites and weakly supported
  concepts.
- [ ] **ONTO-04**: Generated or inferred content is marked as candidate until
  reviewed.

### Teaching Assets

- [ ] **ASSET-01**: System can generate prompt candidates for visual teaching
  assets.
- [ ] **ASSET-02**: Generated assets store source concept, evidence, prompt,
  model config, and review state.
- [ ] **ASSET-03**: Image model configuration verifies the actual OpenAI model
  identifier before production calls.

## v2 Requirements

### General Student Expansion

- **GEN-01**: Support non-interview learning tracks.
- **GEN-02**: Support teacher or parent progress summaries.
- **GEN-03**: Support school or organization tenant policies.

### Advanced Content Operations

- **ADV-01**: Human review workflow for promoted ontology content.
- **ADV-02**: Multi-format teaching material generation beyond static images.
- **ADV-03**: Company-specific or role-specific premium interview campaigns.

## Out of Scope

| Feature | Reason |
|---------|--------|
| Full LMS | Too broad for v1; first validate job-seeker loop |
| Hiring decisions | Product gives practice/readiness, not employment judgment |
| Course marketplace | Not needed for core value |
| Social leaderboards | Risk of shame mechanics and weak learning signal |
| Random reward economy | Misaligned with evidence-backed learning |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| BACK-01..BACK-05 | Phase 1 | Complete |
| INT-01..INT-06 | Phase 2 | Complete |
| MEM-01..MEM-05 | Phase 3 | Complete |
| PROG-01..PROG-05 | Phase 4 | Complete |
| ONTO-01..ONTO-04 | Phase 5 | Pending |
| ASSET-01..ASSET-03 | Phase 6 | Pending |

**Coverage:**
- v1 requirements: 28 total
- Mapped to phases: 28
- Unmapped: 0

---
*Requirements defined: 2026-04-26*
*Last updated: 2026-04-26 after Phase 4 execution.*