Codebook and Development Profile

For each session, CodebookClassificationService collects two kinds of subject — the insight results and the featured outcome — and asks one LLM call to file every one of them under an existing code. Subjects already classified are filtered out first, so replaying a session costs nothing and cannot double-count.

A name the model returns that does not match a code exactly is resolved semantically before being given up on; anything still unmatched is stored with a null codeId, which is what the growth pass looks for. The occurrence’s created is copied from the evaluation result it came from, not from the moment of classification.

Once a project has accumulated GROWTH_THRESHOLD (10) unclassified occurrences, CodebookGrowthService claims a batch of up to 50 of them and asks the model to propose codes that cover them, then assigns every text in the batch.

The claim is a per-document atomic update with a 5-minute staleness timeout, so two sessions ending at once cannot grow from the same texts. They can still coin two differently-named codes for the same pattern: each pass sees the codebook as it was when it started, and the unique index on (project, name) only catches identical names. Semantic duplicates are the known residual risk.

New codes are written in the language of the texts that produced them, so a project’s codebook takes the language of its evaluations.

DevelopmentProfileService renders three blocks into the prompt, all scoped to the same 30-day window and the same 7-day comparison bucket:

Counts alone cannot separate a habit that stopped from a week nobody practised, so every bucket is reported against the number of days in it on which this person was evaluated at all — "12× on 3 of 4 evaluated days". That denominator is computed across all of the user’s occurrences, so it is the same for every code and the codes stay comparable with each other. "None in 4 evaluated days" is a real quiet spell; "no evaluated days" is an absence of evidence, and the prompt forbids reading it as progress.

The direction of a metric is decided in Kotlin, not by the model. A move is only called when both buckets rest on at least 3 records and the change clears 5% of the metric’s declared range, or 10 points for a rate; otherwise the bucket pair is labelled flat or not comparable. Measuring against the range rather than against the previous value is what stops a metric sitting at zero from turning every flicker into a trend.

The range comes from the insight definition’s minValue/maxValue, and travels with the aggregation so the prompt can state it. Without it a reader — human or model — cannot tell 1.0 out of 5 from 1.0 out of 100.

The three evidence blocks are hashed into an evidenceFingerprint stored alongside the content. When the fingerprint matches the stored one, the model is not called at all and nothing is written: it would be handed the same prompt and could only reword the profile it already wrote. A profile that changes is then a signal to the reader rather than noise.

Two deliberate exceptions:

The previous profile is not part of the hash. Including it would change the fingerprint after every regeneration and the gate would never fire.

The model authors everything a reader sees. The service computes advisor — name, ISO dates, session and evaluated-day counts — after the loop ends, and strips it, along with generatedAt and model, from the profile the model is shown. The human-readable rendering of the same period lives in header.periodSummary, which the model writes, because plural forms and date order follow the language and cannot be assembled from a template.

A profile is written in the language of the codebook entries it was built from, which is whatever language the project’s evaluations use. Section headings and direction labels are therefore authored too, and carried in labels.

Because they are display furniture rather than findings, they are re-used verbatim while language holds, whatever the model wrote this run — a heading that drifts from one synonym to another between two sessions is noise the reader has to re-read for nothing. A direction the previous profile never used has no carried label, and that one is taken from the current run. The prompt asks the model not to rewrite them either; the carry-over is the guarantee.

Enumerations stay stable tokens in every language, so a client drives colour and ordering from direction and sentiment and takes the words from labels.

DevelopmentProfile.validate holds what the Kotlin types cannot: a note title and text that are present and under 1400 characters together, 2–8 skill rows with distinct snake_case ids, a label for every direction the rows actually use, and an action that is required on a Risk row and rejected on every other one.

finishProfile returns these errors to the model so it can fix them before it stops. If the content is still invalid afterwards, the last valid profile is kept and flagged needsReview; on a cold start nothing is saved at all. Valid content that arrived without finishProfile — a tool-loop step cap, say — is saved, also flagged.