snappy-migrate

A "convention rename" - renaming a frontmatter field, switching a file-naming convention (e.g. <slug>.md → <slug>/SKILL.md), retiring a feature column - hits dozens of code paths across lints, libs, server endpoints, JSX UI, and generated sidecars. Doing it ad-hoc leaves silent breakage. This skill is the runbook AND the self-correcting loop: each run records what was missed last time so the next run is shorter. Pitfalls compress into the loader.

When to invoke

• Renaming a file-layout convention across state/
• Retiring a frontmatter field (graduation:, maturity:, etc.)
• Changing a directory shape that lints + libs + server + UI all walk
• Anything where a single find/replace would miss a generator output

Steps

1. Scope. State the rename in one sentence: "From X to Y." If you can't,

stop - split into smaller migrations.

1. Sweep active code first. Grep across *.{ts,sh,js,mjs,jsx}:

grep -rn 'old-pattern' state/ bin/ --include='*.ts' --include='*.sh' --include='*.js' --include='*.jsx' --include='*.mjs' Skip backfill scripts (backfill-*.ts) - they walk historical git paths and rewriting them breaks replay semantics.

1. Fix block-comment hazards. A literal */ inside a /* ... */ block

comment closes the block. state/skills/*/SKILL.md inside JSDoc ends the comment at */SKILL. Reword to "per-slug SKILL.md" or use line comments. JSX is parsed by Babel-standalone in-browser - one bad block comment kills the page silently. Always parse-check JSX with @babel/core after edits.

1. Inline-content sweep. If the convention is referenced inside generated

files (loaders, scaffolds, AGENTS.md), grep those too. Generators that create them once won't fix existing copies - you have to rewrite each. Example: loaders-sync.ts only emits NEW loaders; existing 135 AGENTS.md files keep stale path text inside their bodies.

1. Sidecar regen. If a generator (loaders-sync, sync-runtimes, icons)

reads the old shape, update its source list. Re-run the generator. Diff to verify downstream artifacts are clean.

1. Lint pass. npx tsx state/lint/check.ts + npx tsx state/lint/skill-shape.ts

(or whichever shape lint matches the migration). Fix until green.

1. Dogfood the frontend. Restart long-lived npx tsx daemons FIRST -

they don't hot-reload. Then curl every GET endpoint in state/bin/head-screen/server.ts. Look for HTTP 200 with suspiciously small bodies (/skills-catalog returning 24 bytes = empty array). Empty payload from an endpoint that should have data = stale walker.

1. Commit. SNAPPY_POD_DISPATCH_BYPASS=1 for mechanical-reversible ops.

Single commit if the renames are coupled.

Eval

Actor: the playbook above (executed by an agent or sub-agent). Auditor: lint suite + dogfood probe. Independent from the actor.

Pass criteria:

• npx tsx state/lint/check.ts exits 0
• npx tsx state/lint/skill-shape.ts exits 0
• Every GET endpoint in head-screen/server.ts returns a non-empty payload

(or a documented empty case like /match-loaders requiring a query param)

Log to state/log/evals.ndjson with skill: "snappy-migrate".

Gotchas

The compressible distillation lives in AGENTS.md (Known Pitfalls). Each run that hits a new gap MUST P-edit that section before logging. SKILL.md holds the full runbook; AGENTS.md holds the tight rules.

Rubric

criteria:
  - name: lint_check_green
    kind: deterministic
    check: "The command 'npx tsx state/lint/check.ts' must exit with a status code of 0."
  - name: lint_skill_shape_green
    kind: deterministic
    check: "The command 'npx tsx state/lint/skill-shape.ts' must exit with a status code of 0."
  - name: endpoints_dogfooded
    kind: deterministic
    check: "Every GET endpoint listed in 'state/bin/head-screen/server.ts' must return an HTTP 200 status code and a non-empty payload, unless explicitly documented for empty cases."
  - name: agents_md_updated_on_failure
    kind: judge
    check: "If any lint or dogfood check failed on the first attempt, the 'Known Pitfalls' section in AGENTS.md must have been updated to reflect the new gap."

