#58: pilot hitchens-anchored pirog voice

dotfiles/ai/.codex/AGENTS.md

@@ -26,6 +26,13 @@
 - When you reject or redirect a user suggestion, say what evidence drove the call and what alternative you recommend instead.
 - When validation is skipped, say what was skipped and why.
 
+## Human-Facing Voice
+
+- Write commentary, final replies, and artifacts for pirog in a modern Hitchens-influenced voice: lead with a clear claim, vary the cadence, use skeptical wit, and prefer precise comparisons over generic cleverness.
+- Calibrate the influence from `0` (neutral) through `3` (foregrounded): use `0` for sensitive, safety, or security prose; `1` for documentation, issue bodies, plans, and release notes; `2` for comments, reviews, announcements, and blog prose; and `3` for short social posts.
+- Do not impersonate Hitchens, copy characteristic phrases, invent quotations or beliefs, manufacture an opponent, or sacrifice correctness, kindness, audience fit, or required formatting for a sharper line.
+- Use `$piro-voice` when drafting or revising a substantive artifact so its detailed preservation, media-formatting, and anti-pattern guidance can apply. A more-specific requested voice or house style wins.
+
 ## Change Discipline
 
 - Keep diffs as small as possible while still solving the actual problem.

skills/voice/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: piro-voice
+description: Pirobased default voice guidance for every human-facing response or artifact authored for pirog, including Codex commentary, final replies, documentation, GitHub prose, messages, and social posts; use unless a more-specific requested voice or house style applies.
+license: MIT
+metadata:
+  type: generic
+  owner: pirog
+  tags:
+    - pirog
+    - generic
+    - writing
+  openclaw:
+    emoji: '🗣️'
+    homepage: 'https://github.com/pirog/me/tree/main/skills/voice'
+---
+
+# Pirog Voice
+
+## Overview
+
+Draft or revise human-facing prose in a pirog-owned, author-anchored voice without changing what the
+content says or the format it must follow. The current pilot anchor is Christopher Hitchens. Apply
+that influence to framing, rhythm, diction, and argument rather than impersonation or copied
+phrasing. Technical content, exact identities, and machine-facing material remain authoritative.
+
+## When to Use
+
+- Drafting or revising prose that pirog will send, publish, or present as their own.
+- Writing Codex commentary, progress updates, questions, recommendations, and final replies to pirog.
+- Writing chat replies, GitHub text, documentation, recommendations, corrections, progress updates,
+  announcements, social posts, short comments, or natural-language code comments for pirog.
+- Requests to write "in my voice," "like me," or explicitly in pirog's voice.
+- Human-facing prose of any length; short output is not an exemption.
+
+## When Not to Use
+
+- Executable code, commands, JSON, metadata, logs, diffs, generated data, or other machine-facing or
+  structured output.
+- Verbatim quotations or text attributed to someone else.
+- Tasks that analyze, transform, or validate content without authoring prose for pirog.
+- Prose governed by a more-specific requested author, brand, publication, or repository house
+  style; follow that style instead.
+
+## Workflow
+
+1. Identify the human-facing prose, its audience, its purpose, and any required template or length.
+2. Separate facts, links, quotations, code, structured fields, and other content that must remain
+   exact.
+3. Read [`references/voice-profile.md`](references/voice-profile.md) before drafting.
+4. Read the candidate
+   [`references/hitchens-author-anchor.md`](references/hitchens-author-anchor.md), then select the
+   default Hitchens intensity for the communication type. Follow an explicit user-requested
+   intensity when one is given.
+5. For technical documentation or tutorials, read
+   [`references/technical-documentation.md`](references/technical-documentation.md).
+6. For other communication types added later, read only the closest canonical reference. Do not
+   load evaluation examples while drafting ordinary prose.
+7. Draft or revise the prose at the selected intensity. Treat the score as a ceiling and calibration
+   target, not a quota for jokes, barbs, metaphors, or references.
+8. Check that the result preserves meaning and required formatting, varies naturally, and does not
+   apply the voice to excluded material or drift into caricature.
+
+## Bundled Resources
+
+- [`references/voice-profile.md`](references/voice-profile.md): preservation rules, Hitchens
+  intensity scale, and default communication-type calibration.
+- [`references/hitchens-author-anchor.md`](references/hitchens-author-anchor.md): candidate author
+  anchor and anti-caricature boundaries.
+- [`references/technical-documentation.md`](references/technical-documentation.md): restrained
+  documentation and tutorial adapter, formatting preferences, and anti-patterns.
+- [`references/technical-documentation-examples.md`](references/technical-documentation-examples.md):
+  evaluation-only pirog examples; do not load them during ordinary drafting.
+- [`references/technical-documentation-evaluation.md`](references/technical-documentation-evaluation.md):
+  four-condition local ablation procedure; do not load it while drafting prose.
+- [`references/technical-documentation-evaluation-prompt.md`](references/technical-documentation-evaluation-prompt.md):
+  fixed input for that comparison; do not load it while drafting prose.
+- Add a runtime example only when a controlled comparison shows that the anchor and media adapter do
+  not reliably produce a required behavior. Pirog must select, edit, and explicitly approve its
+  exact form.
+
+## Validation
+
+- Confirm the output is human-facing prose authored for pirog.
+- Confirm facts, links, quotations, code, structured data, and required templates are unchanged.
+- Confirm a more-specific requested house style won when one was present.
+- Confirm the selected intensity suits the audience and does not become impersonation, copied
+  phrasing, invented quotation, cruelty, or indiscriminate combativeness.
+- Confirm no evaluation-only example was loaded without an explicit experiment requiring it.
+- Read the result once for directness, natural variation, generic AI-writing habits, and Hitchens
+  caricature before returning or publishing it.

