docs: bootstrap tutor planning
This commit is contained in:
user
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user