2026-06-11 07:57:42lisa:
Build data-dictionary section easy to hard: small tables first
Tool 1 now opens with the two complete two-row tables (Criteria, Band
scale) reproduced verbatim, then an abbreviated four-row cut of the
student record (student, grades, indicator_scores, final) linking to
the full table on GitHub, before the existing §5 derived-values
punchline. Requested by Jeremy after review.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
sd/C05/From SRS to Detailed Designs - Data and Logic.md ..
@@ 42,7 42,38 @@
### Tool 1 — Data dictionary: a separate section for what is *not* stored
-
The data dictionary has a §4 for the **student record** (everything stored to disk) and a separate §5 for **derived values**. The heading is exact:
+
Before the big table, meet two **complete, small** ones. The real data dictionary opens with these — each just two rows, but already carrying the full six-column format (Field / Data type / Format / Description / Example / Validation). The column set itself is the teaching point: every field, however small, gets a type, a format, an example *and* a validation rule. Both tables verbatim:
+
+
> ## 1. Criteria (`CRITERIA`)
+
+
| Field | Data type | Format / range | Description | Example | Validation |
+
| --- | --- | --- | --- | --- | --- |
+
| `cid` | str | `C` + 2 digits, `C01`–`C10` | Criterion identifier; also keys the rubric filename | `C03` | Must have a matching `data/rubrics/<cid>-rubric.md` |
+
| `name` | str | ≤ 80 chars | Criterion title from the VCAA rubric heading | `Skills in documenting a software requirements specification` | Non-empty |
+
+
> ## 2. Band scale (`BANDS`, `BAND_LABELS`)
+
+
| Field | Data type | Format / range | Description | Example | Validation |
+
| --- | --- | --- | --- | --- | --- |
+
| `band` | str | `low-high`, 5 fixed values | Rubric band a score falls in: `1-2`, `3-4`, `5-6`, `7-8`, `9-10` | `7-8` | One of the 5 values |
+
| `band_label` | str | band + qualifier | Display label for evidence grids | `7-8 (high)` | Derived 1:1 from `band` |
+
+
That is a complete data dictionary in miniature — you can read it end to end in thirty seconds. Now you are ready for the real thing: §4, the **student record**, the shape that becomes one markdown file per student in Sprint 2. Here is an abbreviated cut — four rows chosen to show the variety the format can carry, each verbatim:
+
+
> ## 4. Student record (`MOCK_STUDENTS` → one markdown file per student in Sprint 2)
+
+
| Field | Data type | Format / range | Description | Example | Validation |
+
| --- | --- | --- | --- | --- | --- |
+
| `student` | str | ≤ 50 chars | Student name; keys the record and the leaderboard | `Cohen` | Unique within cohort; non-empty |
+
| `grades` | dict | keyed by `cid` | Grading record per criterion (absent = not graded yet) | `{"C03": {...}}` | Keys ∈ `CRITERIA` |
+
| `grades[cid].indicator_scores` | list[int \| None] | 0–10 whole numbers, one per indicator | Teacher's score per indicator | `[8, 7]` | Length ≤ indicator count; each 0–10 or empty |
+
| `grades[cid].final` | int \| None | 0–10 | Final criterion score after the teacher reconciles calculated vs AI vs cross-marker; never auto-filled | `8` | 0–10 or absent |
+
+
*… plus 10 more fields (evidence grids, AI score and evidence, cross-mark, reconciliation note, report comment and advice) — read the [full table on GitHub](https://github.com/vce-soft-dev/SD26-Students/blob/main/Proj-SAT-Grader-UI/C05/data-dictionary.md).*
+
+
Notice the variety those four rows carry: a simple string with a uniqueness rule (`student`), a dict keyed by criterion (`grades`), a list validated per item (`indicator_scores`), and a nullable int whose description states a *policy* — `final` is "never auto-filled". Same six columns every time.
+
+
So §§1–4 document everything **stored**. The punchline is what comes next: a separate §5 for **derived values** — the things the dictionary deliberately does *not* let you store. The heading is exact:
