ulgerang/tutor-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: bootstrap tutor planning

Browse Source
This commit is contained in:
user
2026-04-26 15:35:26 +09:00
commit 9edaddd092
25 changed files with 2205 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
openspec/changes/bootstrap-job-tutor-platform/design.md Normal file
View File

@@ -0,0 +1,74 @@
# Design
## Product Boundary
The first user is a software job seeker. The product should begin with
technical interview preparation because it gives clear task loops:
- ask a question
- receive an answer
- grade against a rubric
- ask follow-ups
- extract memory
- recommend review
- show progress and next challenge
General students remain a future expansion path, but the first requirements
should not be diluted by full K-12 scope.
## Architecture Boundary
Use a Go backend as the product service boundary. Internalize `agent-farm-go`
workflow patterns and contracts inside that backend boundary while keeping agent
behavior configuration-first where possible. Use `third-one` as the LLM
execution kernel with `deepseek-v4-flash` as the default configured model
target.
The product backend owns durable user, learner, memory, ontology, and asset
records. External memory or graph projects may inform design or become adapters,
but they should not own product privacy or tenant semantics.
## Memory Boundary
The platform should not model memory as a flat RAG corpus. It should keep
structured learning state:
- learner profile
- concept mastery
- misconception
- evidence
- intervention
- review schedule
Every durable memory update must include evidence so the product can explain why
it believes a learner is weak or strong on a concept.
## Ontology Boundary
Uploaded materials should become source-backed learning graphs. Inferred gaps
and generated explanations are candidates until reviewed or otherwise validated.
## Visual Asset Boundary
Image generation should support diagrams and slide-like learning slices, but the
asset pipeline must preserve prompt lineage, source concept links, and review
state. The desired image provider key is `gpt-image-v2`, but production
implementation must verify the current OpenAI API model name before wiring.
## Gamification Boundary
Use game-design principles to create healthy persistence: adaptive challenge,
visible growth, clear goals, strong session endings, and long-term readiness
progress. Do not optimize for compulsion alone. Random rewards, punitive streaks,
and shame-based leaderboards are out of scope for the first product baseline.
The initial learning loop is:
- readiness goal
- interview question
- answer
- rubric feedback
- follow-up or correction
- memory update
- visible progress
- next best challenge

44
openspec/changes/bootstrap-job-tutor-platform/proposal.md Normal file
View File

@@ -0,0 +1,44 @@
# Bootstrap Job Tutor Platform
## Summary
Create the first product baseline for a web-based AI tutor aimed at software job
seekers. The platform uses workflow-driven technical interview practice,
structured learner memory, and source-backed ontology building from uploaded
learning materials.
## Why
Software job seekers need adaptive practice and evidence-backed feedback more
than another generic interview-question list. A narrow first audience lets the
platform prove diagnosis, tutoring, memory extraction, and review planning
before expanding to broader student use cases.
## Motivation
The first product target should be narrow enough to build and evaluate:
developers preparing for technical interviews. This target naturally exercises
adaptive questioning, answer grading, misconception tracking, review planning,
and material-to-curriculum transformation. The same foundation can later expand
to general students.
## Scope
- Define the job-seeker-first product direction.
- Define learner memory requirements.
- Define ontology ingestion and gap-detection requirements.
- Define workflow boundaries for `agent-farm-go` and `third-one`.
- Define generated visual teaching asset requirements.
## Non-Goals
- Implement the full web service in this change.
- Replace a school LMS.
- Build a marketplace or certification product.
- Treat generated ontology content as canonical without review.
## Impact
This establishes the planning baseline for future implementation. Future code
changes should trace back to these specs and keep OpenSpec updated as the
product shape evolves.

52
openspec/changes/bootstrap-job-tutor-platform/specs/engineering-quality/spec.md Normal file
View File

@@ -0,0 +1,52 @@
# engineering-quality Specification
## ADDED Requirements
### Requirement: Implementation follows bounded file-size and design principles
The system SHALL be implemented with bounded file sizes and pragmatic SOLID,
KISS, and YAGNI principles.
#### Scenario: backend source is Go by default
- **GIVEN** a developer adds backend service code
- **WHEN** no explicit OpenSpec change revisits the stack
- **THEN** the backend code is implemented in Go
- **AND** workflow integration uses typed Go boundaries.
#### Scenario: source files stay under the manual file-size limit
- **GIVEN** a developer adds or modifies manually authored source code
- **WHEN** the change is ready for review
- **THEN** no manually authored source file exceeds 600 lines
- **AND** files approaching the limit are split by responsibility.
#### Scenario: domain responsibilities remain separated
- **GIVEN** a feature touches interview grading, learner memory, ontology,
progression, or generated assets
- **WHEN** the implementation is designed
- **THEN** each responsibility remains in a cohesive module or service
- **AND** provider SDKs, storage adapters, and workflow calls do not leak into
unrelated domain logic.
#### Scenario: speculative abstractions are deferred
- **GIVEN** a future feature might need a generic framework, plugin system,
queue, or provider abstraction
- **WHEN** the current MVP slice does not require it
- **THEN** the implementation defers that abstraction
- **AND** uses the simplest design that satisfies the current OpenSpec
requirement.
### Requirement: Workflow state changes use typed contracts
The system SHALL prefer typed contracts for workflow inputs and outputs that
change product state.
#### Scenario: grading output updates learner state
- **GIVEN** a tutor workflow grades a user's answer
- **WHEN** the result can affect memory, readiness, or next challenge selection
- **THEN** the workflow returns a typed result
- **AND** the product state update does not depend on parsing freeform prose.

37
openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md Normal file
View File

@@ -0,0 +1,37 @@
# job-seeker-tutor Specification
## ADDED Requirements
### Requirement: Job seeker interview preparation is the first product target
The system SHALL prioritize software job seekers as the first product audience
while preserving an architecture that can later support general students.
#### Scenario: diagnostic session creates an initial study map
- **GIVEN** a user chooses a target software role and technology stack
- **WHEN** the user starts a diagnostic interview
- **THEN** the system asks role-relevant technical questions
- **AND** grades the user's answers against explicit rubrics
- **AND** creates an initial concept weakness map.
#### Scenario: practice session adapts to weak answers
- **GIVEN** a user answers an interview question weakly or incorrectly
- **WHEN** the tutoring workflow evaluates the answer
- **THEN** the system asks a targeted follow-up question or gives a corrective
explanation
- **AND** records the evidence used for that decision.
### Requirement: Review plans are based on learner evidence
The system SHALL generate review plans from graded answers, concept mastery, and
misconception evidence rather than generic topic lists.
#### Scenario: session produces next actions
- **GIVEN** a completed tutoring session
- **WHEN** the review-plan workflow runs
- **THEN** the user receives prioritized concepts, practice questions, and
review timing
- **AND** each recommendation links back to learning evidence.

33
openspec/changes/bootstrap-job-tutor-platform/specs/learner-memory/spec.md Normal file
View File

@@ -0,0 +1,33 @@
# learner-memory Specification
## ADDED Requirements
### Requirement: Durable learner memory is structured and evidence-backed
The system SHALL store durable learner memory as structured learning state
rather than an untyped RAG transcript.
#### Scenario: answer grading updates concept mastery
- **GIVEN** a user answers a technical interview question
- **WHEN** the answer is graded
- **THEN** the system may update concept mastery
- **AND** the update includes the original answer or grading evidence.
#### Scenario: repeated mistakes become misconceptions
- **GIVEN** the same reasoning error appears across multiple answers
- **WHEN** the memory extraction workflow runs
- **THEN** the system records or strengthens a misconception entry
- **AND** links it to the supporting answers.
### Requirement: Temporary context does not become durable truth automatically
The system SHALL separate session context from durable learner memory.
#### Scenario: inferred memory requires evidence
- **GIVEN** a tutor infers that a learner may misunderstand a concept
- **WHEN** the inference lacks enough evidence
- **THEN** the system records it as tentative or ignores it
- **AND** does not promote it to durable mastery state as confirmed truth.

34
openspec/changes/bootstrap-job-tutor-platform/specs/learning-ontology/spec.md Normal file
View File

@@ -0,0 +1,34 @@
# learning-ontology Specification
## ADDED Requirements
### Requirement: Uploaded materials produce a source-backed ontology
The system SHALL analyze uploaded learning materials into concepts,
prerequisites, examples, questions, rubrics, and source evidence.
#### Scenario: material ingestion creates ontology candidates
- **GIVEN** an operator uploads learning materials
- **WHEN** the ingestion workflow completes
- **THEN** the system creates ontology candidate nodes and edges
- **AND** links each supported candidate to source evidence.
#### Scenario: gaps are identified separately from verified content
- **GIVEN** the ontology builder detects a missing prerequisite or weakly
supported concept
- **WHEN** it proposes missing content
- **THEN** the proposed content is marked as generated or inferred
- **AND** it is not treated as canonical until reviewed or validated.
### Requirement: Generated study assets keep lineage
The system SHALL preserve provenance for generated learning materials.
#### Scenario: visual teaching asset is generated
- **GIVEN** a concept needs a diagram or slide-like explanation
- **WHEN** the asset generation workflow runs
- **THEN** the generated asset stores its prompt, model configuration, source
concept, source evidence, and review state.

63
openspec/changes/bootstrap-job-tutor-platform/specs/learning-progression/spec.md Normal file
View File

