FUNCTIONAL SPECIFICATION · v2
Scored components
Conscious Discipline at Home, a module for parents of kindergarten children. This document defines how the module reads what a parent writes: how answers are checked, how the role-play child responds, what triggers a safety response, and what is stored.
HOW TO USE THIS
Requirements are numbered so they can be cited in a bug report. Where one says must not, treat it as a release blocker. File names refer to the module's source: scoring logic lives in js/, and everything a writer edits (criteria, accepted wordings, replies, safety phrases) lives in content/.
1 · Decisions register
Settled. Changing any of these changes the spec below it.
DECISION
RESOLUTION
How answers are judged
By rules. Each criterion is a list of accepted ideas and wordings, checked in the browser. No AI model reads an answer.
What a parent is told
A band: Strong, Nearly there or Not yet, with each criterion named in a sentence. No percentages, points or overall score, anywhere.
Where answers go
Nowhere. Everything stays in the parent’s browser, under one storage key.
When a rule is wrong
The parent can say “I think my answer covered this,” and the module takes their word for it.
What runs first
The safety check, before any scoring, on every free-text field.
AI, later
An optional AI check is planned for version 2, with explicit consent. It is not part of this spec.
2 · The submit chain
Every free-text answer runs through the same steps, in this order:
safety check → gibberish check → matcher → band → coach feedback → saved
C-1If the safety check fires, nothing after it runs. No band, no attempt used, nothing saved. The parent’s text stays in the field.
C-2If the gibberish check fires, nothing is scored or saved and no turn is used. The parent is asked, gently, for a sentence.
C-3The matcher must not produce a number. Its whole output is the band and the list of which criteria passed.
3 · Test Your Knowledge: written answers
Four everyday situations. Each asks one question that needs more than one idea from Learn, and is checked against three or four criteria.
3.1 A criterion
Each criterion in content/quiz.js has:
FIELD
WHAT IT DOES
accept
The wordings that pass it. One match anywhere in the answer is enough.
veto
Rare. Wordings that cancel a pass the accept list already earned. Used once in the module.
hit
The sentence shown when it passes, e.g. “You named your own state as the first thing to manage.”
miss
The sentence shown when it doesn’t, e.g. “Your own state stayed out of the answer.”
3.2 Matching
Before comparing, both the answer and every accepted wording are prepared the same way:
M-1Lowercased. Apostrophes removed, so “won’t” and “wont” are the same word. All other punctuation becomes a space.
M-2A short synonym table folds a few phrasings together (“settle,” “steady” and “regulate” all count as “calm”). The table must stay short: each entry is a claim that two phrasings mean the same thing.
M-3Light stemming, so “calmer,” “calming” and “calmed” meet “calm.” It is crude on purpose; since both sides get the same treatment, an odd stem still matches itself.
M-4Matches are whole words, so “calm” does not fire inside another word.
3.3 Bands
CRITERIA MISSED
BAND
COACH SAYS
None
Strong
The “all” line for that question.
One
Nearly there
The line written for that specific miss. Naming which one is the point of the middle band.
Two or more
Not yet
The “many” line, and one sentence the parent could say.
B-1The parent’s own words are shown back first, then each criterion with its hit or miss sentence, then the coach line.
B-2A parent can try again. The best band stands; a retry never lowers a result.
3.4 When the rule is wrong
“I think my answer covered this” appears on any result below Strong. One tap raises it to Strong. It is not an appeal and asks for no reason: nobody is grading the parent, so there is nothing to defend. The claim is recorded so testing can show which questions it lands on, and those accept lists get fixed.
3.5 Worked example: question 1, at the checkout
He’s been fine all afternoon. Now he’s shouting for a chocolate bar, and a woman behind you is watching. The question: what is probably going on for him, and what would you deal with first?
CRITERION
SAMPLE ACCEPTED WORDINGS
A
Reads the outburst as running out of capacity, not as a choice
tired · overwhelmed · long day · held it together · not about the chocolate · hungry
B
Names the parent’s own state as the first thing to manage
breathe · calm · embarrassed · the woman · my own · me first
C
Sees that a consequence now won’t land
won’t hear · not the moment · later · once he’s calm · won’t work
Criterion A deliberately has no veto for “he’s testing me.” “He’s tired, but he’s also testing me” is a fair answer, and vetoing it would punish nuance.
4 · Try It Out: the role-plays
Three short conversations with Maya, a five-year-old. The parent gets three replies per scene. Maya answers what they actually wrote, and a short coach note follows each reply.
4.1 Maya’s state
Maya is at one of four levels, shown by her pose: 0 overwhelmed, 1 upset, 2 ready to listen, 3 content. Each scene starts at level 1.
4.2 What each reply is checked for
CRITERION
PASSES WHEN THE REPLY…
Composure
…does not contain a threat, a count, a label or a guilt line (“or else,” “I’m counting,” “because I said so”), and isn’t shouted. A word of three or more capital letters, or “!!”, counts as shouting.
Connect
…names what she’s feeling or wants (“it’s hard to stop,” “you really want…”).
Limit
…states the limit clearly.
Choices
…offers two acceptable choices.
4.3 How she moves
FROM
THE REPLY…
SHE GOES TO
Any
breaks composure
One level down
0, overwhelmed
connects, or is short (ten words or fewer)
1
1, upset
names the feeling, then gives the limit and choices, in that order
3
1, upset
names the feeling first, then the limit or the choices
2, and the coach confirms the order
1, upset
connects
2
1, upset
gives a limit without connecting first
Stays at 1
2, ready
has given both the limit and the choices, on this turn or an earlier one
3
2, ready
anything else
Stays at 2
R-1Connection before correction is enforced by the rules: while she’s upset, a limit doesn’t move her until she has felt heard. (A safety limit is the exception, set per scene.)
R-2Nothing is scored on screen during the scene. No ticks, no numbers.
4.4 The scene result
The criteria add up across the whole scene: a criterion met on any turn counts. Composure is the exception. If it broke on any turn, the result shows that one row and grays out the other three. The parent’s composure comes first in the approach, so it comes first in the result.
5 · Gibberish
Checked only when no criterion matched. An answer is treated as not understood when most of its words have no vowel, or when it contains no common English word and at least half of it looks keyboard-mashed. A real one-word answer like “whatevs” is not gibberish. Its result is simply a miss.
6 · Safety responses
Six categories, checked in order of seriousness, so an answer matching two gets the more serious reply. The reply appears where the coach normally speaks, with one resource button and “Back to the question.”
FIRES ON
POINTS TO
SR-1
A parent describing harm to their own child
National Parent Helpline
SR-2
Their child being hurt by someone else
A page in the module about it
SR-3
Worry about their child’s safety or wellbeing
988, or their pediatrician
SR-4
The parent’s own crisis
A crisis line
SR-5
A question about whether the approach applies to their own child’s situation
A person who knows the child
SR-6
Harsh language, including at the scripted child
The helpline, offered without judgment
S-1The two possible errors aren’t equal. A miss scores a disclosure as an answer; a false fire hands a good answer a crisis line. Lists are written narrowly for that reason.
S-2Inside a role-play, SR-1 to SR-3 fire only when the parent is writing about their real child (“my son,” “last night”). “She hit me” is an expected line about Maya.
S-3“I can’t do this anymore” is ordinary tired-parent language. SR-4 fires on its weaker phrases only when a second signal is also present. When in doubt, it does not fire.
S-4Each category’s full reply appears once per sitting; after that, a single shorter line. Nothing about a safety response is ever stored.
7 · Privacy and data
One object in the browser’s local storage, under a single key. Nothing is transmitted. It holds:
FIELD
HOLDS
screen
Where the parent left off, and which screens they’ve seen
answers
What they typed, per question
bands
Their latest and best band per question
claims
Which questions they marked “I think my answer covered this”
stripOpen
Whether they’ve opened Words to try
P-1Start again clears all of it, including the text in every field.
8 · Known limits
The weakness of rules is a parent who is right in words no list anticipated. In the first parent test (October 5, 2026) that happened on question 1: a sound answer got Not yet. Three things answer it, in order of cost:
L-1Add the wording. Each fix is one line in content/quiz.js, and can be checked in the browser console against a single criterion before it ships.
L-2The claim path (3.4) catches what the lists still miss, and records where.
L-3If testing shows the lists can’t keep up, version 2 adds an optional AI check, with the parent’s consent. The rules stay as the fallback and as the safety check.
Whether a written answer is the right way to check understanding at all is an open question, and part of the redesign now underway.
End of specification · v2, October 2026 · Replaces the September draft, which specified AI scoring