build-case-study
Every rule here was paid for. Two case studies produced one published record that contradicted its own title, one metric that already existed, a silently dropped diagram, a claim scanner blocking an honest negation, and three false statements in a discovery report. The order below is the order that avoids repeating them.
This skill does not publish. Publishing is a separate, explicit instruction.
Every record carries a visual story, and the gate refuses one that does not. Since
2026-09-16 (Ali, on approving the CORA pilot: "harden the skill so every case study moving
forward follows this format") publish-gate rule 21, visual_story_missing, refuses any
snapshot with no visualStory that draws a workflow. §8d is therefore a required step,
not an option: author it after the evidence and the metrics, from the record only. It
draws the flow and charts the figures the record already verifies; it introduces no
number. A record with no verified outcome still draws how its system works and shows no
figures; the band says so in words.
The build is a loop, and it ends on a clean completeness audit, not on a feeling (§12).
Since 2026-11-17 (Ali: "Every time it goes through it needs me to correct it and tell it to
look at the skill and make sure all fields are accounted for ... add the loop architect inside
it so it compares it to 5 other approved case studies to ensure it has all the parts"), every
build runs under /loop-architect, and scripts/completeness-audit.js compares the draft with
the five most complete approved, published records, field by field. Run it at the START to
turn the gaps into the plan, after every task, and before any report to Ali. A build with a
GAP, a THIN list or a failed record check is not done, and Ali is never the one who finds it.
Day one, the same turn the draft is created: screens, cover concepts, video (§8, §8c, §8f). Since 2026-11-18 (Ali: "pictures are now gone - no video and I didn't get to pick hero pick even though you talked about it. Fix and harden so the video is not missed anymore. Also pictures ... it's been missed in every single 1st try"). Every first try deferred the media until "after the narrative", then ran out of turn and reported a record with no screens, no video and no cover pick. So the media starts BEFORE the narrative, in the turn §2 creates the draft:
- App screens. Run
node scripts/case-study-screens/captureAppScreens.js --check. If it exits 3, run--loginin the background at once. It opens an Edge window for Ali to sign in, which takes one minute. Make it the FIRST line of the message to Ali, not a request buried at the end. Then write a spec of 3 to 6 screens that show the work, capture them with--spec, and look at every PNG yourself (§8 "check every frame for people"). Never ask Ali to take screenshots by hand. Never stop at "the screens are behind a login". - Cover concepts. Write three concepts, generate them (scripts/case-study-thumbnails, steps 1 to 3)
and open the review page with
Start-Process. Never mention the pick without the page being open in front of Ali. - Video. Build a first cut of the walkthrough from title and cards slides as soon as the metrics exist, then rebuild it when the screens land. A record never reaches Ali without one.
completeness-audit.js has a named record check for each of these: real screens of the software (at
least 3), a video with captions and a poster, and a cover equal to the video poster. A record with any
of them failing is INCOMPLETE however many fields are ok. The ONLY acceptable reason for no app screens
is that the work has no interface. Record that with --accept=record.appScreens:"<why>".
Start section 8 (images) FIRST. Dispatch an agent to find or produce the real images before anything else begins — it takes longer than the rest and a case study without pictures reads as unfinished however good its evidence is.
The cover is a picked thumbnail, not a screenshot (§8f). Since 2026-09-18 (Ali: "harden this process so we always find thumbnail pictures for each project like this") every record gets three YouTube-style concepts from the image model, Ali picks one, and it becomes the cover and the video poster. The real captures stay on the record as evidence in the body.
0. Preflight — before any edit
git branch --show-current && git status --short && git log --oneline -5Read root CLAUDE.md, then docs/case-study/case-study-schema.md and
backend/src/types/caseStudy.ts. Preserve unrelated work.
Then check for an overlapping record. This is a hard stop.
SELECT id, slug, title, status, visibility FROM case_studies ORDER BY created_at;Match on slug, title, subject, commit AND pull request. A record can exist that is approved, private and completely empty — check its counts before assuming it is real work:
SELECT (SELECT count(*) FROM case_study_evidence WHERE case_study_id=$1) evidence,
(SELECT count(*) FROM case_study_metrics WHERE case_study_id=$1) metrics,
(SELECT count(*) FROM case_study_artifacts WHERE case_study_id=$1) artifacts,
(SELECT count(*) FROM case_study_publications WHERE case_study_id=$1) pubs;If an overlap exists: stop and present options. Never create a duplicate.
Claims of absence require a named search
"There is no analytics on the story pages" was reported once and was wrong —
caseStudyTracking.ts was fully wired. The grep used generic names
(trackEvent, analytics) and missed a domain-specific module.
A negative finding from one grep is not a finding. State the searches performed.
1. Path scope — propose, count programmatically, get approval
Derive from the subject. For a single change, the commit's own file list is the scope:
git show --name-only --format="" <sha> > /tmp/scope.txt
grep -c . /tmp/scope.txt # count it; never state a number you did not computeA proposal once said "24 prefixes" over a list of 30. Count, then quote the count.
Present: exact count, numbered list, the claim each path supports, tests included, neighbouring systems excluded, expected stack. Do not apply until approved.
Mechanics that surprise people:
- Prefixes are lowercased on write, matched case-insensitively.
- Matching is at segment boundaries —
backend/src/apinever matchesapiary. - A prefix may name a file. Essential when 5 relevant files sit in a directory of 25.
- Limit is 40.
- Any scope discards the repository-wide language list. Expect
["typescript"].reactdisappears even with frontend paths in scope. This is correct. Do not widen the scope to make the stack look richer.
2. Create, scope, sync
createCaseStudyFromRepoCollection({ title, repositories: ['owner/name'], actor })
node dist/scripts/scopeCaseStudyRepository.js --case-study <id> --repo owner/name \
--scope <p1> --scope <p2> ... --dry-run // then --confirm-production
syncCaseStudy({ caseStudyId, trigger: 'manual' })A sync reporting path scope matched 0 of N paths means a typo. Fix before authoring.
3. Author — WHOLE SECTIONS, never nested paths
The single most costly mechanic. applyHumanOverride refuses a path the snapshot
does not already carry, and a fresh repo-only record has no situation,
measurement, roadmap or contributors at all.
applyHumanOverride({ path: 'situation.narrative', ... }) // ✗ FAILS
applyHumanOverride({ path: 'situation', value: {...} }) // ✓ creates the sectionSet the complete object: identity, taxonomy (with departments), situation,
architecture, buildTimeline, measurement, heroMetrics, roadmap, contributors,
artifacts, repositories, walkthroughVideo, visualStory, builder, decisions,
closing and surfaceVariants. That is every field of CaseStudySnapshotContent; the
completeness audit (§12) checks them against published records, so a forgotten one is
reported, not discovered by Ali.
§3a's deployment, engagement and governance are NOT snapshot fields (checked
2026-11-17: absent from CaseStudySnapshotContent in backend/src/types/caseStudy.ts, and
from all 19 published records). applyHumanOverride cannot store them. Until the type gains
them, put their substance where the record keeps it: deployment in architecture.narrative
and roadmap, engagement in identity.engagementWindow and situation, governance in
decisions and the metric limitations.
heroMetrics is its own section. Marking a metric isHeadline: true inside
measurement does not populate it once measurement has been overridden. Set both.
3a. deployment, engagement, governance — the three the record kept in prose
Added 2026-10-02, after measuring the library against the OpenAI Partner Assessment Technical Capability Assessment workbook. Of the twelve fields that form requires, the record could answer three. Five of the remaining nine were already on the record — in a narrative paragraph, a capability tag, or the methodology text of a metric — just nowhere a form, a partner questionnaire or an RFP could reach them.
These sections exist to stop us failing to claim work we have already done. They add no new claim and relax no gate; every rule in §4, §5 and §6 applies to them unchanged.
applyHumanOverride({ path: 'deployment', value: {
customer, activeUsers, usageFrequency, volumeProcessed, productionDate } })
applyHumanOverride({ path: 'engagement', value: {
targetOutcome, firstContactDate, productionDate, elapsed } })
applyHumanOverride({ path: 'governance', value: {
owner, humanInLoop, guards, boundedActions, complianceRegimes, models } })| field | fill it from | if you cannot |
|---|---|---|
deployment.usageFrequency |
the job's own schedule, usually already written in a metric's plain.from |
omit the key |
deployment.volumeProcessed |
a count-shaped metric you already collected |
omit the key |
deployment.activeUsers |
a person. Never a repository. | omit the key |
engagement.firstContactDate |
a person. The first commit is not the first conversation | omit the key |
governance.humanInLoop / .guards / .boundedActions |
the narrative you already wrote | omit the key |
governance.models |
the connected repository | do not omit — see below |
Rules that bite:
- An omitted key and an empty one mean different things. Omit what is unknown. Write
complianceRegimes: []only to say none is claimed for this deployment, which is a real and useful answer. Never write0,"n/a"or"TBD"into a count. governance.modelsis not optional on a record about an AI system. We published fourteen case studies about systems that run models and named the model in none of them:taxonomy.stacklisted seven technologies and not one was a model, on a record whose own summary says a draft is "prepared by a model". If the subject calls a model, name the provider, the model and the step it runs. If it genuinely calls none, say so explicitly.deployment.customerobeysorganization_identity_mode, always. Ananonymizedrecord stays anonymized here. Naming consent is consent to publish; it is not consent to disclose in a partner submission, and the two are not interchangeable. Where disclosure matters, ask for it and record it separately — do not infer it from a published page.- Dates are
YYYY-MM-DDandelapsedis computed, never typed. A hand-typed interval is the first thing to drift when either date is corrected.
Re-authoring an existing record: replace the body, not just the head
A published case study once carried a new title over the previous case study's situation, architecture, measurement and roadmap. It read as two different stories.
Re-author every section, then diff the body against the new thesis. Scan the finished projection for language from the old subject and explain or remove every hit.
4. Evidence — every verified claim, pinned to a commit
A verified claim with no evidenceId is refused by the gate:
proof_metadata_missing. This includes identity.productionStatus.
A note string is not evidence. Create a real case_study_evidence row:
{ source_type: 'repository', source_ref: 'owner/name',
source_commit_sha: '<sha>', // pin to the SUBJECT commit, never `main`
title, description, // description carries a reproducible command
verification_class: 'verified', is_publicly_openable: true,
public_url: `https://github.com/${repo}/blob/${sha}/${path}` }The description must let another person re-derive the number:
git show --numstat --format="" 0b389be5, split on the.test.tssuffix.
last_seen_sha on the repository row is the repo's current head and is populated by
the sync (caseStudyRepoProvenanceWriter). It is not the right anchor for a claim about
a specific change — pin evidence to the subject commit yourself.
A COLLECTED METRIC ALREADY HAS ITS EVIDENCE. Do not write one by hand. When a
manifest registers a collector (§5), the sync creates the case_study_evidence row
itself, pinned to the commit the figure was computed at, with the reproduce command in
the description. Writing a second row by hand gives the record two pieces of evidence for
one number that can then disagree, and the gate blocks a figure whose commit does not
match the one the record is pinned to (metric_collected_sha_mismatch).
The hand-written block above is for figures the repository cannot compute.
What a repository can never prove: use method, do NOT invent a class
There is no attested verification class, and adding one is a mistake. An earlier
draft of this section specified one. It was wrong, and the vocabulary already in the
codebase is better.
CaseStudyVerificationClass is exactly four members — verified, anonymized,
illustrative, pending — and caseStudyContracts.test.ts reads
frontend/src/components/publicV2/Claim.tsx as text and asserts the same members in
the same order, toHaveLength(4). A fifth member fails that test by design. The order is a
tripwire for exactly this: somebody editing one list without looking at the other.
Class and method are two orthogonal axes, not a hierarchy (backend/src/types/caseStudy.ts):
| axis | question it answers | members |
|---|---|---|
class |
how much of this claim may be shown | verified · anonymized · illustrative · pending |
method |
who established it | client · repo · platform · internal · self · manual |
So the thing the earlier draft wanted already exists:
{ class: 'verified', method: 'client' } // the client confirmed it and may be named
{ class: 'anonymized', method: 'client' } // the client confirmed it, will not be named
{ class: 'verified', method: 'repo' } // a commit proves itPutting "who said it" into the "how much may be shown" vocabulary collapses the two axes and loses the distinction that makes either useful. Do not do it.
For a figure no repository can produce — a user count, an engagement date, an outcome in
use — write method: 'client' (or 'platform' where our own telemetry produced it), pin
reviewed_by and reviewed_at on the evidence row, and keep source_commit_sha null.
The honest sentence is "the client's operations lead stated X on this date", never "X".
Do not back-fill a client-method claim from memory, from a meeting nobody took notes in, or from an email that implies rather than states the figure.
The real gap is in code, not vocabulary. computeMaturity
(backend/src/services/sbp/caseStudyFoundation.ts) counts verified stories, merged
enrichments and demonstration references — it never reads a verification method at all.
That is why operational_result is unreachable: not because the vocabulary is missing, but
because nothing teaches the ladder that a client-confirmed outcome is different from a
passing test. Until that lands, a method: 'client' row is recordable and correct, and
still will not move the rung.
5. Metrics — work the whole candidate list
A case study once shipped with one metric, and that one already existed on the record. Eight candidates had been listed in the brief; seven were never attempted.
Build a candidate table and fill every row. No candidate silently skipped:
| Candidate | Shape | Collector | Built | Value | Evidence | Reason if not |
|---|
If the repository can compute it, you do not type it. Register the collector in the manifest and let the sync produce the figure, the methodology, the limitations and the reproduce command together, pinned to a commit. A number you typed is a number somebody has to trust; a number the repository computed is one they can re-derive.
The five collectors, and the shape each produces:
collector |
Shape | What it counts |
|---|---|---|
test_files |
share | Test files as a share of source files. |
modules_with_tests |
ratio | Named modules that have a test file, out of all of them. |
decision_records |
count | Decision records committed to the repository. |
commit_span |
span | First to last commit date, and how many commits fall inside. |
commits_per_week |
series | Commits per calendar week across that span. |
Register one in the repository's case-study.json:
{ "outcomes": [
{ "key": "modules_with_tests", "label": "Modules with a test file",
"collector": "modules_with_tests" }
] }value_display becomes optional once collector is set. Leave it out. A collector that
cannot compute its figure creates no metric at all rather than a zero, so a missing
card is the honest answer and not something to fill in by hand.
For anything the repository cannot compute, keep writing metrics by hand and give them a
shape and a payload yourself where one fits. A hand-written ratio still renders a
meter and still names its members; it just does not come with a reproduce command.
Prefer repository-verifiable metrics — they need no production read and a reader can reproduce them. Strong ones: schedule interval, files changed, lines added, test files, test-to-implementation ratio, resolution paths, operating modes, gate counts.
Every count states its denominator. "243 agents" and "116 that ran this week" are different facts; reporting the first as the second is the failure this system exists to prevent.
Each metric needs: stable key, label, display value, numeric value, unit, metric type,
baseline, sample, what was measured, methodology, limitations, verification class and
method, verifiedAt, real evidenceId, publishable, explicit headline decision.
Never invent a figure to fill a card. An honest gap — 0, not built — is a
stronger fact than a manufactured one.
5a. At least one metric must COMPARE, not just COUNT
Sort every candidate into two kinds before writing any of them:
| What it says | From the live CoreOps record | |
|---|---|---|
| Change | it is different now, and here is what it was | 7 modules · 4 with tests — baseline: "A policy comment, which is what an unenforced boundary looks like." |
| Scale | how much of a thing there is | 46 test files — baseline: "n/a — this sizes the test surface rather than comparing it." |
Scale metrics are legitimate and easy to verify, which is exactly why a record drifts into being all of them. Four counts of the repository's own contents is an inventory, not a result, and a reader who wanted to know whether the work mattered leaves without an answer.
Ship at least one change metric, or say in the measurement narrative why the record has none. A build with no before-state is a real situation — greenfield work has nothing to compare against — and naming that is stronger than dressing four inventories up as outcomes.
baseline: "n/a" is the tell. When you write it you have just built a scale metric.
That is fine once; if it is true of every card, the set is wrong.
THIS IS NOW A GATE RULE, NOT ADVICE. It was advice for months and the library drifted anyway: on 2026-09-12 all fourteen published figures across the three live records were scale metrics, and three of them were deficiencies standing in the slot a reader reads as the result — 0.7% test coverage, 16% test files, and a commit cadence under four a week. The hero row was cleared on all three, and two blockers now stop it recurring:
| code | fires when |
|---|---|
headline_metric_is_a_bare_count |
a headline figure has no ratio/share/series shape, no two-ended span, and no stated measurement.baseline |
headline_metric_missing_plain_answers |
a headline figure is comparative but does not carry all three of §5b |
A scale metric is still perfectly publishable in the measurement section, which is where "we built eight agents" is an honest thing to say. The rule only governs the hero.
An empty hero row is allowed and is often the right answer. The public strip renders without it, falling back to the facts and indicators, and a record that opens with no figure reads better than one that opens with an inventory. If the work has no comparison to show, show none and say why in the measurement narrative.
The second rule is the one that catches a bad figure the first cannot. A machine cannot tell pride from embarrassment, so it does not try; it asks the author to write "what this does not tell you" beside the number. Writing that line about one file in a hundred and forty-two is usually enough to stop the card.
5b. Plain language: the three answers every figure owes a reader
A shaped metric renders three short blocks under its picture, and they are written by a person. A collector never writes these. It can count files; it cannot tell you what the count means to somebody who did not build the thing.
| Block | The question it answers | Write it as |
|---|---|---|
| What this counts | what is actually in the number | one sentence naming the unit and the boundary |
| Where it came from | why anyone should believe it | the source, and the moment it was taken |
| What it doesn't tell you | what a reader must not conclude | the honest limit of the figure |
From the live CoreOps record:
What this counts Source files under
guardrails/that carry a matching test file. Where it came from The repository tree at the pinned commit, by filename. What it doesn't tell you Whether those tests assert anything useful.
All three or none. The API sends a complete set or nothing, and the gate warns on a
shaped metric with no plain. The reason is not tidiness: a figure that says what it
counts and where it came from, but not what it cannot show, is the exact shape of an
overclaim. Two thirds of an answer reads as more certain than the number is.
Three rules that have already produced weak blocks:
- Write to the reader, not to the reviewer. "Test files are identified by name" is a note to yourself. "A file named after a module may test almost none of it" is the sentence that earns trust.
- The third block is not a hedge. It is the specific thing this number cannot establish. "Results may vary" says nothing; "this counts files, not coverage" says exactly what a sceptic was about to ask.
- Plain language replaces the definition list, it does not sit beside it. A card with
plainrenders the three blocks instead of BASELINE / UNIT / SAMPLE / METHODOLOGY. If the methodology paragraph carries something the three blocks do not, it belongs in "Where it came from", not in a second list underneath.
5c. Write each field for the card it renders into
The reader never sees the object. They see, in this order:
<valueDisplay> ← large, carries the whole claim
<label> ← the sentence under it
<verificationClass> ← "verified"
BASELINE <baseline> ← labelled rows, in this order
UNIT <unit>
SAMPLE <sample>
METHODOLOGY <methodology>
LIMITATIONS every entry, in fullFour consequences, each of which has already produced a weak card:
valueDisplayis the entire headline. It must read as a complete phrase on its own — "14 decision records", not "14". Nothing else renders beside it.unitis metadata, and the card decides whether to print it. WritevalueDisplayas the complete phrase and setunitto the bare token. The renderer suppresses the UNIT row when the value already says that word, so "14 decision records" no longer sits above a row reading UNIT: records. You do not have to trade one against the other. A unit that adds something the value does not say —41%with unitpercentage points— still prints, which is the case the rule exists to protect.Measured, not guessed: 13 of the 14 metrics published across the three live records repeated their unit. That is what makes it a rendering decision rather than fourteen separate authoring slips.
methodologyis the card's body. It is the longest text in the card and the only place a sceptical reader can check your working. A single clause leaves the card visibly empty; write the paragraph that lets someone reproduce the number.Every
limitationis printed, in full, verbatim — nothing truncates them. Write them as sentences addressed to the reader, not as internal caveats. "A file count is not coverage, and 46 of 292 says nothing about which 46" does more for the record's credibility than the metric above it does.
5d. The headline decision is public
isHeadline: true selects headlineMetric in the summary projection — the payload
every index card and every brand surface reads. It is not an internal ranking. It is the
one number chosen to represent the whole record to somebody who has not opened it.
Pick the metric that best answers "did this work?". That is usually a change metric, and it is almost never the largest number.
6. Language the claim scanner rejects
The scanner matches phrases, not meaning. It cannot tell a claim from its denial. A narrative listing "no cost saving" among things deliberately not claimed was blocked as an unbacked ROI claim.
Avoid everywhere — including in negations:
cost saving · cost savings · ROI · hours saved · productivity ·
in production · revenue impact · accuracy improvement
Safer: "the scheduler has an enabled runtime record", "the current count cannot be assigned to one process", "multiple processes operated in the same period".
Why the list is absolute today, and what should make it conditional. Every one of these phrases describes an outcome, and in practice the only evidence a published record carries is a commit. A commit cannot prove a saving, so an unconditional ban is the correct rule for the evidence we actually have.
The intended end state is conditional: blocked without a method: 'client' evidence row
on the same claim, permitted with one (§4). That depends on the ladder learning to read
the verification method, which it does not yet do — so until then the list stays absolute.
Do not write around it. A blocked phrase means the claim is not yet evidenced, which is
information, not an obstacle.
7. Diagrams — no angle brackets, ever
projectDiagramSource returns null for any source containing <, silently. A
diagram using <br/> was published as nothing and nobody noticed.
Use - instead of <br/>. After saving, verify the projection returns it:
p.projection.architecture.diagramSource ? 'renders' : 'SANITISER DROPPED IT'The same no-angle-bracket rule binds every label in the visual story (§8d); when the story draws the flow, the Mermaid drawing folds under "View technical proof".
8. Images — start this FIRST, in parallel, and do not finish without them
The logged-in app is not a reason to skip it.
scripts/case-study-screens/captureAppScreens.jssigns in once through a visible Edge window (--login; the session is saved toscripts/.ali_admin_jwt.txt, which is git-ignored), then captures a spec of screens headless and redacts them. It replaces every email address and phone number, replaces literal names you pass inredactText, and paints overmaskselectors. It refuses to write a screen that still shows a contact detail. Names cannot be found by a pattern: pass them in, mask their cells, and look at every capture. Day one, before the narrative (see the top of this skill).
This is not a checklist item at the end. It is a workstream that begins before the narrative and runs alongside it, because finding or making the right image takes longer than everything else and cannot be rushed at the finish.
Spawn an agent for it on day one
The moment the subject is known — before the path scope, before the metrics — dispatch a dedicated agent whose only job is imagery. It works while the record is authored.
Find or produce the cover image and supporting images for a case study about
<subject>, repo<owner/name>. Search the repo for screenshots, dashboards, architecture drawings and demo captures. Checkfrontend/public/site-v2/for an existing asset that genuinely depicts this system. If the subject has a UI, find a capture of it. If it has data, a dashboard view of that data is ideal. Report what exists, what could be produced, and what would be dishonest to use.
Do not block on it. Author the record in parallel and attach when it reports.
The cover image is the point
A record without a cover opens on text and reads as unfinished no matter how good the evidence is.
Since 2026-09-18 the cover is the §8f thumbnail. Everything in this section still governs the REAL images: at least two captures of the work, which appear in the body, and which stand as the cover only until Ali has picked a thumbnail. Never skip the search for real captures because a thumbnail is coming: the thumbnail is atmosphere and proves nothing; the captures are the evidence.
identity.heroImageUrl now names the cover, and it is gated. It did not always: it
was set correctly on a snapshot, the page showed a different image, and the reason was
that nothing read the field — it was not even on the domain type. It is real now, and the
gate is the part that matters: resolveHeroImage() accepts the named URL only if it
matches an approved, publicly-viewable artifact on the same record, so naming a URL can
never publish a picture the artifact approval did not see. A URL that fails the gate falls
back to type priority rather than erroring, which means a silently wrong cover is the
failure mode — verify, do not assume.
When nothing is named, the cover falls back to artifact type in this fixed order
(HERO_IMAGE_PRIORITY in caseStudyArtifactPresentation.ts):
'screenshot' -> 'architecture' -> 'photo'Consequences worth knowing BEFORE rendering anything:
diagramis not a valid artifact type at all. It is absent fromHERO_IMAGE_PRIORITYand fromCaseStudyArtifactType. Writing one does not fail at the write — it fails in the browser, whereARTIFACT_TYPE_LABELS['diagram']is undefined and.toLowerCase()throws, blanking the entire page. This shipped. The valid set is:screenshot, architecture, photo, demo, deck, roadmap, report, evaluation, code, document, other.- Type decides, not creation order. An
architectureimage beats aphotohowever they were added. - Never relabel a generated chart as a
screenshotto promote it:screenshotasserts a capture of something running.
Verify the projection actually returned what you intended:
p.projection.heroImageUrl // must be the URL you expected, not merely non-nullBefore falling back to a generated image: prove the repo has no interface
You may not generate an image until you have searched the repository for one and come
back empty. On the CoreOps record this step was skipped, a dashboard was generated from
the record's own figures, and Ali asked the only question that mattered — "Are you saying
that image was in the repo?" It was not. The repo had shipped a nine-page
command-center/ app the whole time.
find <repo> -name "*.html" -not -path "*/node_modules/*" | head -40
find <repo> \( -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" \) -not -path "*/node_modules/*" | head
ls <repo>/{public,static,dist,build,docs,ui,web,app,frontend} 2>/dev/nullAn interface counts even when it is static HTML with no server and is deployed nowhere.
scripts/captureRepoUiScreenshots.js serves a directory locally and screenshots named
pages, so anything that renders in a browser can be photographed:
node scripts/captureRepoUiScreenshots.js --root <repo> --out frontend/public/site-v2 \
--height 1250 --page ui/index.html:shot-<slug>-consoleServe the REPOSITORY ROOT, not the UI folder. A page fetching .colaberry/plan.json
resolves it against the document root. Rooted at the UI folder, every capture came back a
perfectly rendered shell reading "plan.json is missing or unreadable — nothing to show
yet": real chrome, real CSS, zero content. Rooted one level up, the same page rendered
thirteen traced requirements.
Then open the PNG and look at it. The script refuses a page under 40 characters, and that guard is nowhere near enough — the empty-state captures above carried 273 to 440 characters of real text and were still worthless. A byte count proves a page rendered, not that it rendered anything. Pick the page with the most content, not the most bytes: of nine CoreOps tabs, four were honest empty states and the best one had six times the text of the tab that was captured first.
What counts as a real image, in order of preference
- A screenshot of the thing running. If the system has any interface, this is the image. A dashboard, a console, a report, a queue view.
- A dashboard of the system's own data — a Power BI-style view built from real figures the record already carries. This is the right answer when the subject is a pipeline, an agent or a service with no interface of its own.
- A rendered architecture diagram —
scripts/renderCaseStudyDiagram.jsturns the record's owndiagramSourceinto a PNG. - A rendered metric chart, for UNSHAPED metrics only:
scripts/renderCaseStudyMetricChart.jsdraws measured values with the reproduce command printed underneath. A shaped metric already draws itself. The card renders a meter, a chip grid, a date bar or a sparkline from the payload, live and in the reader's theme, so rendering a second static picture of the same numbers puts two charts of one figure on the page and gives the reader a version that cannot update. Reach for this tier only when a figure has no shape. - A photograph of the actual work or the actual people, where one exists and consent allows.
What does NOT count
- A mermaid block is not an image, and a rendered mermaid chart is not a picture. The block satisfies the architecture section and fails every image check. Rendering it to PNG does not promote it: Ali's ruling is "you can't use a mermaid chart as a picture because the formatting will be off." A diagram rendered at a diagram's aspect ratio, dropped into a slot shaped for a screenshot, reads as a mistake — it sits tiny and centred with the page's whitespace around it. Diagrams belong in the architecture section, inline, where the layout expects their shape. Two real pictures beat one real picture plus a rendered diagram.
- A chart of the record's own numbers is not a screenshot of the product, and must never be captioned as though it were. If tier 2 is genuinely the best available, say what it is in the artifact description — "a dashboard built from the figures this record carries" — and never style it to resemble the subject's real console.
- A stock photograph is not evidence. An atmosphere image standing in for a screenshot is the thing the publish rules exist to prevent — it implies a system was seen working when it was not.
- A screenshot of a different system. If the image does not depict this subject, it is decoration pretending to be proof.
- CODE, EVER. Ali, 2026-11-18: "Don't ever show code in a case study." That means no
screen of source, a prompt or
.mdfile, a JSON or YAML entry, a terminal, a diff, a pull request, or the AI tool that built it ("Remove the claude code screenshots ... the part where you show claude is boring"). Show the product a buyer would use and the result it produced. The audit'sno code showncheck refuses a public artifact whose file is source or data or whose title says code, prompt, terminal, JSON, commit, pull request or Claude. Not even as "how it was built": that story is told in words, in the decisions. A link into a repository is code too: a public artifact pointing at a file or folder on GitHub (/blob/,/tree/) is refused like a screenshot of it (the 19 Nov sweep found three on one live record: two.mdfiles and an infrastructure folder; they were made private, not deleted). Ali, 2026-11-19: "don't want any code or claude code screenshots in the video or the presentation", so the same rule holds for every frame of the walkthrough video: before attaching it, render a contact sheet (ffmpeg -i v.mp4 -vf "fps=1/10,scale=480:-1,tile=4x4" -frames:v 1 sheet.jpg) and look at every tile.
Trim every screen, and they show one at a time
Ali, 2026-11-18: "I don't like the scroll bar for the artifacts. Instead use a carousel and trim the screenshots." Both renderers now draw the pictures as a one-slide carousel (no scrollbar, arrows and a "3 of 21" count, each picture whole inside the same 16:9 frame), so:
- Trim before attaching: cut the blank page margins, and cut a very tall capture to its headline chart (a funnel without its table, the top of a timeline). A screen taller than it is wide reads tiny in a 16:9 frame; a phone view belongs in the video, not the carousel. Never alter a pixel inside what you keep.
- The caption is the message. The carousel prints each artifact's title and description under the picture, so the description says what the picture shows and what it means, in the order the story tells it. Attach in story order.
- Show the product being used. When the product has a guided tour, a wizard or a flow,
capture a screen per step (the tour's stops) as well as the overview, and record a GIF of
a person moving through it (
scripts/walkthrough-video/screencast.js).
Generating one honestly
When a subject has no interface — a classifier, a cron job, a library — the honest image is one made from the record itself:
node scripts/renderCaseStudyDiagram.js --in diagram.mmd --out frontend/public/site-v2/<name>.png
node scripts/renderCaseStudyMetricChart.js --in bars.json --out frontend/public/site-v2/<name>.png --title "..." --foot "Reproduce: <command>"Both refuse to invent: the diagram renderer reads the record's own source and rejects
anything containing <, and the chart prints the command to reproduce its numbers.
Watch the units. An early chart plotted 945 lines beside 9 files on one axis — two different units, so both bars meant nothing. Compare like with like or use two charts.
Getting them served
Images live in frontend/public/site-v2/ and reach production through an nginx
deploy, which also bounces the backend. Batch them: render every image for the record
before deploying once.
Attaching them
{ artifact_type: 'screenshot' | 'architecture' | 'photo' | 'report',
source_type: 'generated', // or 'repo' for a capture from the codebase
source_commit_sha: <sha>,
visibility: 'public', status: 'approved',
public_url, preview_url } // set BOTH; some surfaces read preview_urlartifact_type is a closed set and writing outside it blanks the page. There is no
write-time validation, so a bad value persists happily and only fails in the browser,
where ARTIFACT_TYPE_LABELS[type] is undefined and .toLowerCase() throws. The full
valid set: screenshot, architecture, photo, demo, deck, roadmap, report, evaluation, code, document, other. diagram is not one of them.
Then lift the approved rows into the snapshot's artifacts section — creating the row
alone does not put it on the page — and set identity.heroImageUrl to the cover.
Done means
- The projection's
heroImageUrlreturns the image you INTENDED, not just non-null - At least two approved, publicly viewable images (readiness checks both)
- Every image depicts this subject
- Every
artifact_typeis in the valid set above - Artifacts lifted into the snapshot, not just created as rows
- Images verified live with an HTTP 200 before the record is called finished
- The rendered page was opened and looked at — see section 8b
- The cover and the video poster are the §8f picked thumbnail, and every real capture is in the body (the old cover included)
8a. What the builder already made beats anything you can produce
The rule above is about pictures. It generalises, and it is the more important half: search the repository for what the builder actually produced before you create, generate, or commission anything. A case study about someone's work that illustrates itself with our own output is a case study about us.
Look in artifacts/ first. It is one of only four paths the platform lets a build
write to (CLAUDE.md, docs/, .colaberry/, artifacts/ — see PATH_ALLOWLIST in
renderDocs.ts), and it is the one reserved for what the build produced rather than what
the platform wrote. It is also the folder this skill never mentioned until 2026-09-14,
which is why builders' own output was being walked past.
ls -R <repo>/artifacts 2>/dev/null | head -40
find <repo> -maxdepth 3 \( -name "*.pdf" -o -name "*.pptx" -o -name "*.csv" -o -name "*.ipynb" \) \
-not -path "*/node_modules/*" | head -20
find <repo> -maxdepth 2 -iname "*report*" -o -maxdepth 2 -iname "*eval*" -o -maxdepth 2 -iname "*demo*" | head -20Anything found maps to a real artifact_type, and the set is wider than screenshots:
screenshot, architecture, photo, demo, deck, roadmap, report, evaluation, code, document, other. A learner's evaluation notebook is an evaluation. Their slide deck is
a deck. Their exported results are a report. Each is stronger on the record than
anything generated, because the builder made it while doing the work.
Set source_type: 'repo' and source_commit_sha on anything taken this way, so the
record states which commit it came from and a reader can go and look.
Does it make sense? Three questions, all of which must pass
Finding an artifact is not a reason to publish it. Ask, in this order:
- Does it show the work, or does it show the tooling? A screenshot of the running
system, an evaluation of its outputs, a deck presenting it: these show the work. A
package.json, a CI badge, a folder listing: these show that software exists. - Would it mean anything to someone who did not build it? An architecture diagram usually survives this. A raw log file usually does not. The test is the same one the metrics learned on 2026-09-13: a thing that only the builder can read is inventory, whatever format it is in.
- Is it honest at the moment it is shown? An empty state, a half-seeded dashboard, a demo pointing at a dead endpoint — all real, all in the repo, all misleading on a record. Nine CoreOps tabs were captured and four were honest empty states; the useful one had six times the text of the tab captured first.
A found artifact that fails any of the three is left where it is. Nothing is better than something that does not make sense — the same standing rule the hero row learned.
Two things that will bite
Promotion is a button, and a candidate is invisible until you press it. Approve an
artifact on the Studio's Visuals tab ("Approve + publish"), which calls
PATCH /api/admin/case-studies/:id/artifacts/:artifactId and sets status: 'approved',
visibility: 'public' in one idempotent write. Nothing else moves an artifact off
candidate, and projectArtifacts silently drops anything that is not approved, so a
record can carry sixty candidates and render none. (This section said on 2026-09-14 that
the promotion path had no caller. It did; the file's header describes the gap it was
written to close, not the present. Read headers here as dates, not status.)
A private repo is a publish blocker, not a warning. An artifact whose public_url
points into a private repository trips private_repo_exposed at the gate. Check the
repository's visibility before promoting anything that links into it, rather than at
publish time when the refusal costs a round trip.
8b. Open the page and look at it
A record can pass every gate in this file and still be wrong on screen. Ali's ruling after the CoreOps record published: "The content is good when everything is there, but it needs a UI/UX developer to make the format correct." Data checks do not catch layout.
Never call a record finished from an API response. Render it and photograph it:
BROWSER=none PORT=4321 npx react-scripts start # in frontend/
node scripts/previewStoryLayout.js --slug <slug> \
--payload <projection.json> --out preview.png --width 1440
node scripts/previewStoryLayout.js --slug <slug> \
--payload <projection.json> --out band.png --clip ".cbv2-story__context"previewStoryLayout.js intercepts the public API in the browser and fulfils it from a
file, so it renders the real page component with real content without writing
anything. That matters: a fixture with two-word metric values hides the exact defect this
is for. Take the live projection, substitute only what is under review.
It prints the measurements that catch the failures seen so far:
| Reading | What a bad value means |
|---|---|
pageScrollW > viewportW |
Something is pushing the page sideways |
factRows > 1 at 1440px |
The facts row is trapped in a narrow track |
metricHeights wildly unequal or > ~800px |
Cards are in a column too narrow for their prose |
cover: null when a cover is set |
The hero is not rendering it |
problems[] non-empty |
A JS error or a failed asset |
Check at 1440 and at 390. Both were needed: the desktop defect was a void, the phone risk is horizontal overflow.
The layout failures this page has actually shipped
- A band sized for one card, given two. The context band split 5fr/7fr to put facts beside the figure card. With two headline figures the 7fr track fits two 20rem columns, every card becomes a narrow tower of wrapped prose, and the six short facts run out after three rows — leaving a screen-height void beside them. A layout tuned for one of something is a defect waiting for the second one.
- A cover that no page rendered.
heroImageUrlreached the index card and the detail page ignored it, so the page a shared link opens was the one page with no picture — and the masthead held an empty right half the whole time. grid-row: 1 / -1with nogrid-template-rows. The explicit grid has one line, so-1resolves back to line 1, the span collapses, and the spanning element's height becomes row 1's height. It put 600px between a breadcrumb and a title. If an element must span a variable number of rows, wrap the others in one child instead.- Labels stacked above two-word values. Four label/value rows printing the label on its own line is eight lines of card height to carry four facts. Put the label in a fixed left track.
- The closing call to action in a 448px black block, off centre (Ali, 2026-11-18:
"the black space ... where the text is not centered and not on a good ratio"). It
inherited the 128px section padding and a left-aligned card. Fixed in
storyDetailV2.css; the check is that the eyebrow, heading and button are centred on one axis and the band is no taller than its content plus 64px each side. - Pictures in a strip of cards with a scrollbar (Ali, 2026-11-18: "I don't like the scroll bar"). Now one slide at a time on both renderers; the check is no visible scrollbar, a "1 of N" count, and every picture whole in its frame.
Before publishing, confirm on the rendered page
- The cover appears in the masthead, at a size that can be read
- No band has a void larger than a card beside its content
- Every metric card's methodology paragraph has a readable measure, not ~40 characters
- At least one metric compares — not every baseline is
n/a(§5a) - No card says its unit twice — read
valueDisplayand the UNIT row together (§5b) - Every limitation reads as a sentence to the reader — they render in full (§5b)
- The headline metric is the one that answers "did this work?" (§5c)
-
pageScrollW === viewportWat 1440 and 390 - Diagrams are in the architecture section, not standing in for a picture
- If the record carries a visual story (§8d): the band sits under the context strip, the strip prints no duplicate headline figure, and the band renders at 768 too
- The story in brief: label caption-size, each text directly under its label, desktop and phone
- The pictures: one at a time, no scrollbar, a "1 of N" count, no screen of code (§8)
- The closing band: centred, and not a tall empty black block
-
problems[]is empty - On all three surfaces, not the one you previewed: the rail, the status board, the folds and no empty "Who built it" (the §8e marker table), and the flow in lanes at 1440. A format checked on one site is a format shipped on one site.
8c. The walkthrough video — EVERY record gets one
A record without a narrated walkthrough is not finished. Ali, after the first one shipped: "go ahead and create for the other case study and also harden the Case study skill to include these videos on every case study creation."
It is roughly 80 seconds, 1080p, and it sits in the masthead's picture slot on all three surfaces — not in a band underneath. That was tried and it opened a record with two visuals doing the same job: the cover screenshot, then a film of the same product, with the reader scrolling past the first to reach the second.
Toolchain: scripts/walkthrough-video/. Read its README before starting; it carries the
failures below with the commands attached.
Machine setup has one value per slot, in the README's "Setting up a machine" table
(Python 3.12, edge-tts, Pillow, ffmpeg/ffprobe from Gyan.FFmpeg, Arial from
C:/Windows/Fonts, voice en-US-AndrewNeural), each with its check and its install line.
Run the checks before telling anyone a tool is missing, and install from that table rather
than choosing tools again (Ali, 2026-11-11: "the skill should have all this information - no
need to recreate the wheel"). Put ffmpeg's real bin folder on PATH: winget's Links shim
is not enough for Python's subprocess.
A record with no usable footage or screenshots (for example a login screen showing features
that are not built) gets a deck of title and cards slides carrying the record's own
sentences and its verified figures only (preference 4 below). ToolSmithAI, 2026-11-11, is
the reference: decks/toolsmith-ai.json.
python make_narration.py --deck <dir>/deck.json # neural voice -> audio/ + timings.json
python build_video.py --deck <dir>/deck.json # slides + footage + audio -> mp4
python make_vtt.py --deck <dir>/deck.json # the accessible caption sidecarmake_narration.py runs FIRST. Segment durations come from how long each sentence
actually takes to speak, not from the deck's guesses, or a slide ends mid-word.
The captions: one layer, and check which one it is
The sentence the narrator speaks can reach the reader twice — burned into the picture by
build_video.py, and again as the .vtt sidecar make_vtt.py writes. Ali, after seeing
both at once: "We have double captions - there should only be one."
BURN_CAPTIONS in build_video.py is the switch, and it is currently False. Read
it before describing the film to anyone; this paragraph said the opposite for two months
after the code changed, which is long enough for someone to "fix" a video that was right.
With burning off, the .vtt is the only caption layer there is.
Which makes the default attribute on the <track> load-bearing, and it is absent.
StoryHeroFigure.tsx renders <track kind="captions" srcLang="en" label="English"> with
no default, because when captions were burned in, marking it default put two read-overs
on the same frame. That reason is gone. As it stands a viewer sees no captions at all
unless they find the CC control, which is one layer fewer than Ali asked for rather than
one. Do not flip it silently as part of a video build: it changes every live record at
once, so raise it as its own decision.
It is also worth knowing that crossorigin="anonymous" on the <video> is load-bearing
for the captions and nothing else: a cross-origin track is refused without it, the
track's readyState goes to 3 and the cue list stays empty while the video plays
perfectly. Nothing looks broken except the missing captions.
Check it on the rendered page, not in the markup. The two layers are only obviously two layers when you look at a frame:
// captions the browser is painting — should be 0 showing, with the cues still there
[...document.querySelector('video').textTracks].map(t => ({ mode: t.mode, cues: t.cues?.length }))And to see what is burned in, pull the file rather than trusting the player, which will
not have buffered anything under preload="none":
ffmpeg -ss 8 -i walkthrough.mp4 -frames:v 1 -y frame.pngEvery figure it narrates is already a metric on the record
The video is a second surface for the same claims, never a place for new ones. If a number is spoken or printed on a card, it is a published metric on the record underneath, with its methodology, denominator and limitations. A figure that exists only in the video is an unverified claim that happens to be made of pixels and audio — the exact thing the publish gate exists to stop, arriving through a door the gate does not watch.
Write the deck AFTER the metrics are authored, and take the numbers from the projection rather than from your notes.
What it is made of, in order of preference
- The project's own demo recording, if it committed one. Cropped to the application window, held at its real rate — a 1.3fps timelapse shown as slow stills is honest; interpolating it into motion the source never had is not.
- A recording of a person using the real product (
clipslides). Ali, 2026-11-18: "show the person going through the tour". Drive the real (public or redacted) page with a visible cursor throughscripts/walkthrough-video/screencast.js, log the time of each step, assemble the frames with ffmpeg, and cut the clip into slides bystart. The builder holds the last frame if a sentence outlasts its cut. - Its real screenshots, the same ones the record already publishes as artifacts.
- Its own architecture diagram, rendered from
diagramSource. - Typographic slides carrying the record's own sentences.
Nothing is generated or restaged: a clip is the real page doing what it does, performed once, at its real speed. There is no sixth option.
The script follows the product, not the build. Lead with the single most important thing the product says (the one action, the headline result), then walk the reader through the rest the way a user would (the top 10, the tour), then what it predicted and how that was graded. Never a slide of code, a prompt, a terminal or the AI tool that built it (§8, "the part where you show claude is boring"). The visual story's workflow illustration (§8d) is NOT slide material: it is an illustration drawn by the team, and a film that shows it as if it were the product is exactly the fault §8 forbids.
CHECK EVERY FRAME FOR PEOPLE
A learner's demo recording is usually a recording of their own profile, and it will contain their name, their photograph and their personal email address. The Repo2Reputation recording did, from frame 60 onwards.
Choose footage windows that land only on placeholder-state frames, then open the highest frame index you actually used and look at it. Re-do this for every subject; it is not a property of the tool, it is a property of the recording.
The voice
Check what is already installed before offering anybody a trade-off. The first cut
shipped with the built-in Windows SAPI voice, presented as "the option that needs no
install", and Ali's verdict was voice is horrible. edge-tts — Microsoft's neural voices
— had been installed on the machine the whole time, so the provisioning gate that made SAPI
look like the only free choice never applied.
Default to en-US-AndrewNeural. Audition two or three first; it takes a minute. Their
personality tags differ and the register matters. The narration text is the caption text
— what is heard and what is read are the same sentence, or you are maintaining two scripts
and they will drift.
The endpoint returns NoAudioReceived intermittently under a burst. That is transient, not
bad input; the retry is already in speak(), so do not remove it and conclude otherwise.
It is NOT an artifact
demo exists in CaseStudyArtifactType and attaching it there is the obvious move. Do not.
It would put a video in the artifacts carousel at a screenshot's aspect ratio and make it
a hero candidate through HERO_IMAGE_PRIORITY — and a video that can win the cover is a
video that can stand in for a screenshot of the running system.
It is its own top-level snapshot section:
applyHumanOverride({ path: 'walkthroughVideo', value: {
url, title, captionsUrl, posterUrl, durationSeconds, narrationSource: 'synthetic',
}})narrationSource: 'synthetic' makes the page say so. An unlabelled synthetic voice is a
small deception and this system's whole claim is that it does not make those.
Four ways this fails silently, all of which shipped
A walkthrough with no audio stream at all. The Selective Service record shipped on 2026-11-05 with a 77-second film built by a one-off script in a scratch directory instead of this toolchain, and nobody noticed for a day. Every other check passed: the URL returned 200,
ffprobereported the intended duration to the frame, the poster drew, the player rendered in the masthead, and the page looked finished. Silence is the one defect a muted autoplaying player cannot show you. So probe the STREAMS, never just the duration, and do it on the file production serves rather than the one you built:ffprobe -v error -show_entries stream=codec_type,codec_name,channels -of csv=p=0 walkthrough.mp4 # must list an audio line: aac,2 (or similar). One video line alone is a silent film.The deeper rule is the one this section opens with: a record without a NARRATED walkthrough is not finished, and
make_narration.pyruns first for that reason. A build that never called it cannot have produced sound, so if the toolchain was bypassed, assume silence until the probe says otherwise.ffmpeg -ssinto an animated GIF. Seeks to 1s and 11.5s worked; a seek to 30s produced a segment with no picture at all and exit code 0. Pull frames by index with Pillow instead.The concat demuxer drops unreadable segments and still exits 0.
ffprobethe finished file and compare against the intended length. Short means a segment was dropped; long means one overran its trim. Never compute the duration.A cross-origin caption track is refused. The
.vttand.mp4are served from the platform while two of the three pages are on other domains, so both needAccess-Control-Allow-Originand the player needscrossorigin="anonymous". Miss it and the video plays perfectly, the.vttreturns200 text/vtt, and the captions simply never appear.HTMLTrackElement.readyState3 is ERROR, 2 is LOADED — it was misread once and reported as working.
docker cp is not a deploy
The video is baked into the nginx image from frontend/public/site-v2/. A copied-in file
survives only until the container is next recreated, which on a box where other sessions
deploy can be nine minutes. It silently reverted a re-recorded narration to the
previous voice while the URL still returned 200 and the right byte count at the moment it
was checked.
Commit the file, merge, rebuild nginx. Verify with md5 against the local file, not a status code: two different videos both return 200.
Done means
- It was built by
scripts/walkthrough-video/, starting withmake_narration.py -
ffprobelists an audio stream on the file production serves, not only on the local build - Every figure spoken or shown is a published metric on the same record
- Every frame used has been checked for a person's name, face or email
-
ffprobeduration matches intended, within a second - The caption track reports
readyState: 2and a non-zero cue count on all three surfaces, not just the same-origin one - The player renders in the masthead and above the fold on all three
- The file was verified live by md5, after an nginx rebuild
8d. The visual story (required): the flow drawn, the figures charted, from the record only
Every record carries a visualStory section on its snapshot: a workflow illustration
(single-state, or Before/After when the before-state is evidenced), up to three outcome
cards, and up to six charts. The public page renders it as one band directly under
the context strip, above the first prose section; when the band shows cards, the strip
prints no headline figure, the measurement section folds its metric cards under "Full
notes on all N metrics" (the figures are already on the page once), and the Mermaid
drawing folds under "View technical proof". The gate refuses a snapshot without one
(visual_story_missing, rule 21): presence and a workflow are required, figures are not.
Every record published before 2026-09-16 was migrated the same day; a record with no
verified outcome carries a workflow-only story and the band says it shows no figures.
§8d is the whole rule set; the rest of this file still applies to every word and figure.
The drawing fits its width. The layout sizes the flow to the canvas it is given and falls back to one column when a step would be unreadable; the page never scrolls sideways for it. Keep labels short (40 characters) and steps few (a panel over about eight columns becomes a column on a laptop); a connection label the drawing has no room for is said in the step panel under "Reached from", so nothing is lost, but a flow that reads only from the panel is a flow with too many steps.
What it is not
- Not a new section key. It carries no
data-section; the surface profiles, the section vocabulary andsectionOrderare untouched. Presence of the section is the flag;enabledplus thesurfaceslist inside it decides which sites show it.surfaceslists every surface the record is published on. Ali, 2026-09-16: "They need to be done for all the published sites." Every site draws the same band: Enterprise in React, aiflotation.com and training.colaberry.com through the framework-free port inpackages/case-study-shell(case-study-visual-*.js, kept equal to the React geometry bystoryVisualShellParity.test.ts; the training site vendors those files verbatim undersrc/vendor/case-study-shell). A story on one surface only is the exception, and needs a reason in the record. - Not a place for a number. Every card is a metric key; every chart anchors on a
metric key; a chart part is a metric key or a literal that carries its own denominator
and an
evidenceIdthe record already holds. The projection resolves each figure from the verified metric at request time, so the story can never disagree with the metrics beneath it. If a cited metric loses verification, the whole story drops, not one card. - Not telemetry. The particles are illustrative, fixed cadence, and the band says so in words. The motion note is part of the section and is claim-scanned like prose.
Where it lives, and the one way to write it
Snapshot content, key visualStory, schema version 1 (backend/src/types/caseStudy.ts,
limits in caseStudyVisual.ts). Authored as a whole section through the override
path, like everything else in §3: applyHumanOverride with path: 'visualStory'
validates it (caseStudyVisualStoryValidate.ts) before any write and refuses with
{path, code, message} per field. It survives sync as a human override; a sync that
changes the sections it was drawn from marks it stale (the Studio shows the badge)
and never regenerates over a person's work.
The Studio's Visuals tab, Visual Story panel is the only authoring surface:
Generate from evidence (POST /api/admin/case-studies/:id/visual-story/generate,
reads only) draws a single-state workflow from the architecture diagram, picks the
headline and comparative metrics as cards, and proposes one chart per ratio or share
metric by its guardrail. Edit the words in the row editors, Preview changes, then
Save. A generated draft is enabled: false on no surface: turning it on is your act.
Chart mapping: the metric's shape decides the chart, never the other way round
| Metric shape on the record | Chart kind | What it needs | What it refuses |
|---|---|---|---|
| ratio or share, parts of one whole | composition |
parts that sum to the denominator (the remainder is named in the table) | a part with no figure |
| ratio, with a "N of M" baseline in the measurement notes | comparison |
both windows as parts, a visible caveat naming the windows |
anything read as a trend; a bar without a denominator |
| ratio or share | share |
the anchoring metric | a literal part without evidence |
| two summary statistics (median and p90, say) | two_value |
exactly two parts, a unit, an axisMax |
a third part; a value over the axis |
| a zero over a real denominator | zero_card |
the anchoring metric at 0 of N | a non-zero anchor; a missing denominator |
No line, no dates on an axis, no kind that reads as a trend: a title containing "trend", "over time", "per week" or "growth" is refused unless the kind is comparison.
Workflow guardrails
- Every node key unique; every edge joins two known nodes; no self-loop; every node
reachable from the initial step (
node_unreachable); at most 16 nodes and 24 edges per panel. Labels 40 characters, sublabels 48, kicker 60, detail 280, evidence 240. - A before panel exists only when the before-state is evidenced. The generator
never invents one; it draws
single_state. Author a Before/After pair by hand and cite where each before-step's proof lives in itsevidencetext. - Roles (
human,system,external,data), statuses (processing,resolved,attention,failure,unknown) and lanes (primary,recovery,manual) are closed lists and render as words as well as colour. - No
<,>,@, URL or control character in any text (§7 applies here too). - A node's
metricKeyshows that metric's verified value beside the step as a tally, with the same verification badge as every other figure.
The gate and the scanner
Blocker visual_story_invalid (rule 20) runs the same validator on every publish and
names up to eight refusals by path. The claim scanner reads the workflow title, caption,
description, motion note, every panel label and summary, every node label, sublabel,
kicker, detail and evidence, every edge label and condition, and every chart title,
caption, caveat, limitation and part label. A percentage in any of those must be
carried by a verified metric on the record (§6), the same rule that forced a
missing_event_rate metric onto the CORA record on 2026-09-15 when "4.2%" appeared in
its prose; a caveat on a chart is prose to the scanner.
Previews
scripts/previewStoryLayout.js renders the band with the rest of the page; pass the
{surface, caseStudy} envelope with the projected visualStory in it. Check 1440,
768 and 390 (pageScrollW === viewportW at all three; the graph is one 360-wide
column below 768 and scrolls inside its canvas at natural size above), and once with
prefers-reduced-motion on: no .cbv2-story-visual__particle, and the pause control
reads "Reduced motion". Every figure is visible as text before any animation: the
cards rest at the final figure until they scroll into view, so a capture taken before
the count-up shows the true wording, never "0%".
Done means
- Every card and chart anchor is a verified, publishable metric on the same record
- Every literal chart part carries a denominator and an
evidenceIdthe record holds - The before panel, if any, cites evidence in its own words
-
readVisualStoryStatereportsvalidation.ok: trueandstale: false - The gate passes with no
visual_story_invalid -
enabled: truewithsurfacesequal to the record's published surfaces (every site draws the band); fewer only with a reason recorded - The rendered band checked at 1440, 768, 390 and under reduced motion
- The hero and the walkthrough video are unchanged
8e. The story: a person, three decisions, a closing, written per surface
Piloted on the CORA record for training.colaberry.com on 2026-09-17, revised twice on Ali's review, then approved as the format for every record ("Let's harden this format"). The visual story (§8d) shows the system; this section is what a reader remembers: who did it, what they chose, what it cost, what it showed.
The arc, in the order the page tells it
person (once) → concrete stakes → the first attempt → the decisions → the complication → the outcome → what it demonstrates. Greenfield work has no earlier failure; never manufacture one. A demonstration stays a demonstration: no prose upgrade to measured impact, and no figure on a card that is not on the record.
Where each part lives, and who orders it
The surface profile places three section keys, decisions, builder and closing
(caseStudySurfaceProfiles.ts; keys in CaseStudySectionKey). Every renderer draws bands
in surface.sectionOrder; a renderer that predates a key ignores it. The placements:
| Surface | decisions | builder | closing |
|---|---|---|---|
| enterprise | right after situation |
after roadmap |
after repositories, before cta |
| training | right after situation |
after roadmap |
after builder, before repositories |
| ai-flotation | right after architecture |
before contributors |
before cta |
Do not move a section by editing a page. Move it in the profile, and every site follows
(caseStudySurfaceLens.test.ts pins the placements).
The words live on the snapshot, per surface, in content.surfaceVariants.<surface>
(CaseStudySurfaceVariant: standfirst, situation, measurementNarrative,
metricNotes, contributors, builder, decisions, closing). resolveSurfaceContent lays the surface's variant over the canonical content
(caseStudySurfaceVariant.ts). A surface with no
variant reads the canonical words; a record with no variants projects byte-for-byte as
before variants existed (caseStudySurfaceVariant.test.ts). A variant never carries a
figure: valueDisplay and payload are not in the type, so the numbers are the same on
every surface and the metric rules still hold.
Publishing one surface without touching the others
applyHumanOverride republishes EVERY live surface of the record. When one surface must
stay pinned (a pilot, a revision under review), compose the same services by hand, inside
the backend container:
applyOverrides(content, [{ path: 'surfaceVariants', value, actor, recordedAt, note }])with the WHOLE map (merge the other surfaces' variants in unchanged);persistCaseStudySnapshot({ status: 'draft', draft: { ..., generatedBy: 'human_edit', contentHash: hashCanonical({ content, sourceCommitMap }) } });approveSnapshot; 4.publishCaseStudy({ surfaceKey })for each surface you mean.
The committed script does all four, and refuses to write until it has shown you the
result: backend/src/scripts/publishCaseStudyVariants.ts (inside the container,
node dist/scripts/publishCaseStudyVariants.js <slug> <variants.json> --surfaces a,b [--apply]).
Without --apply it is a dry run: the gate for every surface over the composed content, the
projection diff of every surface NOT named (must be empty), the story review per named
surface, and each named surface's current published_snapshot_id, which is the rollback
(approveSnapshot(previous) then publishCaseStudy(surface, previous)). It stops if a named
variant names a contributor the record has not consented to, and never writes consent.
--remove <surface> returns one surface to the canonical words, which is the rollback when
the record's identity has changed since the previous snapshot and rule 5 would refuse it.
Record the ids the dry run prints in deployment-log.md before you apply.
The person: facts by class, consent by the record
Four classes of fact, never mixed and never upgraded by generation:
| Class | Example | Where it may appear |
|---|---|---|
| user-confirmed biography | "joined as an intern; hired; now a Forward Deployed AI Engineer" | builder.intro, builder.progression, standfirst; ONLY with the person's name released by consent |
| repository-supported contribution | "built the detection query, the panel, the replay job" | builder.contribution, builder.skills[].evidence; stands under the role title without a name |
| internally measured outcome | "586 of 604 resolved" | metrics, cards, decision figures |
| personal reflection, quotation | anything the person felt or said | NOT on the record until the person supplies it and permits it; there is no field for it |
Consent is a record fact (builder_identity_mode, builder_naming_consent, the
contributor's consentRecordedAt). The author never writes it and never implies it. The
projection releases the name and the biography only when builder.displayName equals a
contributor the consent gate projected as named for that same content; rule 5 refuses a
profile whose name is not such a contributor. Everything else on the card (role title,
organisation, contribution, skills) is a project fact and crosses without a name.
Sparse author. No consented person: the card credits the role. displayName is the
EMPTY STRING (rule 5 refuses any non-empty name that is not a consented contributor, even
though the projection would withhold it; the rollout hit this on three records at once),
intro and progression empty, initials one letter for the role so the mark is not a
blank circle ("L" for a learner, "C" for the Colaberry team), contribution and skills from
the record. That is a valid story: the review prints story_biography_unavailable as a
note, not a warning. Write the gap in the handoff ("no consented author; role credit"); do
not invent a person, a placeholder or a team name the record does not carry. Do not
interrupt Ali for an optional interview.
Names. "Kes" only, never expanded; verify any full name against an approved profile
before it appears anywhere, including links. (The verifier found the repository owner's
GitHub handle inside evidence hrefs of the CORA payload: pre-existing, and on Ali's list.)
The decisions: three cards, each pinned and each closing on a figure
CaseStudyDecision: title, problem, decision, evidence, consequence (all
required; a card missing one is not drawn), stage (the label of a node in the workflow
drawing, e.g. "Detection query"; the card reads "At Detection query"), figure (what the
card closes on, as displayed: "28 Apr", "0", "97%"; the consequence is its caption).
- Three is the number. One choice is a feature; five is a list.
stagenames a node of the drawing the reader has just scrolled past, in the node's own words shortened, so the two can be found together.figureis a value that is on the record: a metric's display value, a date on the timeline, a count in the evidence. A demonstration's cards may close without a figure; the review notes it and moves on.evidenceis one line naming where the claim lives (build timeline, architecture narrative, measurement notes, the two screenshots).- No card repeats the situation. The problem line is the specific fork, not the backstory.
The closing
One paragraph, closing (variant or canonical): what the work shows about the role, the
one or two figures that carry it, and the gaps stated as gaps. Every statement on the
record. Do not write "the gaps made the next priorities clear" when the roadmap marks
them "not pursued". No CTA language; the profile's CTA follows it.
The story in brief (required, added 2026-11-18)
Ali: "the story is so shortened I can't even tell what the story is. Can we create a small
format at the top that tells the story of what happened ... Sometimes the opening paragraph
does a good job explaining and sometimes it doesn't." So every record carries
identity.storyInBrief: 3 to 5 beats, each { label, text }, drawn as "The story in
brief" directly under the masthead on Enterprise and under the outcome tiles on Hire.
- Labels are a few words (32 characters at most). The default arc is Before, What we built, What happened, Why it matters; a fifth beat ("What's next") is allowed.
- Each text is one or two plain sentences (240 characters at most), readable by someone who reads nothing else on the page. Name the business problem, not the code.
- Every figure in a beat must be on the record: beats are claim-scanned like the standfirst.
- All or nothing: one bad beat drops the band, and the audit's record check
the story in brief tells the whole arcfails. Nothing is ever derived from other sections.
Ali, 18 Nov 2026, after seeing it live: "I do like the Story in Brief section." Hardened from the builds of 17-18 Nov (CF1-CF3, GD1-GD2, Internship, Open House). What a good set does:
- Before names the situation a buyer recognizes, in business terms, with its number if it has one: "An audit the next morning found 5 new accounts and nobody had gone in", not "the onboarding flow had a bug".
- What we built is the thing, in one sentence a non-engineer repeats: "One portal from application to cohort", "A weekly funnel report that ... stars the one move". Never a file, a service, a model or the AI tool that wrote it.
- What happened carries the headline figure with its denominator and its comparison:
"66 of 82 new accounts went in, against 0 of 5 before", "8 of 8 admission decisions were
made by a reviewer". A result with no number is a claim. (Audit:
carries no figure.) - Why it matters is the principle a buyer takes away, not a restated result.
- What's next is the honest limit: what has not shipped, what is not measured yet, with
an absolute date when one exists ("Its first grade is due on 25 November"; "Nothing yet
records whether an intern was hired"). This is where the record's
closing.limitlands. - Write the beats LAST, after metrics, closing and the standfirst are final, and copy every figure from the record's own metric or closing. Beats copy figures, nothing syncs them: change a metric and re-read the beats.
- No beat repeats the standfirst, and no two beats say the same thing: the band exists because the opening paragraph sometimes does not tell the story.
- It is not a ticket: no file names, identifiers, URLs, PR or ticket numbers, staff names
(roles only), learner names (none: the byline names the builder, see below). (Audit:
reads like a ticket.) - Writing it on a live record republishes it.
applyHumanOverrideon pathidentitytakes the WHOLE identity:{ ...identity, storyInBrief: beats }, or the rest is erased. RunstoryInBriefProblem(beats)from/app/distfirst and refuse on any problem. - Look at it on both sites, desktop and phone (§8b). Two layout faults shipped on day
one: a page-level
h2rule outranked the band's caption on Enterprise (it printed at 41px in the display face), and on Hire the text dropped below its label when a beat stretched to its row. Both are fixed in the CSS; the check is that the label is caption-size and every text starts directly under its label.
The audit's second check, the story in brief is a story, not a ticket, runs
storyInBriefLint (completenessCore.js) over the beats and the standfirst.
Every live record carries beats. Ali, 19 Nov 2026: "can we add 'The story in brief' to
all the case study's." The whole live catalog (20 records) was backfilled that day from
scripts/case-study-story-in-brief/beats-2026-11-19.json by apply-story-in-brief.js
(dry run by default; refuses an id/slug mismatch, the server's own shape problems, and the
claim scan's vocabulary: percentages, currency, quotation marks, return and production
claims; skips unchanged beats; reports any surface the republish did not reach). To add or
change beats on a live record, edit that file (or a dated successor), run
node --test scripts/case-study-story-in-brief/beats.test.js, then the applier. Lessons
from the backfill:
- Counts, not percentages. The claim scan blocks any percentage a verified metric does not carry verbatim, and a blocked republish leaves the record approved but NOT live. "31 of 66" passes; "47%" did not, on Open House, until the captions were reworded.
- No metric, no invented figure. A record with no metric (your-repositories) labels its third beat Where it stands and says no outcome is measured yet. The test lists it as a named exception; the fix is a verified metric on the record, not a number in the beat.
- Pick the headline a buyer cares about. When a record marks no headline metric, lead with the result (findings kept and rejected, calls scored), not a safety count that reads oddly on its own ("0 of 10 stored queries write ...") - put that second.
- No builder name at all, not even Kes. The beats are one text for every surface, but the
builder is not: Hire names a consenting learner in the byline, Enterprise and Training say
Kes. Ali, 19 Nov 2026, on a Hire page bylined Harpreet Kaur: "the names in your story brief
don't always match the author ... this was built by harpreet but you mention kes". Write the
beats in the passive or about the product ("A tool that ...", "the retries were bounded");
the byline names the builder. The test refuses
Kesin a beat.
One introduction
The standfirst introduces the person once (name, the shortest true progression). The
situation opens on the problem, not the biography. The builder card is the one place the
progression is drawn. story_situation_opens_on_biography and
story_progression_repeated (the review, below) catch the repeats the pilot shipped with.
The compact ending: a THREE-SURFACE contract (approved 2026-09-17)
From "Who built it" down the training page shrank from 4,227 px to 1,871 px at 1440 with nothing leaving the record: the build as a horizontal rail with staggered labels (compact rows under 900 px, never a horizontal scroll), the roadmap as a status board, the architecture's first paragraph and stack with the rest folded, the measurement narrative in one paragraph (two columns at 1100 px and up), "Who built it" standing down when the builder card names the only contributor. Every fold reads "Notes on N of the M ..." so the reader knows what is behind it.
It shipped on one surface and was published on three. The format was built for the
training site and the note here said to port it "when the format reaches" the other two.
Nothing made that happen, so Case Study #2 went live on Enterprise with a 1,274 px dated
list, a 1,034 px roadmap and an empty "Who built it" heading, and on aiflotation.com with
the same lists and the workflow drawn as a stack of boxes. Ali, looking at them: "the
timeline is not on the aiflotation side and I'm not feeling the chart here. It's just not
even close to the same effect. Same thing with enterprise." All three renderers now draw
it (training RecordBands.tsx, Enterprise StoryLowerV2.tsx and StoryArchitectureBand,
AI Flotation packages/case-study-shell/case-study-record.js), and the rule is:
A change to how a story reads is not done until all three surfaces draw it. A page
format is a contract across the training site, enterprise.colaberry.ai and
aiflotation.com, not a feature of whichever one was looked at first. Before calling any
record or format change done, open the rendered page on each of the three and find, by
eye and by selector:
| Marker | Training | Enterprise | AI Flotation |
|---|---|---|---|
| The build as a rail | .cs-rail |
[data-testid="story-build-rail"] |
.cs-rail |
| The roadmap as a board | .cs-next |
[data-testid="story-roadmap-board"] |
.cs-next |
| The long text folded | details.cs-measure-fold |
[data-testid="story-technical-proof"] |
details.cs-measure-fold |
| No empty "Who built it" | band absent | band absent | band absent |
| The flow in lanes at 1440 | horizontal | horizontal | horizontal |
The flow rule behind the last row: layoutWorkflowToFit keeps the horizontal composition
on any desk-width viewport and lets the SVG scale into a narrow canvas, up to 1.6 times
the canvas width, rather than falling back to a column (aiflotation.com's record column is
1,024 px against training's 1,384, which is what stacked it); the shell also lets the band
break out to 1,280 px where the column is narrower. A column at 1440 on any site is a bug.
shellLowerHalf.test.ts runs the AI Flotation renderer against a real projected envelope
and fails without the rail, the board or the fold; storyLowerV2.test.tsx does the same
for Enterprise; the training repository's lowerHalf.test.ts for training. A new band
that changes the format needs a line in all three, in the same PR set.
Vocabulary
No em-dash or en-dash anywhere a reader sees (Ali's rule, all published copy). No editorial bookkeeping in the story: "this revision", "first revision", "review notes", "candidates from the brief" belong in the handoff. No "n/a" in a metric note: say what is true or leave it out. Dates read "28 Apr 2026"; times, when any, Central with the zone written out.
A variant cannot fix a dash in the CANONICAL prose (the situation, the architecture, the
measurement narrative of a record written before the rule). The review names the path
(story_dash @ architecture.narrative[4] on the training-system record, found during the
rollout); the fix is a whole-section override of that section through the same
persist-approve-publish path, republishing only the surfaces the record is on
(publishCaseStudyVariants.ts --canonical <section>=<file> carries it beside the variants).
Scan every record before you call a rollout done: reviewCaseStudyStory per surface prints
the dash paths for the sections it reads.
The review, before Ali reads it
npx ts-node -T src/scripts/reviewCaseStudyStory.ts <slug> [surface] (or
--file <composed content.json>) prints reviewCaseStudyStory's findings and rubric for
the latest approved snapshot. It is advisory and exits 0. Warnings: no builder card, no
decisions, an unpinned card, no closing, bookkeeping, a dash, "n/a" in a note, the
situation opening on the biography, the progression repeated. Notes: role-only credit
(biography unavailable), a card without a figure. The rubric scores six dimensions 0 to 2
with the passage or gap cited (references/story-rubric.md); the ones marked
"editorial" are settled by a person, and no score ever substitutes for a gate.
Done means, per surface
- The dry run's gate is CLEAN for that surface and the other surfaces' projections did not move; the review prints no warning you did not accept in writing.
- The live API for
?surface=<key>carries the builder (name only if consented), three decisions withstageandfigureas authored, the closing, the standfirst. - The live page at 1440, 768 and 390 draws the sections where the profile places them, the
hero and the video untouched, no horizontal scroll, no page error, no "n/a", no dash; a
capture of each new section in the run directory. training.colaberry.com revalidates a
page 60 seconds after a publish: the first request after that serves the old page and
triggers the rebuild (
x-nextjs-cache: STALE), the next serves the new one. Read it twice before calling it wrong. - The handoff names the previous snapshot id per surface, the editorial gaps, and what was not done.
8f. The cover and the video thumbnail: three concepts, Ali picks one
Ali, 2026-09-18, after picking from eighteen concepts for six records: "Replace them as the image for the case studies and the thumbnail for the videos. The old picture can be used as an artifact inside the case study, don't throw it away. Then harden this process so we always find thumbnail pictures for each project like this." He asked for them to look like the thumbnails on videos with millions of views, and to be "very custom and relatable and really pop".
The tools and the step-by-step are scripts/case-study-thumbnails/README.md. The rules:
- Every record gets three concepts before its checkpoint, generated with the newest
OpenAI image model by
generate.jsinsideaccelerator-backend(the key never leaves the container). Three different ideas, not three crops of one: a person reacting, an object or metaphor with no words, a before and after. One face or one object filling the frame, complementary colours, a hook of at most four words. - The hook is a feeling, never a claim. No figure, date, client name, product interface or result in the picture; nothing a reader could take as a measurement. The words come from the record's own tension ("LOST CALLS, FOUND.", "NOT YET."), or the picture carries none.
- Look at every image before Ali does, word by word. The model invents text on
props (a card, a screen, a sign): flag it on the review page (
build_review.pynotes), and if Ali picks it, repaint only that region withedit.jsand paste only that polygon back withfinalize.py composite. The model does not respect the mask on its own. - Ali picks. Nothing reaches a record until he has named the concept. The review page shows every concept at YouTube feed size beside the current covers.
- One 16:9 file serves everything (
finalize.py crop, 1536x864, the top offset chosen so the hook stays in frame): the cover, the index card and the video poster.frontend/public/site-v2/thumb-<name>.jpg, served by an nginx deploy like any asset. - It is a
photo, so it is atmosphere.apply-cover.jswrites it asartifact_type: 'photo',source_type: 'generated', titledIllustration: <what it shows>(the alt text), described fromcover-caption.json, and setsidentity.heroImageUrlandwalkthroughVideo.posterUrlto it in one snapshot. The projection stamps a photoatmosphereand drops one whose caption claims delivered work (DELIVERED_WORK_CLAIMS), so the caption says only what the picture shows. Never type itscreenshotto promote it. - The old cover stays. It is already an approved artifact; once it is not the cover,
the renderers place it in the body, because the cover is the only image they skip.
Nothing is deleted, from the record or from
site-v2. - Every picture once (Ali, 2026-09-18: "do not use the picture a 3rd time inside the
case study ... if the old picture was already being used, then only use it once"). The
thumbnail appears exactly twice: the video's poster in the masthead and the thumbnail on
index and related cards. Never inside the article. Every other picture appears once on
the page: Enterprise counts a cover that is the poster as shown (
StoryDetailArticle) and its artifacts band lists only what the page has not drawn (unshownArtifacts); the AI Flotation and training shell skips the cover and the placed figures in the same band. Check it on the live page by counting each file name amongimgandvideo[poster]. - Only where the record is already live.
apply-cover.jsrepublishes on the surfaces the record is published on and nowhere else; a record that is not live stops at a draft. Its dry run checks the cover resolves, the photo projects as atmosphere, the visual story re-validates after its hash is re-stamped, and every live surface's gate is clean.--applyrefuses until the image URL answers 200.
Done means
- Three concepts generated, looked at, flagged where the model invented words
- Ali's pick recorded in the run directory, in his words
-
thumb-<name>.jpglive with a 200 beforeapply-cover.js --apply - The live API's
heroImageUrlandwalkthroughVideo.posterUrlare the thumbnail - On all three surfaces the masthead poster is the thumbnail and the old cover is in the body, and no picture is drawn twice (the thumbnail not at all) inside the article
8g. The submission PDF — because reviewers do not accept a URL
Partner assessments, RFP response packages and procurement portals take PDF, DOC, DOCX, PPT, PPTX, typically five files at 20 MB. The OpenAI workbook is exactly this shape.
We publish web pages, SVG visual stories and MP4 walkthroughs. Measured 2026-10-02 across the fourteen approved records: nothing we hold is in an accepted format, and the walkthrough video — the single most persuasive artifact we make — cannot be submitted at all.
Every record gets a PDF rendering, built from the sections that already exist:
identity, situation, architecture with its diagram, decisions, measurement with
its charts, and deployment / engagement / governance from §3a.
- Render the published projection, never the draft, so the PDF cannot say something the live page does not.
- The walkthrough video becomes a titled still plus its public URL. Do not pretend a video is in the document; name it and link it.
- Carry the evidence. Each figure keeps the sentence that lets a reader re-derive it. A number in a PDF with no methodology is the format at its worst.
- Name it
<slug>-<YYYY-MM-DD>.pdfand attach it as acase_study_artifactsrow of typesubmission_pdf, so the next person assembling a package finds it instead of rebuilding it. - Check the page count and open the file before calling it done. A PDF that renders blank pages, or clips a chart at the margin, fails silently and ships.
9. Record and snapshot must agree
Overriding identity.title in the snapshot does not update case_studies.title.
The public page then shows one title and the admin list another.
Same for consent: a record with organization_identity_mode: hidden against a snapshot
saying named produces confusing organization_consent blockers.
Use updateCaseStudy for the record row and applyHumanOverride for the snapshot,
and set both. Fields that must match: title, slug, organization identity mode,
organization naming consent, builder identity mode, builder naming consent.
10. The gate
Evaluate through the supported mapping, with an actor:
evaluateCaseStudyPublishGate({
caseStudy: store.toPublishRecord(await store.loadCaseStudyOrThrow(id)),
snapshot: store.toPublishSnapshot(snapshotRow),
surfaceKey: 'enterprise',
})Do not call the gate broken until this exact shape has been tried. It was reported
broken twice; both times the probe passed raw snake_case rows or skipped
toPublishRecord().
evaluateCaseStudyPublication resolves the approved snapshot, not the latest draft.
A stale approved snapshot from a previous subject produces blockers describing content
that is not in your draft — approving the current snapshot clears them.
Blockers naming case_study_not_approved and snapshot_not_approved are the intended
resting state for an unpublished draft.
A record about a student project carries that project's maturity
Two blockers were added on 2026-09-11. They fire when the record is about a student
project, which the gate establishes two ways: case_studies.project_id is set, or the
record has no project_id and one of its cited repositories belongs to a student project
(a stored project_id on the repository row, or an owner/name match in
github_connections). The second route was added on 2026-09-14 because until then
from-repositories skipped the rule entirely, and one live record cited a student's
connected repository that way. A record whose repositories belong to no student project
(the enterprise repo, a stranger's repo) never sees them, which is why the library of
records about our own work was unaffected. When several projects resolve, the least
mature and the most unsettled decide.
| code | what it means |
|---|---|
maturity_below_operational_result |
Nothing has been measured in real use, so this is a build record or a demonstration, not a case study. |
project_truth_has_open_questions |
A story found something that disagrees with what the student confirmed, and nobody settled it. The project's truth disagrees with itself. |
The ladder is computed on every read and is never stored, so no column edit can promote a record:
story_hypothesis an interview happened; nothing built
build_record a story verified from the repo, or a story that reported what it built
capability_demonstration a verified story AND something it points at as "watch it work"
operational_result NOT REACHABLE from a build. Needs an outcome measured in use.
impact_case_study NOT REACHABLE from a build. Needs that, confirmed by the client.computeMaturity cannot return the bottom two rungs of that list. That is deliberate: the
line between "we finished building it" and "it worked for someone" is drawn in code
rather than left to an author's judgement, and the publish gate refuses everything below
operational_result.
So a passing build is not a case study. If the linked project has no measured outcome, do not try to write around the blocker. Either the outcome exists and belongs on the record as a verified metric, or the record is a build story and stays unpublished.
Read the foundation before you author a linked record
GET /api/portal/sbp/intake/:projectId/case-study-foundationRead-only, participant-scoped, and it answers publishable: false on the wire because
nothing on the student side can publish. It returns four sections that must stay apart
in whatever you write:
| section | what it holds | where it comes from |
|---|---|---|
hypothesis |
what the student SAID they would build | the project's truth revision |
buildEvidence |
what the stories SHOWED | repo_evidence facts, plus a per-story ledger |
demonstrationEvidence |
what a story POINTED AT | a test, a file, a URL |
outcomeEvidence |
what was MEASURED in use | empty by construction until an approved measurement definition exists |
It also carries maturityReason and nextRungNeeds in plain words, which is the fastest
honest answer to "why can I not publish this yet".
Blurring those four is how "the tests pass" becomes "the client saved 40%". A repo can
prove what was built; it cannot prove what the business wanted, what hurt before, or what
success meant. The truth contract refuses repo_evidence outright on success_definition,
desired_outcome and pain_points for exactly that reason, so a fact filed under those
dimensions came from a person, never from a commit.
Hardening — what is prevented, and what is only remembered
Audited 2026-09-13 against the source and extended 2026-09-16. 21 blocker codes run on
every publish, and every path to a live page goes through them: publishCaseStudy is
called from exactly two places, caseStudyAdminRoutes and caseStudyAdminReview, and
nothing writes case_study_publications directly. The gate runs on a repeat publish of
an already-live record too, so consent withdrawn between two clicks is caught.
Prevented in code
| Failure | The guard |
|---|---|
| A record goes live on a surface it was never meant for | surface_not_publishable, checked before anything else |
| A draft or an unapproved snapshot reaches a reader | case_study_not_approved, snapshot_not_approved — the intended resting state of a draft |
| An organisation or a builder is named without consent | organization_consent, builder_consent, checked against the record row AND the snapshot, which must agree |
| A private repository is exposed | private_repo_exposed on the structured path, and again on identifiers typed into prose |
| A figure claims "verified" on the strength of a self-report | self_attested_verification |
| A "verified" figure has no evidence behind it | proof_metadata_missing, which also demands a baseline, sample or methodology |
| A metric nobody has verified is on the page | metric_pending, applied only to figures a human promoted with publishable |
| A model's words are published as a quotation | ai_generated_quote |
| An outcome or ROI claim appears in prose with no metric behind it | unverified_claim |
| A shaped figure disagrees with itself | metric_shape_payload_mismatch, metric_ratio_missing_denominator, metric_members_count_mismatch |
| A figure is computed at a commit the record is not pinned to | metric_collected_sha_mismatch |
| A build record is published as a case study | maturity_below_operational_result — on a record linked to a student project, or one whose cited repository belongs to one |
| A record is published while the project's truth contradicts itself | project_truth_has_open_questions |
| An inventory count stands in the headline | headline_metric_is_a_bare_count |
| A headline figure never says what it does not tell you | headline_metric_missing_plain_answers |
| A new blocker ships with nothing that triggers it | The coverage sweep in caseStudyPublicationService.test.ts asserts every declared code is emitted by some fixture, and fails CI otherwise |
| A blocker an admin cannot act on | Every blocker must carry a field, a remedy, and a message that is not the code restated. Also a test |
| A high readiness score authorising a publish | Readiness is advisory and reported beside the decision, never consulted by it. There is a test named for it |
| A record with no visual story reaches a reader | visual_story_missing (rule 21, since 2026-09-16): a snapshot with no story, or a story that draws no workflow, is refused with the Studio's Generate-from-evidence remedy. Figures are not required; presence and a flow are |
| A visual story that stopped being true | visual_story_invalid (rule 20): the same validator the save runs, so a metric that lost its verification after the story cited it refuses the publish and names the field |
| A builder profile names a person the record has not released | rule 5 (builder_consent, extended 2026-09-16): a profile whose displayName is not a named, consented contributor of the same content is refused; the projection withholds the name and the biography on the same condition (projectBuilder) |
| A variant says something on a surface it should not | rule 5 refuses a variant keyed on a non-publishable surface; resolveSurfaceContent applies a variant to its own surface only, and a record with none projects byte-identically (caseStudySurfaceVariant.test.ts) |
| An unbacked figure hides inside a variant, a card or the closing | the claim scan (collectNarrative) reads every variant string, every decision card string (stage and figure included) and the closing, canonical and per surface |
| A story section drawn in a different place on each site | the surface profile places decisions, builder and closing; renderers follow sectionOrder (caseStudySurfaceLens.test.ts pins the placements) |
Prevented only by someone remembering — the useful half
§5a lived here for months. "At least one metric must COMPARE, not just COUNT" was true, written down, and enforced by nothing, so the readiness score went up while the card row stayed wrong. It moved into the table above on 2026-09-13, after all fourteen published figures on the three live records turned out to be inventory. That is what this list is for: everything below can drift the same way.
- Whether the record is worth publishing at all. The gate can prove a figure contradicts itself. It cannot tell you the story is dull, the narrative is padded, or that the record answers a question nobody asked. On 2026-09-13 a set of figures measuring the platform's own task-auditing passed every rule here and was still wrong, because nothing in code asks "would a reader care".
- The cover image, and every other image. §8 says start them on day one. The gate contains zero references to images; a record with none publishes cleanly.
- The walkthrough video. §8c says every record gets one. Nothing enforces it, and nothing checks that what the narration counts still exists on the page — the caption promised "the verified metrics recorded below" on three records that had none until the string was made conditional on 2026-09-13.
- Looking at the rendered page. §8b exists because six layout failures shipped past green tests. No rule can replace opening it.
- Diagrams with no angle brackets (§7), whole-section authoring (§3), and working the entire candidate list (§5). All three are prose.
- That a record with no figures says why. Removing a bad card is enforced; writing the sentence that explains the silence is not.
- That the visual story tells the truth about the flow. The validator (§8d) proves
the graph is connected and every figure is a verified metric; it cannot tell whether
the arrows run the way the system does, or whether a "before" ever happened. That is
read off the evidence, by a person, before
enabledis set. - That the story reads as a story.
reviewCaseStudyStory(§8e) warns about the shape (no person, no decisions, an unpinned card, no closing, bookkeeping, a dash, the biography repeated) and scores six dimensions; it cannot tell whether the stakes are real to the reader or the complication honest. Those are read by a person, withreferences/story-rubric.mdopen, before Ali reads it. - That the compact ending stays compact. Nothing measures the height of the page. The rail, the board and the folds are code; the discipline to keep the narrative to one paragraph is not.
- That the skill and the gate agree. §8e once said a role-only card's
displayName"may be anything"; rule 5 said otherwise and blocked three records in one dry run. The gate was right.skillStoryRules.test.tsproves the checks §8e names exist; it cannot prove the prose describes them correctly. When a dry run contradicts this file, the dry run wins, and this file changes the same day. - That a format reaches every surface. The rail, the board and the folds are now
tested on the two renderers this repository holds (
shellLowerHalf.test.ts,storyLowerV2.test.tsx) and the third lives in the training repository. No test can see across the two repositories, so a NEW band still has to be added three times by a person who remembers to. The §8e marker table and the §8b checklist line are that memory; the live render on all three sites before calling it done is the check. - That every record gets a picked thumbnail. §8f is a step in this skill, and
apply-cover.jsrefuses the ways a cover goes wrong (a dead URL, a caption the projection would drop, a cover that does not resolve, a gate that is not clean). Nothing refuses a record published WITHOUT one: the gate still accepts a screenshot cover, on purpose, so a record is never blocked on a picture. The checklist in §8 is what remembers it.caseStudyCoverThumbnail.test.tspins the parts that can drift: the caption against the claim list, the explicit cover winning over a screenshot, and the tools this section names.
When you add a rule here, decide which half it belongs in before you write it. A rule in the second half is a rule with a half-life.
11. Verify, then report with denominators
The visual story is on the snapshot and validates (§8d):
readVisualStoryStatereportsvalidation.ok: true,stale: false; the gate lists neithervisual_story_missingnorvisual_story_invalid. Without this the record cannot publish.Override survival: re-sync and confirm each section held. Should report
unchanged.backend/node_modules/.bin/tsc --noEmit— never barenpx tsc(resolves 4.9.5).npx jest src/services/caseStudy src/types src/routes/admin src/scripts.Every shaped metric agrees with itself. The gate blocks four disagreements, and each is worth checking before you get there: a payload that does not match its declared shape, a ratio or share with no denominator, a member list longer than the total it is counted against, and a figure computed at a commit the record is not pinned to.
Every shaped metric has its three plain-language answers. The readiness report warns (
metric_plain_missing) and costs no points, so nothing forces this. Write them anyway; the picture makes a reader more confident, which is exactly when the third block matters.Every collected metric has exactly one evidence row, written by the sync. Two rows for one figure can disagree.
If the record is linked to a project, run the gate and read the two maturity blockers as answers rather than obstacles: below
operational_resultmeans no outcome has been measured, and an open question means the project's truth contradicts itself. Neither is cleared by editing the case study.Regression: other records unchanged, public index count,
/case-studiesand/demo-dayredirects.The completeness audit (§12) exits 0, or every remaining row is ACCEPTED with a reason you repeat in the report. Paste its verdict line.
Report denominators, never impressions. Not "the detail page renders" but: sections authored X of X · candidates investigated X of X · metrics verified X of X · metrics that compare X of X (§5a) · metrics computed by a collector X of X · shaped metrics with plain language X of X · artifacts X · images X · timeline entries X · prefixes X · walkthrough video X seconds, cues loading on X of 3 surfaces · visual story: cards X, charts X, steps X, enabled on X surfaces, gate rule 20 clean (§8d) · completeness audit: gaps X, thin X, accepted X (each with its reason), record checks failed X, against references <the five slugs> (§12).
Never say complete, production-ready or published without evidence for each claim.
12. The completeness loop: loop-architect inside the skill
Why. The skill lists what a record needs in prose, and prose is skimmed. The published records are the ground truth of what a finished record carries. Every build until 2026-11-17 reached Ali with something missing: no video, no screenshots, no surface variants, or a field the skill named but the author skipped. Ali had to send it back with "look at the skill". The loop moves that check from Ali to a script and a grader.
The audit
The command is scripts/completeness-audit.js. Its pure logic is in scripts/completenessCore.js,
and its tests are in scripts/completenessCore.test.js; run them with
node --test .claude/skills/build-case-study/scripts/. The audit is read-only and runs inside
accelerator-backend:
ssh root@95.216.199.47 "mkdir -p /tmp/csaudit && docker exec accelerator-backend mkdir -p /tmp/csaudit"
scp completenessCore.js completeness-audit.js root@95.216.199.47:/tmp/csaudit/
ssh root@95.216.199.47 "docker cp /tmp/csaudit/completenessCore.js accelerator-backend:/tmp/csaudit/ && docker cp /tmp/csaudit/completeness-audit.js accelerator-backend:/tmp/csaudit/ && docker exec -w /app accelerator-backend node /tmp/csaudit/completeness-audit.js <caseStudyId> --surfaces=enterprise,hire"- References: the 5 most complete records that are live on some surface (live means approved). They are ranked by fields present, then surfaces, then recency, and the record under audit is never one of them. The audit prints their slugs; open one when a gap is unclear and copy its shape.
- GAP: a field that at least 3 of the 5 carry and the draft does not. The audit reads depth 1 and 2 of the snapshot, plus derived checks that a key alone cannot show: open images, a cover that is an artifact, a video with captions, metrics with all three plain answers, metrics with limitations, and decisions pinned to evidence.
- THIN: a list shorter than every reference's. For example, a visual story on 1 surface when every reference has at least 2.
- Record checks:
- A confirmed service link.
- For a Colaberry-team record, a
project_id, so Hire can list it. - The cover is a picked
photoartifact (§8f). - The pure gate passes on each surface, given the service-link AND hire facts. Never use the bare gate, which reports false blockers.
- The story review raises no warnings.
--accept=<path>:"<reason>": for a field a person has ruled not applicable to this record. An example is nosurfaceVariants.trainingon a record that must never reach the training site.- Accepting a field accepts its children.
- On a role-only record,
builder.displayNameis accepted automatically (gate rule 5). - Each acceptance is printed with its reason, and the reason goes in the report. It is never a way to finish sooner.
- Exit codes: 0 complete, 2 something to fix, 1 error.
The loop
Run the build under /loop-architect (.claude/skills/loop-architect/SKILL.md). The run
directory is .loop-architect/runs/<timestamp>-case-study-<slug>/. Its phases map onto this
skill like this:
| loop-architect | in this skill |
|---|---|
| A. Discover | §0 preflight, §1 path scope |
| C/D. Contract and plan | §2 creates the draft. Then run the audit on the empty draft: every GAP and THIN row and every failed record check becomes a task in plan.md, beside §4 to §8g. Nothing the references carry can be left out of the plan. |
| E. Plan audit | loop-plan-auditor must score 18 of 20 or better, and the plan must name a task for every audit row |
| F. Execute | One section or asset per task. After each task, re-run the audit. loop-task-verifier grades the task using the audit output and the gate as its fresh evidence. A task passes only if its rows turned ok and nothing else regressed. |
| G. Quality gate | The audit exits 0 (or its remaining rows are ACCEPTED with reasons), plus the §8b rendered-page check and the §11 list |
| H/I. Deploy and verify | Assets deploy through deploy-prod.sh, then loop-production-verifier reads the live surfaces |
| J. Handoff | The §11 report, with the audit verdict pasted in |
The limits are loop-architect's: 3 attempts per task, and 3 cycles of the audit with no progress. If the same row is still a GAP after 3 cycles, stop. Show the row and why it cannot be filled, and ask Ali one lettered question. Never accept it on his behalf.
Run the audit before every report to Ali. If you are about to say a record is ready for review and you have not pasted a verdict line from this session, you have not checked.
What it does not judge
The audit checks that the parts exist and that no list is thinner than every reference's. It
cannot tell a good decision card from a bad one, or a truthful metric from a convenient one,
so §5, §8e, the story rubric and Ali's review still apply. It also does not run the
foundation facts of a linked student project: run evaluateCaseStudyPublication once that
snapshot is approved.
Reference: the two records built with this
| training system | tickets reconciler | |
|---|---|---|
| readiness | 89 | 91 |
| metrics / headline | 4 / 1 | 6 / 3 |
| evidence rows | 15 | 12 |
| contributors | 0 | 2 |
| artifacts | 3 | 2 |
| images | 3 | 0 ← the live gap |
| walkthrough video | added later | added later |
| metrics with methodology + limitations | 4 of 4 | 6 of 6 |
| visual story (§8d) | workflow only, no verified outcome | workflow only, no verified outcome (pilot with figures: CORA, 2026-09-16) |
The tickets record scores higher on rigour and lower on pictures. Both patterns are worth copying in one direction only.