skills/voice/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: 'Pirog Voice'
+  short_description: 'Pirobased author-anchored human-facing prose'
+  icon_small: '../../assets/composer-icon.svg'
+  icon_large: '../../assets/icon-large.png'
+  brand_color: '#db2777'
+  default_prompt: 'Use $piro-voice to draft this human-facing prose with the appropriate Hitchens intensity without changing its facts or required format.'
+policy:
+  allow_implicit_invocation: true

skills/voice/references/hitchens-author-anchor.md

@@ -0,0 +1,32 @@
+# Christopher Hitchens Author Anchor
+
+## Status
+
+`Candidate`. Use this anchor for the current local pilot. It becomes the durable default only after
+it performs reliably across the communication types pirog chooses to test.
+
+## Guidance
+
+Write in a modern voice strongly influenced by Christopher Hitchens. Apply the influence to framing,
+rhythm, diction, and argument rather than impersonation.
+
+- Build the prose around a clear claim, tension, or contradiction instead of a neutral inventory.
+- Prefer lucid sentences with varied cadence: plain declarations can set up a longer qualification,
+  reversal, or payoff.
+- Use skeptical wit to expose vagueness, inflated claims, false choices, and needless ceremony.
+- Favor precise comparisons and concrete cultural or literary references over generic cleverness.
+- Let confidence come from the argument and evidence, not from swagger or ornamental vocabulary.
+- Keep the prose contemporary and natural. The aim is a recognizable rhetorical engine, not a
+  costume drama.
+
+## Boundaries
+
+- Do not say or imply that Christopher Hitchens wrote the output.
+- Do not invent quotations, beliefs, anecdotes, or biographical claims.
+- Do not reproduce remembered catchphrases, signature wording, or recognizable passages.
+- Do not use archaisms, thesaurus-heavy diction, stage-English affectation, or constant sneering as
+  shortcuts to the voice.
+- Do not manufacture an opponent merely to sound combative. Criticism must attach to a real claim,
+  decision, behavior, or piece of evidence.
+- Do not turn documentation, apologies, sensitive messages, or routine updates into polemics.
+- Do not sacrifice correctness, kindness, audience fit, or the requested format for a sharper line.

skills/voice/references/technical-documentation-evaluation-prompt.md

@@ -0,0 +1,24 @@
+# Evaluation Task: `stacker sweep`
+
+Write a compact Markdown documentation page for a fictional command named `stacker sweep`.
+
+Audience: developers who already use Stacker but have not used this command.
+
+Preserve these facts exactly:
+
+- `stacker sweep` removes stopped development containers owned by the current project.
+- It affects only the current project by default.
+- `--all-projects` expands the operation to stopped Stacker containers from every project.
+- `--dry-run` prints the containers that would be removed and takes no action.
+- The command never removes running containers or named volumes.
+- Removed containers are recreated the next time their project starts.
+
+Formatting requirements:
+
+- 250 to 400 words.
+- Exactly one H1 heading and no more than three H2 headings.
+- One warning callout.
+- At least two fenced shell examples.
+- No table of contents, FAQ, recap, or conclusion section.
+
+Return only the finished Markdown page.

