testimonial-scan

Closes the phantom referenced by testimonial-ask.md - that skill drafts permission requests against "silent-shipped" artifacts but has no drafting/scoring lib behind it. testimonial-scan is the upstream half: it pulls existing testimonials from the content-engine DB and scores new candidate quotes on the 4-dimension rubric (specificity, authenticity, impact, clarity) before anything gets handed to testimonial-ask.

Failure mode this prevents: testimonial-ask drafting a request that quotes a LOW-scoring (generic, polished, no-specifics) line, which would burn the client relationship for a useless asset. The scorer is the gate.

Steps

1. Scope - no side effects

• action=list: call getTestimonials(status?) from

state/lib/testimonials.ts. Reads from the content-engine SQL proxy (https://rb-content-engine.fly.dev/sql). Read-only.

• action=score: call scoreTestimonial(text, speaker). Pure function,

no network, no credentials.

2. Gate

• action must be "list" or "score". Any other value throws.
• For action=score, both text and speaker are required. "Unknown"

is allowed as a placeholder speaker but flagged in the clarity sub-score.

• Disqualify-at-gate rules (from kernel SKILL.md):
• Never score Robert's own lines - speaker check against "Robert".
• Verbatim only. If the caller paraphrased, the score is meaningless.

3. Act

import { getTestimonials, scoreTestimonial } from "../lib/testimonials.ts";

// list
const rows = await getTestimonials(status);  // Testimonial[]

// score
const result = scoreTestimonial(text, speaker);
// { score: "HIGH"|"MEDIUM"|"LOW", specificity, authenticity, impact, clarity, total, reason }

Hand HIGH-scoring candidates downstream to testimonial-ask for permission-draft generation. MEDIUM is a judgement call. LOW is a hard reject - do not draft against it.

4. Log + eval

append("chain", { run_id, skill: "testimonial-scan", action,
                  candidates: rows?.length ?? 1,
                  high: rows?.filter(r => r.score === "HIGH").length });
score("testimonial-scan", run_id, {
  score: shape_ok && (action === "list" ? rows_fetched : score_produced) ? 1.0 : 0.0,
  high_count, medium_count, low_count,
  primary_issue: !shape_ok ? "bad-action" :
                 action === "list" && !rows_fetched ? "sql-empty-or-error" :
                 null,
});

Eval

Actor: scoreTestimonial() - a pure deterministic TypeScript function in state/lib/testimonials.ts. For action=list, the actor is the content-engine SQL endpoint.

Auditor: shape-gate in this skill (validates the returned row shape + score dimensions ∈ [1,5] + total ∈ [4,20]) plus the disqualify-at-gate rules enforced in Step 2. Actor and auditor are different files and one is code while the other is the skill page's contract - actor ≠ auditor holds.

Score convention:

This is a shape-grade auto eval in spirit. True semantic grading (did the scorer agree with Robert's own read of the quote?) requires a second model as auditor - see ## Gotchas below.

Gotchas

• Verbatim only, never paraphrase. Kernel SKILL.md rule. Paraphrased

quotes silently break both the rubric and the eventual permission ask.

• One quote per permission ask. Do not batch. Enforced downstream in

testimonial-ask, but worth repeating: a "list of quotes to ask about" is not a testimonial-ask input, it's a queue.

• Never re-ask a declined quote. That state lives in the

snappy-knowledge contact notes - not in this skill. Downstream responsibility, surfaced here so the scan stage doesn't resurface dead candidates.

• env import is currently unused in lib/testimonials.ts. Ported

skillatim per bootstrap.md §3 "do not refactor anything else." The content-engine SQL endpoint is unauthenticated. If a future auth layer lands, wire env("CONTENT_ENGINE_TOKEN") into the sql() helper.

• Graduation to full auto eval requires a second model (e.g.

dispatch gemini) as semantic auditor: does the LLM agree with the rubric's HIGH/MEDIUM/LOW verdict on a fresh read? Until then, the eval is shape-only and this skill stays prose.

Graduation

Prose until a second-model semantic auditor lands (see Gotchas). The deterministic scoreTestimonial() function is already in state/lib/ - graduation for this skill means adding the auditor, not extracting the scorer.

Rubric

criteria:
  - name: action_input_validation
    kind: deterministic
    check: "The 'action' input must be 'list' or 'score', otherwise an error is thrown."
  - name: score_input_requirements
    kind: deterministic
    check: "For action='score', both 'text' and 'speaker' inputs must be provided."
  - name: disqualify_robert_speaker
    kind: deterministic
    check: "If action='score' and the 'speaker' is 'Robert', the skill output should be disqualified (score 0.0)."
  - name: output_shape_validity
    kind: deterministic
    check: "The output must conform to the expected shape: for 'list', an array of Testimonial; for 'score', an object with score as HIGH/MEDIUM/LOW, 4 dimension scores, total, and reason."
  - name: side_effect_honesty
    kind: deterministic
    check: "The skill must not produce side effects beyond reading from content-engine DB for 'list' action."

testimonial-scan - loader

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

Critical Rules

• Verbatim only, never paraphrase. Kernel SKILL.md rule. Paraphrased quotes silently break both the rubric and the eventual permission ask.
• NEVER score Robert's own lines. Speaker check against "Robert" is a disqualify-at-gate.
• NEVER batch - one quote per downstream permission ask.
• NEVER re-ask a declined quote. That state lives in snappy-knowledge contact notes (downstream concern, surfaced here so scan doesn't resurface dead candidates).
• LOW score is a HARD REJECT. Do not draft against it. MEDIUM is a judgement call. Only HIGH gets handed to testimonial-ask.

Commands

| ui dashboard | state/skills/testimonial-scan/resources/ui.openui | |invoke (list): import { getTestimonials } from "state/lib/testimonials.ts"; const rows = await getTestimonials(status?); |invoke (score): import { scoreTestimonial } from "state/lib/testimonials.ts"; const result = scoreTestimonial(text, speaker); |verify: shape-gate - score dimensions ∈ [1,5], total ∈ [4,20], result has {score, specificity, authenticity, impact, clarity, total, reason} |eval log: state/log/evals.ndjson (skill: "testimonial-scan") - fields: high_count, medium_count, low_count

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/testimonial-scan/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

• getTestimonials() reads from content-engine SQL proxy https://rb-content-engine.fly.dev/sql - it is NOT Xano. Currently unauthenticated; if auth lands, wire env("CONTENT_ENGINE_TOKEN") into the sql() helper.
• scoreTestimonial() is pure - no network, no credentials. Safe to call from any context.
• "Unknown" is allowed as placeholder speaker but flagged in clarity sub-score.
• Score 0.5 = shape valid but zero rows / zero usable dimensions. Score 0.0 = invalid action / SQL error / disqualify-at-gate hit.
• True semantic grading (LLM agrees with rubric verdict) requires a second-model auditor - until that lands, eval is shape-only and skill stays prose.

Self-Test

An agent reading this should correctly:

1. [ ] Refuse to score a paraphrased quote
2. [ ] Refuse to score a Robert quote
3. [ ] Reject LOW candidates before passing to testimonial-ask
4. [ ] Know the SQL endpoint is content-engine (Neon Postgres proxy), not Xano

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] testimonial-scan: <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)] testimonial-scan: <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.