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