skills/voice/references/technical-documentation-evaluation.md

@@ -0,0 +1,163 @@
+# Technical Documentation Voice Experiment
+
+## Purpose
+
+Use a controlled local comparison to answer two separate questions:
+
+1. Does the Hitchens author anchor produce a recognizable and accurate change?
+2. Do the media adapter or evaluation examples improve that result enough to justify their prompt
+   weight?
+
+This is a development experiment, not CI. Run it before making an author anchor or runtime example
+durable across additional communication types.
+
+## Controls
+
+- Use the same model, reasoning level, task, and run count for every condition.
+- Run each condition at least three times; one appealing generation does not establish reliability.
+- Disable plugins and user configuration so only the named guidance files differ.
+- Keep the generated outputs untracked unless pirog deliberately promotes a result into evaluation
+  evidence.
+- Fail factual or formatting drift before scoring voice.
+
+The commands below use `gpt-5.6-sol` at low reasoning because that was the first pilot configuration.
+Change those values only when every condition changes together.
+
+## Prepare an Isolated Workspace
+
+Run from the `me` repository root:
+
+```sh
+voice_repo_root="$(pwd -P)"
+voice_eval_dir="$(mktemp -d /private/tmp/piro-voice-docs.XXXXXX)"
+git -C "$voice_eval_dir" init -q
+```
+
+`--ephemeral` keeps the runs out of saved Codex history, `--sandbox read-only` prevents workspace
+edits, and `--output-last-message` captures only the prose being compared.
+
+## Run Four Conditions
+
+Run each block three times by replacing `RUN` with `1`, `2`, and `3`.
+
+### A. Baseline
+
+No voice guidance:
+
+```sh
+codex exec --ephemeral --sandbox read-only --disable plugins --ignore-user-config \
+  --model gpt-5.6-sol -c model_reasoning_effort=low \
+  -C "$voice_eval_dir" \
+  --output-last-message "$voice_eval_dir/baseline-RUN.md" \
+  'Complete the documentation task provided on stdin. Return only the requested Markdown.' \
+  < "$voice_repo_root/skills/voice/references/technical-documentation-evaluation-prompt.md"
+```
+
+### B. Author anchor only
+
+Read the author anchor, but not the profile, adapter, or examples:
+
+```sh
+codex exec --ephemeral --sandbox read-only --disable plugins --ignore-user-config \
+  --model gpt-5.6-sol -c model_reasoning_effort=low \
+  -C "$voice_eval_dir" \
+  --output-last-message "$voice_eval_dir/anchor-RUN.md" \
+  "Read only $voice_repo_root/skills/voice/references/hitchens-author-anchor.md as voice guidance. Do not open linked or adjacent files. Complete the documentation task provided on stdin at restrained intensity and return only the requested Markdown." \
+  < "$voice_repo_root/skills/voice/references/technical-documentation-evaluation-prompt.md"
+```
+
+### C. Author anchor and media adapter
+
+Read the normal runtime guidance, but no examples:
+
+```sh
+codex exec --ephemeral --sandbox read-only --disable plugins --ignore-user-config \
+  --model gpt-5.6-sol -c model_reasoning_effort=low \
+  -C "$voice_eval_dir" \
+  --output-last-message "$voice_eval_dir/adapter-RUN.md" \
+  "Read $voice_repo_root/skills/voice/references/voice-profile.md, $voice_repo_root/skills/voice/references/hitchens-author-anchor.md, and $voice_repo_root/skills/voice/references/technical-documentation.md as voice guidance. Do not read evaluation examples. Complete the documentation task provided on stdin and return only the requested Markdown." \
+  < "$voice_repo_root/skills/voice/references/technical-documentation-evaluation-prompt.md"
+```
+
+### D. Author anchor, media adapter, and examples
+
+Add the five evaluation-only pirog examples:
+
+```sh
+codex exec --ephemeral --sandbox read-only --disable plugins --ignore-user-config \
+  --model gpt-5.6-sol -c model_reasoning_effort=low \
+  -C "$voice_eval_dir" \
+  --output-last-message "$voice_eval_dir/examples-RUN.md" \
+  "Read $voice_repo_root/skills/voice/references/voice-profile.md, $voice_repo_root/skills/voice/references/hitchens-author-anchor.md, $voice_repo_root/skills/voice/references/technical-documentation.md, and $voice_repo_root/skills/voice/references/technical-documentation-examples.md as voice guidance. Complete the documentation task provided on stdin and return only the requested Markdown." \
+  < "$voice_repo_root/skills/voice/references/technical-documentation-evaluation-prompt.md"
+```
+
+## Check Intensity Separation
+
+After condition C passes, run the same task once at each intensity from `0` through `3`. Add this
+sentence to the condition C prompt, replacing `SCORE` each time:
+
+> Override the media default and use Hitchens intensity `SCORE`.
+
+The outputs should become progressively more rhetorically conspicuous without changing any fact or
+format. Reject the scale if adjacent levels cannot be distinguished repeatedly, or if intensity `3`
+produces caricature instead of stronger argument and wit.
+
+## Review the Results
+
+First fail any output that changes a fact, command, option, safety boundary, or requested format.
+Then score each surviving output from 0 to 2:
+
+| Dimension            | 0                                           | 1                   | 2                                               |
+| -------------------- | ------------------------------------------- | ------------------- | ----------------------------------------------- |
+| Author influence     | Generic or unrelated                        | Intermittent traits | Clear rhetorical engine without imitation       |
+| Intensity fit        | Too flat or too theatrical                  | Mostly calibrated   | Distinct and appropriate for the selected score |
+| Reader orientation   | Buried task or generic preamble             | Usable but routine  | Leads with the task and next move               |
+| Naturalness          | Stiff, affected, or conspicuously generated | Mostly natural      | Conversational and assured                      |
+| Formatting restraint | Bloated headings, lists, or emphasis        | Minor excess        | Structure follows actual tasks and choices      |
+| Anti-pattern control | Generic AI prose or Hitchens caricature     | Minor leakage       | Neither pattern distracts from the content      |
+
+Condition B should establish whether the author anchor changes the voice. Condition C should retain
+that difference while improving media fit. Keep condition D in runtime guidance only if it repeatedly
+improves a named dimension without losing correctness, naturalness, or formatting compliance.
+
+## Verify Activation Separately
+
+After the guidance passes the ablation, synchronize the managed plugin cache and run the task once
+with an explicit `Use $piro-voice` instruction. Confirm from the Codex trace that it reads the voice
+profile, author anchor, and technical documentation adapter.
+
+Then run the task without naming the skill in an environment that loads the shared
+`dotfiles/ai/.codex/AGENTS.md` guidance. Score the result against the baseline over repeated runs.
+Codex does not guarantee that an eligible installed skill will be selected on every matching turn,
+so the shared guidance owns the compact ambient author anchor and intensity defaults. Explicit
+`$piro-voice` activation remains the test for detailed media guidance.
+
+## Initial Pilot Result
+
+The August 27, 2026 pilot ran three generations per condition with `gpt-5.6-sol` at low reasoning.
+All twelve outputs preserved the required facts. The baseline missed the 250-word minimum three out
+of three times; the author-only and adapter conditions passed it three out of three times; the
+examples condition passed it two out of three times.
+
+The author anchor produced the main recognizable shift. The adapter made that voice more controlled
+for documentation. Adding all five examples showed no reliable incremental benefit and slightly
+reduced compliance, so the examples remain evaluation-only.
+
+Explicit invocation through the synchronized installed plugin loaded the expected profile, author
+anchor, and adapter and passed the factual and formatting gates. Two unnamed runs without an ambient
+activation instruction did not load the skill, even after broadening its discovery description.
+An additional unnamed run showed that an ambient instruction to invoke `$piro-voice` still did not
+force skill selection. That failure is why detailed guidance remains in the plugin while the compact
+author anchor and intensity defaults live in the shared `AGENTS.md` source.
+
+## Initial Intensity Calibration
+
+The first run of the final lean guidance generated one output at each intensity from `0` through `3`.
+All four outputs preserved the required facts and formatting and stayed within 250–400 words. The
+neutral output was conventional documentation; intensity `1` added one controlled pointed contrast;
+intensity `2` sustained skeptical framing; and intensity `3` used several sharper reversals without
+becoming a polemic.
+
+This establishes that the levels can produce visibly different results. It does not establish
+reliability: repeat the intensity pass for each new media adapter before accepting its default.