From 320f1e44407c0fb86f23d30bb31646c8b4ee2532 Mon Sep 17 00:00:00 2001 From: ameer Date: Sat, 2 May 2026 02:52:43 +0800 Subject: [PATCH] Add codex implementation brief --- CODEX_PROMPT.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 CODEX_PROMPT.md diff --git a/CODEX_PROMPT.md b/CODEX_PROMPT.md new file mode 100644 index 0000000..ac4b22e --- /dev/null +++ b/CODEX_PROMPT.md @@ -0,0 +1,55 @@ +# Codex implementation brief — Live In-Lecture Quiz Portal + +You are implementing a complete, production-quality web application from a detailed specification. The user (Prof. Ameer H. Khan) wants to use this for an in-lecture engagement quiz with his students next week. + +## Required reading +**Read `SPEC.md` in full before writing any code.** It is the authoritative specification. Sections 1-18 cover everything: routes, data model, state machine, WebSocket protocol, frontend pages, security, project layout, and acceptance criteria. Implement exactly what the spec says. + +## Working directory +You are at `/home/ameer/RD/Projects/Apps/quiz/`. This is your workspace root. The spec, a baseline git commit, and `.git/` are already in place. + +## Your responsibilities, end-to-end + +1. **Implement** the full application per `SPEC.md` — backend (FastAPI + websockets + aiosqlite), frontend (vanilla HTML/CSS/JS), data model, scoring, state machine, all routes. +2. **Set up** the project structure exactly as specified in §12 (`pyproject.toml`, `.env.example`, `.gitignore`, `app/`, `static/`, `tests/`, `examples/`). +3. **Author** an example question pool at `examples/week9_pool.json` with 10 plausible MCQs about Computer Organization Week 9 recap topics (CPU structure, multi-cycle datapath, hardwired control unit, FSM, microprogrammed control, hardwired vs microprogrammed tradeoffs). It is fine to generate plausible technical content; the user will replace with his real questions later. +4. **Write tests** as listed in §14 — unit, API, WebSocket, edge-case, and the load-simulation test. +5. **Run tests iteratively** until all pass: `pytest -q` green, `pytest --cov=app` at least 80% line coverage on `app/`. Fix bugs as they surface. Iterate until clean. +6. **Smoke test** by starting `uvicorn app.main:app` with a test `.env`, verify it boots without errors and `GET /healthz` responds. +7. **Document** in `README.md` (install + run + test + manual smoke test) and `NOTES.md` (any non-obvious choices or deviations from the spec, per §17). +8. **Commit incrementally** to git as you go — separate commits for "scaffold project", "data model + db", "scoring + pool validation", "auth + cookies", "student API + WS", "admin API + WS", "frontend student", "frontend admin", "tests", "fixes from test runs". This makes the human review tractable. + +## Operational rules + +- **Use `python3.11` or newer** (system has `python3` available; check version; if <3.11, document fallback in NOTES). +- **Create a `.venv`** inside the project dir, install deps via `pip install -e '.[dev]'`. Do NOT use conda or shared envs. +- **Pin dependencies** with compatible-release operators (e.g. `fastapi~=0.115`). +- **Do not** invent new features beyond the spec. Where the spec is silent, pick the simplest reasonable option and document in `NOTES.md`. +- **Do not** add Docker, systemd, Caddy, DNS, or any deployment config. §15 explicitly defers these to the human. +- **Do not** commit `.env`, `quiz.db`, `__pycache__`, or `.venv` (`.gitignore` handles this). +- **Do not** add em-dashes (`—` or `---`) in user-visible text (frontend strings, README, error messages). Use commas, semicolons, periods, parens, or colons. (User preference; internal scratch is unconstrained.) + +## When you are done + +Write a final summary to `IMPLEMENTATION_REPORT.md` in the project root covering: +- What was built (file inventory + LoC counts). +- Test results: full `pytest -q` output, coverage percentage. +- Any deviations from the spec (with rationale). +- How to run locally (3-5 lines of shell). +- Any open issues, known bugs, or things you noticed but couldn't fix. +- Anything you'd recommend the human review carefully. + +Then stop. Do not deploy, do not push to remote, do not modify anything outside `/home/ameer/RD/Projects/Apps/quiz/`. + +## Acceptance bar + +The implementation is acceptable when: +- All test categories from SPEC §14 are present. +- `pytest -q` is fully green. +- Line coverage on `app/` is ≥ 80%. +- The load simulation test passes with 50 simulated students. +- `uvicorn app.main:app` boots without errors. +- `README.md` and `NOTES.md` are present and informative. +- Git history shows incremental commits. + +If you hit a blocker you genuinely cannot resolve, document it clearly in `IMPLEMENTATION_REPORT.md` under "Open issues" and continue with the rest of the work; do not halt the whole job for a single recoverable issue.