tune-house-style

Generated descriptions read in a generic voice until they are calibrated to how the institution's cataloguers actually write. This skill closes that gap. It collects a handful of the institution's finished, approved records, derives the house style from them, writes that style into the application profile's description_style (the canonical home that fills the prompt's {{DESCRIPTION_STYLE}} and {{HOUSE_STYLE_EXAMPLES}} placeholders), saves a new owned prompt version in the institution's overrides/ with a changelog note, re-runs one sample item, and shows the cataloguer the old and new descriptions side by side.

It tunes the description field, which is free-text and where house voice lives. It does not retune controlled-vocabulary fields; those are governed by controlled_vocabularies in the profile and resolved deterministically in stage 5.

Where it sits in the pipeline

This is a stage 4 (generation) tuning operation, run inside the improvement loop's refine step (step 5 in ../../docs/the-improvement-loop.md). It changes how the generation prompt produces the description field and then exercises stage 4 on one item to show the effect. It does not touch intake, authority resolution, review, or export.

A house-style change is usually a domain customization: it encodes one institution's voice, so by the generalizable-versus-domain test it stays in the institution's owned instance. The profile's description_style lives in the adjacent workspace already, and the tuned prompt version this skill produces lands in the workspace's overrides/ rather than the shared prompts/system/. A run composes shared assets plus local overrides with local winning, so the overrides version is the one that executes. The exception is a change that improves the prompt's default style guidance for any collection (for example, a clearer instruction to describe what is visibly present without interpreting intent); that generalizable mechanism is extracted and contributed upstream as a separate PR against prompts/system/, while the institution-specific wording stays local. Decide this explicitly and record it; see ../../CONTRIBUTING.md.

When to run it

• Early in the loop, once a first sample exists and the cataloguer can see that generated descriptions read longer, more interpretive, or in a different register than the institution's own records.
• Whenever review feedback clusters on the description field for register or length rather than for factual error (a calibration miss, not a content miss).
• When onboarding a new collection whose descriptive conventions differ from the rest of the institution's holdings.

Inputs

• Exemplar finished records. Five or so of the institution's own approved descriptions, the more representative the better. They live in the adjacent workspace (the path the profile's description_style.examples_path points at, by convention context/exemplar-records/). These are finished catalog records, not first-pass draft output.
• The application profile (application-profile.json in the adjacent workspace), conforming to ../../schemas/application-profile.schema.json. Its description_style block is the canonical home of the house style; see ../../docs/application-profiles.md.
• The current generation prompt (../../prompts/system/metadata-generation.v1.md), whose {{DESCRIPTION_STYLE}} and {{HOUSE_STYLE_EXAMPLES}} placeholders are filled from that block.
• One sample item already generated in a prior run, so a clean before-and-after is possible. Its existing record conforms to ../../schemas/metadata-record.schema.json.

Outputs

• An updated description_style block in application-profile.json: guidance rewritten to match the exemplars, examples_path pointed at the exemplar set, and max_length_words set if the records imply a cap.
• A new owned prompt version file in the adjacent workspace's overrides/ (for example overrides/prompts/system/metadata-generation.v2.md), with the internal version incremented and a changelog entry recording what changed and why. The prior version stays in place; records that cite it remain reproducible.
• A re-generated record for the sample item, conforming to the metadata-record schema, with provenance.prompt_version stamped to the version that actually ran.
• A before-and-after view of the description field for the cataloguer to judge.

Steps

1. Read the exemplars and the current style. Read the five or so finished records and the profile's current description_style.guidance. Characterize the house voice concretely: sentence count, length, tense, person, whether it states only what is visibly present or interprets intent or mood, how it handles uncertainty, and any recurring phrasing conventions. Name the specific gaps between the exemplars and the current generated output.
2. Draft the revised style guidance. Write description_style.guidance as a short, operational instruction a generator can follow, grounded in the exemplars. Set max_length_words if the records imply a cap. Keep it about the description field only.
3. Update the application profile. Write the revised block back into application-profile.json. Set description_style.examples_path to the exemplar set so the generator gets the records for few-shot calibration through {{HOUSE_STYLE_EXAMPLES}}. Validate the file against ../../schemas/application-profile.schema.json. This block is the canonical source; the prompt receives it through its placeholders.
4. Save a new prompt version, owned and local. Copy the current effective prompt to the next version file in the adjacent workspace's overrides/ (for example overrides/prompts/system/metadata-generation.v2.md), increment the internal version, and add a changelog entry naming the house-style change, the institution, and the reason. The institution's specific voice rides in through {{DESCRIPTION_STYLE}} and {{HOUSE_STYLE_EXAMPLES}} from the profile, so the override usually carries the version bump and changelog rather than institution-named wording in the body. Keep the tuned version in overrides/, not in the shared prompts/system/, because it encodes one institution's voice; a run composes shared plus local with local winning, so this is the version that executes. If, and only if, the change sharpens the prompt's default style guidance in a way that holds for any collection, extract that generalizable wording and open a separate PR against the shared prompts/system/; that is the only path by which the commons gets a new version. A new version is warranted whenever the change alters what the prompt produces, so records stay attributable to the exact prompt that made them.
5. Re-run the sample item. Run stage 4 for the one sample item against the updated profile and the new prompt version. The generation model is the profile's model.generation. The re-generated record carries provenance.prompt_version set to the effective composed prompt, which is the overrides version when one exists, plus a fresh generated_date. Re-running a single item is cheap and isolates the style change; it is not a measured loop round.
6. Show before and after. Present the description field old and new, side by side, for the same item, plus the one-line changelog note. Let the cataloguer judge whether the new voice matches house practice. Confidence, basis, and the controlled fields are unaffected by a description-style tune; say so rather than implying the whole record changed.
7. Hand off. If the cataloguer approves, the new overrides prompt version becomes the one the next run composes and uses, recorded in the run manifest's prompt_versions (../../schemas/run-manifest.schema.json) as the effective prompt id. To confirm the style change actually moves the description pass rate rather than just one item, run a measured loop round on a sample (compute-pass-rate) before scaling. Classify the change generalizable or domain per the section above and route it accordingly: the institution's voice stays in overrides/, and any generalizable default-style sharpening goes upstream as a separate PR.

Usage example

This is sample-user-prompt #2 from the initiative's operator curriculum, the few-shot calibration exercise:

Here are five of our existing finished records (paste or point to context/exemplar-records/).
Our cataloguers write shorter, more neutral descriptions than the current output,
one or two sentences, present tense, no interpretation of mood or intent. Update the
description style to match these examples, save the prompt as a new version with a note
in the changelog, re-run item tel_0001, and show me the old and new descriptions side by side.

Run against this, the skill: reads the five exemplars and characterizes the shorter, neutral, present-tense voice; rewrites description_style.guidance and sets max_length_words in application-profile.json and points examples_path at context/exemplar-records/; copies the generation prompt to the next version with a changelog entry recording the house-style calibration; re-runs stage 4 for tel_0001 against the new version; and shows the description field before and after for that item with the changelog note.

Notes

• The house style is one institution's voice, kept in that institution's profile and exemplars. It is not a Notch8 setting and not hidden anywhere; it is visible, version-controlled text the institution owns and edits.
• The exemplars carry the calibration. Pointing examples_path at the institution's own approved records is the most direct lever on register and length; prefer adding or sharpening exemplars over writing longer prose in guidance.
• This tunes free-text description only. To change which controlled vocabularies apply or how authority candidates are proposed, edit controlled_vocabularies in the profile and use resolve-authorities; do not encode vocabulary rules in the description style.