pid-regen

The "I" (integral) of the PID loop. Reads state/log/evals.ndjson, finds skills whose recent scores are trending down, and rewrites their state/skills/<name>.md pages to address the primary issues the eval log surfaced.

This closes the compounding-knowledge loop: every skill run produces a score, scores accumulate, and when a skill starts failing repeatedly the system rewrites the skill itself. No human in the loop for the regen trigger.

When it runs

• Stop hook, automatic: every session end, pid-detect.ts scans for skills

needing regen. If any are found, briefs are queued to state/log/regen-queue/.

• On demand: skill: pid-regen → scans now and drains any queued briefs.

Detection rules (from pid-detect.ts)

A skill needs regen if any of:

1. fails >= 3 - three or more runs scored ≤ 0.5 in the last 7 days
2. runs >= 5 && mean <= 0.75 - sustained mediocrity across many runs
3. zeros >= 2 - two or more complete failures (score = 0)

Steps

1. Detect: npx tsx state/bin/pid-detect.ts - scans evals.ndjson, writes

regen briefs to state/log/regen-queue/<skill>.md for any skill needing regen.

1. Drain: npx tsx state/bin/pid-drain.ts - for each brief, pairs it with

the current skill page and marks it ready for rewrite.

1. Dispatch: the Stop hook or orchestrator dispatches a fresh subagent with:

"Read <brief> and <skill page>. Rewrite <skill page> to address the primary issues. Surgical edits only."

1. Lint: after rewrite, npx tsx state/lint/check.ts state/skills/<skill>.md

validates structure (frontmatter, Eval section, etc.). If lint fails, revert and re-queue.

1. Archive: on successful rewrite + lint, brief moves to state/log/regen-queue/done/.

Eval

score("pid-regen", run_id, {
  score:
    rewrites_passed_lint === rewrites_attempted && briefs_archived === rewrites_attempted
      ? 1.0
      : rewrites_attempted > 0 && rewrites_passed_lint > 0
        ? 0.5
        : 0.0,
  briefs_detected,
  rewrites_attempted,
  rewrites_passed_lint,
  briefs_archived,
  primary_issue:
    rewrites_passed_lint === 0 && rewrites_attempted > 0
      ? "all-rewrites-failed-lint"
      : null,
});

Score 1.0: every brief was drained, rewritten, and linted clean. Score 0.5: at least one brief drained successfully, some failed. Score 0.0: no briefs drained or all rewrites failed lint.

Read-only mode

skill: pid-regen --dry scans and reports needing-regen skills without writing briefs. Useful for checking what the system thinks is declining without triggering rewrites.

npx tsx state/bin/pid-detect.ts --stats prints a one-line-per-skill table of trends (runs, mean, fails) in the last 7 days.

Rubric

criteria:
  - name: all_briefs_rewritten_and_linted
    kind: deterministic
    check: "The `eval` score for 'pid-regen' is 1.0, indicating that `rewrites_passed_lint` equals `rewrites_attempted` and `briefs_archived` equals `rewrites_attempted`."
  - name: lint_passes_for_rewritten_skills
    kind: deterministic
    check: "For every skill page rewritten by `pid-regen`, running `npx tsx state/lint/check.ts state/skills/<skill>.md` exits with code 0."
  - name: regen_briefs_are_archived
    kind: deterministic
    check: "All brief files (from `state/log/regen-queue/`) processed by `pid-regen` are moved to `state/log/regen-queue/done/`."
  - name: surgical_edits_only
    kind: judge
    check: "The rewritten skill pages (e.g., `state/skills/<skill>.md`) show minimal, targeted changes directly addressing the outlined issues from the brief, without extraneous modifications or complete overhauls."

pid-regen - loader

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

Critical Rules

• Detection rules (any one triggers regen): fails >= 3 (≤0.5 in 7d) OR runs >= 5 && mean <= 0.75 OR zeros >= 2
• Regen is SURGICAL - the dispatched subagent edits the existing skill page to address primary_issue from the eval log; not a full rewrite
• ALWAYS lint after rewrite (npx tsx state/lint/check.ts state/skills/<skill>.md). On lint fail → REVERT and re-queue. Do NOT ship a broken skill page.
• Briefs that pass lint move to state/log/regen-queue/done/. Anything left in regen-queue/ without .ready is unprocessed.
• Score 1.0 only when every brief was drained AND rewritten AND linted clean. Partial success = 0.5. All-fail = 0.0.

Commands

| ui dashboard | state/skills/pid-regen/resources/ui.openui | |detect: npx tsx state/bin/pid-detect.ts (writes briefs to state/log/regen-queue/<skill>.md) |drain: npx tsx state/bin/pid-drain.ts (marks each brief .ready) |stats only (read-only): npx tsx state/bin/pid-detect.ts --stats |dry mode: skill: pid-regen --dry |dispatch (from Stop hook or orchestrator): subagent reads brief + skill page, surgical edit |eval log: state/log/evals.ndjson (skill: "pid-regen")

OpenUI Resource

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

• A scrubbed skill (e.g. linkedin-post-scraper) may show false-positive regen triggers because pre-gate drift rows still sit in evals.ndjson. The right move is QUARANTINE the bad rows to state/log/evals.quarantine.ndjson, NOT rewrite the page (see linkedin-post-scraper skill for the canonical quarantine procedure)
• P0 frictions beat P2 evals at 0.7 score - the PID loop reads state/log/frictions.ndjson to prioritize. Pain before polish.
• Lint failure on a rewrite means revert + re-queue, not ship-and-fix

Self-Test

An agent reading this should correctly:

1. [ ] Quarantine pre-gate drift eval rows rather than triggering a brief on a clean skill?
2. [ ] Revert a rewrite that fails state/lint/check.ts and re-queue the brief?
3. [ ] Recognize that --stats is read-only and --dry writes no briefs?

Self-report

If this loader fell short, append a line:

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