cockpit-audit

Per-page audit checklist for snappy-shell pages. The pattern emerged from repeated misses in one session: refresh buttons that didn't refresh, "drain queue" buttons that didn't drain, "click to copy" docs without click handlers, page subtitles claiming 0 pending while a stale cache hid 11 items behind it.

Robert (2026-04-26): "why do i have to explain the obvious for everything it is like you need a checklist for every single page some kind of checklist that enforces everything."

The full checklist + dogfood-verify protocol lives in this skill's AGENTS.md loader. Trigger keywords: cockpit, audit, snappy-shell.

When to run

• Before writing any git commit message that says "shipped" / "works" / "fixed" against a snappy-shell page
• After adding a new button, endpoint, or data surface
• When auditing an existing page for missed sophistication (the "hidden layer" pattern)

Steps

1. Open the page in the running app OR read the screen file end-to-end
2. Walk the 10 points in AGENTS.md
3. For each button: curl the underlying endpoint, observe the side effect, then trigger via UI
4. For each data surface: check the server endpoint returns more than the page consumes (richer-endpoint trap)
5. If any point fails, fix it before commit. If a point can't be verified from this shell (SSH/no Screen Recording), say so in the commit message
6. Log the audit in state/log/agents-md-feedback.log

Eval

Shape. This skill is prose-only; the eval is whether running it actually catches the kind of issues it was created to catch. Manual audit log lives in feedback log.

Failure modes that motivate this skill

• Krisp refresh button fired krisp-inbox skill, which only READS the cache, doesn't refresh it. Cache stayed 6 days stale.
• Regen drain button fired pid-regen skill, which scans evals.ndjson, NOT regen-pending.txt. Queue stayed at 11 entries.
• Memory page rendered raw journal only, hid the distilled observations layer that /memory/state already exposed.

All three would have been caught by point #4 (verified buttons) or #2 (layered visibility).

cockpit-audit - loader

Per-turn rules for auditing a snappy-shell page before declaring it "shipped." Robert (2026-04-26): "you need a checklist for every single page some kind of checklist that enforces everything."

Critical Rules

1. Data freshness - Cached or live? If cached, subtitle shows age ("synced 6h ago"). Refresh button hits source-of-truth (not a downstream skill re-reading cache). Verify: curl endpoint pre-click, check cache file mtime post-click.
2. Layered visibility - Pages surface ALL data stages (raw→derived→archive), not just the one the endpoint returned. Server may expose richer endpoints than the page currently reads.
3. Button coverage - Every documented action is a button on the page. No "run this bash command" workarounds.
4. Verified buttons (CRITICAL) - E2E test before commit: curl endpoint → observe state change → click button → confirm same change lands. Never ship an untested button.

• 4a (CRITICAL - Krisp pattern 2026-04-26): Curl response keys MUST match Swift Codable model CodingKeys exactly. Server returns meeting_id but model expects id → silent decode failure → blank UI. Required: list curl keys, list CodingKeys, verify 1:1 map.

1. Honest staleness - Subtitle never lies. "12 items · synced 6 days ago" (not "12 items").
2. Actionable empty states - Button, not CLI. "no X yet - [seed]" button (not "run npx tsx ...").
3. Errors + retry - Every ErrorPlaceholder has a retry callback.
4. Click intent matching - If doc says "click row to copy," clicking does copy.
5. Live-listen - If SSE data event exists for page, observe AppState.liveEvents and refetch on change.
6. No cockpit exits - Every documented operation has an in-app button.

Commands

| ui dashboard | state/skills/cockpit-audit/resources/ui.openui |

Self-Test

1. [ ] Run curl on every button's endpoint before trusting it works
2. [ ] Verify curl JSON keys match Swift CodingKeys (not just HTTP 200)
3. [ ] Check all data-backing stages are visible, not just one
4. [ ] Refuse to commit without ticking points 1,3,4,6,7,10

<!-- 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)] cockpit-audit: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> 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.

• action_kind: shape-ok | skill-ran | loader-rewritten | pattern-elevated

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.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/cockpit-audit/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.