Golden examples

🌐 繁體中文（canonical） · English mirror

Golden examples (golden-examples) — skeleton

This is the skeleton version. A golden-examples library's whole value is "your own real adjudications" — someone else's samples can't set your tone — so this file keeps only the mechanism (usage, intake rules, format) and leaves the content of §1–4 blank for you to fill.

Usage: before you write, read the matching section and imitate the shape of the "after." Every example carries a judgment point — the part a rule can't state, that you can only absorb from an example. The "before" should come from real history, not a straw man.

Every example below is a <placeholder>, marked "(illustrative — replace)". Replace them with adjudications you receive in real tasks — before your first intake, delete that section's illustrative example.

1. Commit message

One line: the reader of a commit message is "the person running git blame three months from now"; verb + object + purpose is what makes it searchable.

Format illustration (replace)

• Before: <the original commit message the user rejected, e.g. "update code">
• After: <the version the user approved, e.g. "refactor: normalize module X's verbose comments to one style">
• Judgment point: <the principle from this adjudication that transfers to next time — one sentence>

2. UI copy (this skill's primary scenario is Japanese copy — see frontmatter)

One line: UI text must fit the target language's native idiom; error messages are two-part (what happened + what the user can do), and the error code goes to the log, not the screen.

Format illustration (replace)

• Before: <the original string that reads machine-translated or colloquial>
• After: <the idiomatic version the user changed it to>
• Judgment point: <transferable principle, e.g. "labels use noun + verb; avoid katakana transliteration">

3. Code review comments

One line: a comment has three elements = location + failure scenario (what input → what bad result) + suggestion; a comment that can't state a failure scenario is downgraded to a nit or dropped.

Format illustration (replace)

• Before: <vague comment, e.g. "this could be strengthened">
• After: <concrete comment, e.g. "file:line only logs after catch and doesn't notify the caller; on failure the user sees a spinner that never stops; suggest returning Result to the upper layer to show an error state">
• Judgment point: <transferable principle>

4. Completion report to the user

One line: a report has three elements = what you did + machine evidence (compile/test output, read-back) + change scope; an evidence-free "it should work" is forbidden.

Format illustration (replace)

• Before: <evidence-free report, e.g. "changes complete, it should work now">
• After: <report with evidence, e.g. "added the setting, release-level compile passes (last 5 lines of output below), touched a single config file">
• Judgment point: <transferable principle, e.g. "conclusion first, detail after; 'complex' and 'in theory' are hedging words — their presence means you haven't finished verifying">

5. Intake rules (log the adjudication as it happens)

Every time the user makes a taste call (picks an option, changes wording, rejects a design, corrects tone), before wrapping up append a precedent to the matching section (open a new one if none fits):

• File only when all three elements are present: Before (the real original, no straw man) / After (the version the user adjudicated) / Judgment point (a transferable principle).
• If the judgment point yields no transferable principle → it's a one-off preference, don't file it.
• On intake, check for contradiction with an existing precedent; a contradiction = taste drift — keep the new one, delete the old, and note the date.