snappy-migrate - loader

Per-turn rules for running a convention/shape migration. Full reference: state/skills/snappy-migrate/SKILL.md. Do not skip these.

Critical Rules

• Sweep ACTIVE code first (*.{ts,sh,js,jsx,mjs}), comments/docstrings second.

Backfill scripts (backfill-*.ts) are historical replay - leave them alone.

• Long-lived npx tsx daemons (head-screen server, autopilot, byline) do NOT

hot-reload. Kill + relaunch after code changes or you'll dogfood stale bytes.

• Generators emit on first scaffold; existing copies are NOT rewritten by

re-running the generator. Inline-content sweep is a separate pass.

• HTTP 200 with a tiny body (/skills-catalog: 24 bytes) = walker missed the

migration. Inspect the JSON, find the lib, fix the walker.

• HTTP 500 with ReferenceError: <var> is not defined = the migration renamed

a local (e.g. files → loaderEntries in listSkills refactor) but left a stale reference in the response body. Same fix posture: re-derive from the new walker shape (listSkills(skillsDir).filter(...)) or remove the stat. Caught skill-authority on the SKILL/AGENTS folder migration.

• Every gap discovered that wasn't in this loader → P-fix it (see footer).

Commands

| ui dashboard | state/skills/snappy-migrate/resources/ui.openui | |grep refs: grep -rn 'old-pattern' state/ bin/ --include='*.ts' --include='*.sh' --include='*.js' --include='*.jsx' --include='*.mjs' |lint: npx tsx state/lint/check.ts && npx tsx state/lint/skill-shape.ts |restart head-screen: pkill -f 'tsx state/bin/head-screen/server.ts'; sleep 2; nohup bash state/bin/head-screen/launch.sh >/tmp/head.log 2>&1 & disown |parse-check JSX: NODE_PATH=/tmp/jsxcheck/node_modules node -e "require('@babel/core').parseSync(require('fs').readFileSync(F,'utf8'),{presets:['@babel/preset-react'],filename:F})" |dogfood probe: curl every GET in state/bin/head-screen/server.ts (grep pathname ===) |commit: SNAPPY_POD_DISPATCH_BYPASS=1 git commit -m '...' |eval log: state/log/evals.ndjson (skill: "snappy-migrate")

OpenUI Resource

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

• */ inside block comments closes the comment. state/skills/*/SKILL.md

inside /* ... */ ends the JSDoc at */SKILL, breaking the file. Reword to "per-slug SKILL.md" or use // line comments. JSX is parsed by Babel-standalone in-browser - one bad block comment kills the page silently with no error in head-screen.log.

• AGENTS.md inline content sweep is separate from generator regen.

loaders-sync.ts only emits NEW loaders; existing AGENTS.md files keep stale state/skills/<slug>.md text in their bodies. Walk + rewrite each.

• head-screen daemon is sticky. Server holds old listSkills in memory.

Symptom: /skills-catalog, /skills, /never-do return tiny payloads despite full disk state. Cure: kill + relaunch via launch.sh.

• Babel parse hazard in JSX. Block comment containing */<anything> will

silently break the page. Always parse-check after edits to JSX.

• Single-touchpoint rule. Every walker over the skill catalog goes through

listSkills() from state/lib/skill-paths.ts. Direct readdirSync on state/skills/ is a code smell - it'll miss the next migration.

Self-Test

An agent reading this should correctly:

1. [ ] Sweep active code first, comments second, skip backfill scripts?
2. [ ] Reword */ patterns inside block comments?
3. [ ] Restart head-screen / other tsx daemons after code changes?
4. [ ] Probe every GET endpoint for empty-payload regressions?
5. [ ] P-fix this loader before logging FIXED to feedback.log?

Self-report

If this loader fell short, append a line:

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