@@ -0,0 +1,63 @@
# learning-progression Specification
## ADDED Requirements
### Requirement: Learning progression is evidence-backed and game-inspired
The system SHALL use game-inspired progression loops to make study sessions
rewarding while tying progress to learning evidence.
#### Scenario: session loop ends with visible progress
- **GIVEN** a user completes an interview-practice loop
- **WHEN** the system grades the answer and extracts memory
- **THEN** the user sees what improved, what remains weak, and the next
recommended challenge
- **AND** any progress shown is linked to grading or memory evidence.
#### Scenario: adaptive challenge stays near learner ability
- **GIVEN** the learner repeatedly fails a concept at the current difficulty
- **WHEN** the next challenge is selected
- **THEN** the system lowers difficulty, changes explanation strategy, or inserts
a recovery question
- **AND** does not simply continue escalating difficulty.
### Requirement: Progression surfaces support interview readiness
The system SHALL expose progression surfaces that help job seekers understand
interview readiness.
#### Scenario: readiness map summarizes concept state
- **GIVEN** the learner has completed diagnostic or practice sessions
- **WHEN** the readiness map is displayed
- **THEN** each concept has a readiness state
- **AND** the state can be traced to answer evidence, misconception evidence, or
review completion.
#### Scenario: boss question unlocks after prerequisite stability
- **GIVEN** a cluster of prerequisite concepts is stable enough
- **WHEN** the user reaches the next milestone
- **THEN** the system may unlock an integrated boss-style interview question
- **AND** the question combines multiple concepts under realistic constraints.
### Requirement: Engagement mechanics avoid exploitative patterns
The system SHALL avoid engagement mechanics that encourage unhealthy compulsion
or shame.
#### Scenario: streaks do not punish missed days
- **GIVEN** a user misses a scheduled practice day
- **WHEN** the user returns
- **THEN** the system helps the user resume with a recovery plan
- **AND** does not erase durable learning progress.
#### Scenario: rewards are connected to learning value
- **GIVEN** the system awards progress, badges, unlocks, or generated assets
- **WHEN** the reward is shown
- **THEN** it reflects mastery, effort, review completion, or interview readiness
- **AND** is not primarily a gambling-like random reward.

49
openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md Normal file
View File

@@ -0,0 +1,49 @@
# tutor-workflows Specification
## ADDED Requirements
### Requirement: Tutor behavior is workflow-driven
The system SHALL express core tutor behavior as configurable workflows using
`agent-farm-go` patterns internalized behind the Go backend boundary, with
`third-one` as the LLM execution kernel.
#### Scenario: grading workflow emits typed output
- **GIVEN** a user answer and grading rubric
- **WHEN** the grading workflow runs
- **THEN** it emits a typed grading result
- **AND** includes correctness, depth, communication clarity, evidence, and
follow-up recommendation fields.
#### Scenario: memory extraction workflow emits typed candidates
- **GIVEN** a graded interview answer
- **WHEN** the memory extraction workflow runs
- **THEN** it emits memory update candidates
- **AND** each candidate identifies its evidence and confidence.
### Requirement: Default LLM runtime is configurable
The system SHALL keep the LLM model target configurable while defaulting the
initial planning baseline to `deepseek-v4-flash`.
#### Scenario: workflow invokes the default model
- **GIVEN** no product override is configured
- **WHEN** a tutor workflow invokes the LLM kernel
- **THEN** the workflow uses the configured `deepseek-v4-flash` runtime target.
### Requirement: Backend stack is Go
The system SHALL use Go for the backend service so workflow orchestration,
typed contracts, and learner state updates share one strongly typed service
boundary.
#### Scenario: workflow calls cross typed backend interfaces
- **GIVEN** an API handler needs diagnostic, grading, memory extraction, or next
challenge behavior
- **WHEN** it invokes the workflow layer
- **THEN** it calls a typed Go interface
- **AND** does not mutate product state by parsing freeform shell output.

14
openspec/changes/bootstrap-job-tutor-platform/tasks.md Normal file
View File

@@ -0,0 +1,14 @@
# Tasks
- [x] 1. Create initial PRD for job-seeker-first tutoring.
- [x] 2. Create initial architecture note for workflow, LLM, memory, ontology,
and visual assets.
- [x] 3. Add OpenSpec capability specs for the first product baseline.
- [x] 4. Incorporate game-design learning loop and progression planning.
- [x] 5. Add repository engineering principles and code-size constraints.
- [x] 6. Lock Go backend and internalized agent-farm workflow direction.
- [ ] 7. Choose the first interview track and canonical concept seed list.
- [ ] 8. Define typed JSON contracts for diagnostic, grading, memory extraction,
ontology gap detection, and asset prompt generation.
- [ ] 9. Draft the first `agent-farm-go` YAML workflow package.
- [x] 10. Validate the OpenSpec change.