content-polish

The thesis test. This skill exists because the kernel's content-polish shipped em-dashes: the shell exit code was 0 so it reported success, but the draft had two em-dashes (dead AI tells). Metrics aren't evals. In mini, voice.checkTone() runs as deterministic code inside the skill, and the eval score IS the violations-zero check, not a downstream wrapper.

Steps

1. Scope - no side effects

Run voice.checkTone(draft). Return { pass, violations }. If pass, done; log eval score 1.0.

2. Rewrite loop (if violations present)

for turn in 1..max_turns:
  dispatch {
    model: "gemini",
    prompt: <draft> + <violation list> + <voice rules> + "rewrite, zero violations",
  }
  draft = response
  result = checkTone(draft)
  if result.pass: break

3. Flow check (long-form drafts only)

After tone passes, run voice.checkFlow(draft) on drafts ≥ 10 sentences. This catches AI-flat prose: monotone sentence length, no short punches, no flowing clauses. Score degrades to 0.5 if flow violations remain after rewrite.

const flow = checkFlow(draft);
if (!flow.pass) {
  // re-dispatch with flow violations as additional instruction
  // re-check after each turn, same loop as step 2
}

4. Final verdict + log

const tone_ok = checkTone(draft).pass;
const flow_ok = draft_sentences < 10 || checkFlow(draft).pass;
score("content-polish", run_id, {
  score:
    tone_ok && flow_ok && first_try ? 1.0 :
    tone_ok && flow_ok ? 0.5 :
    tone_ok && !flow_ok ? 0.5 :
    0.0,
  primary_issue: final_violations.slice(0, 3).join("; ") || flow.violations?.[0] || null,
  turns_used: turn,
  flow_profile: flow.profile,
  flow_stdev: flow.stats?.stdev,
});
append("chain", { run_id, skill: "content-polish", action: "scoped", ... });

Eval

Actor: dispatch model (gemini-2.5-flash via openrouter) rewrites the draft. Auditor: voice.checkTone() - deterministic regex + banned-phrase list in state/lib/voice.ts. Two different systems, as rule #actor-≠-auditor requires.

Score convention:

The shell exit code is irrelevant. A dispatch can return exit 0 with an em-dash in its output. The eval catches that.

Gotchas

• Image-prompt frontmatter (layer_*, metaphor_rationale, image_prompt)

is §4a-exempt. Don't run checkTone on those fields - they go to DALL-E.

• Round-tripped drafts may contain the , artifact where em-dashes used

to be. Add a scan for the literal string if you see it.

• dispatch() uses pi under the hood; make sure pi is on PATH.
• Rewrite prompts should hand the model the actual violations list, not a

generic "be better." Give it what failed so it can fix it.

Graduation

Sidecar at state/bin/content-polish/run.ts is the deterministic path.

Rubric

criteria:
  - name: no_tone_violations
    kind: deterministic
    check: "The final draft produced by the skill must result in 0 violations from `voice.checkTone(draft)`."
  - name: flow_assessment_accuracy
    kind: judge
    check: "For drafts >= 10 sentences, the skill's final score (1.0 or 0.5) must accurately reflect the `voice.checkFlow(draft)` result."
  - name: efficiency_of_rewrites
    kind: judge
    check: "The `turns_used` reported in the final log should be minimal, indicating the skill did not take unnecessary rewrite turns to achieve the desired tone and flow."
  - name: no_forbidden_artifacts
    kind: deterministic
    check: "The final processed draft must not contain forbidden artifacts like ' ,  ' or em-dashes if they were present initially and flagged as violations."

content-polish - loader

Per-turn rules for the content-polish skill. Full reference: state/skills/content-polish/SKILL.md. Do not skip these.

Critical Rules

• NEVER trust the shell exit code. The eval is voice.checkTone() returning zero violations - a dispatch can return exit 0 with em-dashes still in the output. The kernel shipped em-dashes because of exactly this confusion.
• ALWAYS hand the rewrite model the actual violations list, not a generic "be better." The model can only fix what it's told failed.
• Image-prompt frontmatter (layer_*, metaphor_rationale, image_prompt) is §4a-exempt. Don't run checkTone on those - they go to DALL-E, not a reader. (feedback_image_prompts_not_4a.md)
• Scan for the literal string , (space-comma-two-spaces) - known kernel artifact where round-tripped em-dashes leave a residue voice.ts doesn't catch. (feedback_skool_emdash_backfill_artifact.md)

Commands

| ui dashboard | state/skills/content-polish/resources/ui.openui | |invoke: npx tsx state/bin/content-polish/run.ts (script - graduated) |verify: re-run voice.checkTone(draft) and confirm violations.length === 0 |eval log: state/log/evals.ndjson (auto eval - skill: "content-polish")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/content-polish/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• After tone passes on long-form (≥10 sentences), run voice.checkFlow() - flow violations degrade score to 0.5 even with clean tone
• dispatch() uses pi under the hood; pi must be on PATH or the loop silently misfires
• Score 0.0 = do not ship. There is no "good enough" override.

Self-Test

An agent reading this should correctly:

1. [ ] Treat voice.checkTone() zero-violations as the only success signal, not exit code
2. [ ] Skip checkTone on image-prompt frontmatter fields
3. [ ] Pass the violations list into the rewrite prompt, not just the draft

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] content-polish: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] content-polish: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.