129 lines
5.5 KiB
Markdown
129 lines
5.5 KiB
Markdown
<!--
|
|
SYNC IMPACT REPORT
|
|
==================
|
|
Version change: (unset) → 1.0.0
|
|
New file: first ratification, all placeholders filled.
|
|
|
|
Modified principles: N/A (initial ratification)
|
|
|
|
Added sections:
|
|
- Core Principles (5 principles)
|
|
- Technology Constraints
|
|
- Development Workflow
|
|
- Governance
|
|
|
|
Templates reviewed:
|
|
- .specify/templates/plan-template.md ✅ compatible (no amendments needed)
|
|
- .specify/templates/spec-template.md ✅ compatible (no amendments needed)
|
|
- .specify/templates/tasks-template.md ✅ compatible (no amendments needed)
|
|
|
|
Deferred TODOs:
|
|
- TODO(RATIFICATION_DATE): exact project start date unknown; using today (2026-03-31) as ratification date.
|
|
-->
|
|
|
|
# AI Teacher Constitution
|
|
|
|
## Core Principles
|
|
|
|
### I. Keep It Simple Stupid (KISS)
|
|
|
|
Every design and implementation decision MUST default to the simplest viable option.
|
|
Complexity MUST be explicitly justified against a concrete, present need — not a hypothetical
|
|
future requirement. Gold-plating, speculative abstractions, and premature optimization are
|
|
non-compliant.
|
|
|
|
**Rules:**
|
|
- A feature MUST NOT be split into multiple layers/services unless a single layer is demonstrably insufficient.
|
|
- Dependencies MUST be chosen for their simplicity, not their feature count.
|
|
- If two approaches solve the problem equally well, the shorter one wins.
|
|
|
|
**Rationale**: This is a POC. Speed of learning and iteration matters more than architectural
|
|
elegance. Complexity kills POCs.
|
|
|
|
### II. Easy to Change
|
|
|
|
Code MUST be written with future modification in mind. High coupling between unrelated modules
|
|
is non-compliant.
|
|
|
|
**Rules:**
|
|
- Modules MUST communicate through clearly defined interfaces; internal implementation details
|
|
MUST NOT leak across boundaries.
|
|
- Hardcoded values MUST be extracted to configuration at the boundary where they are consumed.
|
|
- A feature's core logic MUST be separable from its delivery mechanism (HTTP handler, CLI, etc.)
|
|
without full rewrites.
|
|
|
|
**Rationale**: A POC that cannot pivot cheaply is a dead end. Changeability is the primary
|
|
competitive advantage of early-stage software.
|
|
|
|
### III. Web-First Architecture
|
|
|
|
The project is a web application. All architectural decisions MUST assume an HTTP
|
|
request/response model as the primary interface.
|
|
|
|
**Rules:**
|
|
- The backend MUST expose a REST (or equivalent HTTP) API as its public contract.
|
|
- The frontend MUST be a standalone client that communicates solely through the API;
|
|
server-side rendering of business logic is non-compliant.
|
|
- API contracts MUST be versioned at the URL path level (`/api/v1/...`) from day one.
|
|
|
|
**Rationale**: Maintaining a clean client/server split allows each side to evolve independently,
|
|
which is critical for a project that is expected to change frequently.
|
|
|
|
### IV. Documentation as Architecture
|
|
|
|
The README.md MUST contain a living architecture overview using Mermaid diagrams. Diagrams MUST
|
|
be updated whenever the architecture changes; outdated diagrams are a compliance violation.
|
|
|
|
**Rules:**
|
|
- At minimum, a system-context diagram (components and their relationships) MUST exist in README.md.
|
|
- Each major subsystem added to the project MUST be reflected in the README diagram within the
|
|
same PR that introduces it.
|
|
- Diagrams MUST use the `mermaid` fenced code block syntax so they render natively on GitHub/GitLab.
|
|
|
|
**Rationale**: For a POC with a small team, the README is the primary onboarding document.
|
|
Keeping diagrams co-located with code prevents documentation rot.
|
|
|
|
|
|
## Technology Constraints
|
|
|
|
- **Project type**: Web application (backend API + frontend client).
|
|
- **Structure**: `backend/` and `frontend/` at repository root (Option 2 in plan template).
|
|
- **Complexity ceiling**: Maximum two deployable units (one backend, one frontend) unless
|
|
a concrete scaling need is demonstrated and documented.
|
|
- **External services**: MUST be wrapped behind an interface so they can be swapped without
|
|
cascading changes.
|
|
- **Database**: A single relational or document store is sufficient for the POC; no distributed
|
|
storage without explicit justification.
|
|
|
|
## Development Workflow
|
|
|
|
- Branch strategy: feature branches off `main`; short-lived (merge within one week).
|
|
- PR size: SHOULD be small enough to review in under 30 minutes; large PRs MUST be split.
|
|
- README MUST be updated in the same PR as any architectural change (Principle IV).
|
|
- The `Complexity Tracking` table in the plan template MUST be filled whenever a Principle I
|
|
or II violation is introduced.
|
|
- No performance optimization pass before the first working end-to-end prototype is validated
|
|
(Principle V gate).
|
|
|
|
## Governance
|
|
|
|
This constitution supersedes all informal conventions. Amendments MUST be proposed as a PR
|
|
that updates this file with an incremented version number and updated `LAST_AMENDED_DATE`.
|
|
|
|
**Amendment procedure:**
|
|
1. Open a PR with the proposed changes to this file.
|
|
2. The PR description MUST state which principle is affected and why the change is needed.
|
|
3. Merge after at least one reviewer approves.
|
|
4. All open feature branches MUST be rebased onto the updated `main` within 48 hours of merge.
|
|
|
|
**Versioning policy (semantic):**
|
|
- MAJOR: Removal or redefinition of an existing principle.
|
|
- MINOR: Addition of a new principle or section.
|
|
- PATCH: Clarifications, wording, or typo fixes.
|
|
|
|
**Compliance review**: Every PR review MUST include a check against the Constitution Check
|
|
section in the plan template. Non-compliant complexity MUST be logged in the Complexity
|
|
Tracking table before merge.
|
|
|
|
**Version**: 1.0.0 | **Ratified**: 2026-03-31 | **Last Amended**: 2026-03-31
|