tutor-service/.planning/phases/002-diagnostic-interview-loop/002-CONTEXT.md

Phase 2: Diagnostic Interview Loop - Context

Gathered: 2026-04-26 Status: Ready for planning Source: GSD continuation after Phase 1 completion

## Phase Boundary

Phase 2 proves the first job-seeker loop from target role/stack selection through a graded diagnostic answer. It should create a thin backend product surface for diagnostic sessions while avoiding persistent storage and real LLM calls until later phases require them.

## Implementation Decisions

Persistence

• Use an in-memory session store in Phase 2.
• Do not add a database or migrations yet.
• Persisting original answers and grading evidence means preserving them inside the in-memory diagnostic session record for this phase.

Interview Track

• Use the Backend Developer Interview track from docs/planning/INTERVIEW_TRACKS.md.
• Seed questions should cover the canonical concept clusters, starting with a small representative set.

Workflow Boundary

• Grading must go through the typed workflows.Runner interface.
• The default implementation can remain deterministic/stubbed, but it must return typed GradedAnswer data rather than freeform prose.
• HTTP handlers must not shell out or parse arbitrary assistant text.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Product and Track

• docs/planning/PRD.md - diagnostic interview product flow.
• docs/planning/INTERVIEW_TRACKS.md - first track and concept seed list.
• docs/planning/WORKFLOW_CONTRACTS.md - typed workflow result shape.

Engineering and Requirements

• docs/planning/ENGINEERING.md - 600-line, SOLID, KISS, YAGNI constraints.
• .planning/REQUIREMENTS.md - INT-01 through INT-06 requirements.
• .planning/ROADMAP.md - Phase 2 goal and success criteria.
• openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md
  • diagnostic and first-track requirements.
• openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md
  • typed workflow requirements.

</canonical_refs>

## Specific Ideas

• Add internal/interview for sessions, questions, answers, and in-memory store.
• Add endpoints:
  • POST /api/v1/diagnostic-sessions
  • GET /api/v1/diagnostic-sessions/{id}
  • POST /api/v1/diagnostic-sessions/{id}/answers
• Keep routing simple with standard library http.ServeMux.
• Add deterministic grading in the workflow stub so tests can prove typed evidence is recorded.

## Deferred Ideas

• Real third-one grading execution.
• Database persistence.
• Authentication and user identity provider integration.
• Memory extraction and durable learner memory.
• Frontend UI.

---

Phase: 002-diagnostic-interview-loop Context gathered: 2026-04-26