Pixel-CLI/pixel / .agents/skills/pixel-retro
pixel-retro
VerifiedMine the last 24 h (or a given window) of pixel usage — every repo's `.pixel/actions.jsonl` plus the agent transcripts indexed by `pixel recall` (claude, codex, pi…) — for frictions pixel actually caused, verify each one against the current binary and code, and propose ranked, evidence-backed improvements (bug fix, error message, flag, agent prompt, rule, doc); for the pixel repo itself, also measure each pull request from first edit to validated CI and where agents sat idle (`lead_time.py`). Suggests only; implements nothing without the user's pick. Use when the user says "/pixel-retro", "retro pixel", "qu'est-ce qui a coincé avec pixel", "améliorations pixel depuis les transcripts", "pixel friction", "où l'agent attend", "bottleneck", "lead time", or asks what to improve in pixel or its development workflow from recent sessions.
Pixel retro
Turn what pixel did to agents over a recent window into a short list of improvements, each anchored to something that happened. No evidence, no suggestion: an idea you cannot point to in an action log or a transcript turn belongs in a separate conversation.
Argument: a window (24h by default, 48h, 7d, an ISO date). Written
$W below.
Prerequisite — the plugins this skill reads through
recall, action-log, list-errors, commit-history, search-history,
repo-state, review-changes and diff are command plugins, not core
commands. pixel plugin list shows what runs; install what is missing, one
repository each: pixel install github:Pixel-CLI/pixel-recall (recall),
pixel-telemetry (action-log, list-errors, token-savings),
pixel-git (the git commands). A plugin that declares network access also
needs pixel plugin enable <name>. A missing plugin prints
"recall" moved to a plugin: pixel install … and exits 2: install it, do
not skip the step. The action log itself is plain JSONL
(<root>/.pixel/actions.jsonl, one record per line, plugin runs included),
readable without action-log.
Step 0 — Fresh corpus, known baseline
pixel recall daemon status # not running → the corpus is stale
pixel recall index --stats # incremental, a few seconds
pixel recall status # last ingest must be minutes old, per agent
pixel --version # the binary the suggestions are judged against
pixel commit-history # what main gained inside the window
pixel --metrics off doctor . --only install.claude-hooks --only install.pi-impact
The last line says which prompt the agents in the transcripts were
reading (--only is newer than 0.4.0: on an older binary, run pixel doctor . and read those two checks). A stale one — red, or the note: agent-prompt.md deployed by \pixel setup` differs…` line every command
prints since #243 — means the misuses in the window may follow an older
release's command map: judge them against that prompt, not the current one.
Stop and say so if an agent's last ingest predates the window: a quiet
window on a stale corpus is not a quiet window. Semantic search may be off
(semantic: no vectors yet); pixel recall ask then degrades to lexical,
so prefer search with explicit regexes.
Read the ledger ~/.local/state/pixel-retro/seen.tsv (columns:
date fingerprint verdict ref; a missing file means an empty ledger).
A fingerprint is <command>|<error normalised: paths, numbers, ids → _>.
Anything already fixed, wontfix, suggested or not-pixel less than 7 days ago is
skipped unless its count grew.
Step 1 — Collect the raw signal
Two sources, in this order: the action log is structured and exact, the transcripts explain what the agent did about it.
A. Action logs. Every pixel invocation appends to
<root>/.pixel/actions.jsonl (ts_ms, command, args, cwd,
outcome, error, duration_ms, serve). The roots come from the sessions
themselves, so a repository outside the usual folders is not missed: take
every session cwd in the window, resolve it to its repository root, and
keep the roots that have a log. pixel recall sessions caps --limit at
200 and has no offset, so roots.py cuts the window into time slices and
halves any slice that comes back full; it dedupes by session id, includes
subagent sessions, and warns if 200 sessions overlap a single second. The find adds the worktrees and fixtures no
session ran in:
python3 .agents/skills/pixel-retro/roots.py $W
find ~/code /tmp/pxwt -maxdepth 4 -path '*/.pixel/actions.jsonl' -mtime -1 2>/dev/null # -mtime -2 for 48h, and so on
then per root pixel action-log --errors-only --json --limit 500 <root>,
keeping entries whose ts_ms falls in the window. Count each
invocation_id once and place it by its cwd, not by the log it was read
from: a worktree bootstrap that copies the main checkout's .pixel/ copies
actions.jsonl with it (verified 2026-10-16, a downstream repository's Codex
worktrees: one find-symbol in four logs). A read op that takes
seconds is a friction even when it succeeds; group the slow ones by how
they were served:
python3 .agents/skills/pixel-retro/slow.py $W <root>/.pixel/actions.jsonl ... # --min-ms 5000 by default
It keeps read ops (search-*, find-*, impact, who-calls,
call-path, scope-task, pack-context, status, repo-state, and
recall only for search/ask/context/show/sessions/status: a slow
recall index is an ingest, not an answer) over the threshold, leaves the
test suite out (cwd under crates/ or the temp dir, /tmp/pxwt/ kept), and groups them
on (command, route, reason, dominant phase) with count, total, worst, and
the three worst invocation_ids. Each line's serve list (#241, #242)
records who answered each request and where its milliseconds went; name a
cause from it, never from the command alone:
serve shows | Where the time went | Look at |
|---|---|---|
daemon, probe_ms dominant | the queue ahead: the daemon serves one request at a time and flushes its watcher batch first | a concurrent call in the same seconds (another agent, a hook), a large pending batch after a checkout (daemon.rs flush_pending) |
daemon, request_ms dominant | the op itself, lazy graph or index work included | profile the op on that repo |
daemon_started, start_ms dominant | a cold start: no daemon (30 min idle exit, reboot, upgrade) | how long Service::open takes there; retiring a stale daemon after an upgrade counts here too |
in_process start_timed_out, start_ms ≈ 5 000 then open_ms | the start outlasted the 5 s wait and the CLI opened the index a second time, in process, next to the starting daemon | daemon startup order (daemon::run opens the Service before taking the lock); PE-01 in docs/audit/pixel-retro-2026-09-23 |
in_process auto_start_disabled / no_daemon, open_ms | every call opens the index itself, by configuration | PIXEL_DAEMON_AUTO_START=0 or --no-daemon in that agent's setup: a config finding, not a pixel bug |
in_process newer_daemon | two pixel binaries on one root, the older one declining the newer daemon | install drift (Step 3) |
recall daemon_absent / not_routed, open_ms | the transcript catch-up and the model load, in process (context has no daemon route) | the recall daemon was not running (pixel recall daemon status) |
recall daemon, open_ms dominant | search catches up in process before it asks the daemon | the catch-up itself, not the daemon |
recall daemon_error | the daemon answered with an error and the query was redone in process | the error on the stderr of that call |
unattributed | the line predates serve | nothing to conclude: say so, and do not read a warm replay under 2 s as "not reproduced" |
Drop the noise before counting (verified 2026-09):
- pixel's own test suite.
cargo testspawns the CLI withcwdunder<pixel>/crates/…or args under/var/folders/…,$TMPDIR,/tmp/, and those runs land in the real repo'sactions.jsonl(37 of 40 errors in one sample werecheck-release/classifytest cases). Exclude them from the counts; report the leak itself once as a finding while it lasts. - The stale-prompt note and a side build. A
pixel-devnever prints it. The managedpixelprinting it on every call while~/.claude/settings.jsonrunspixel-dev run-hook …means a globalpixel-dev setuptook the home install: report it once, withpixel setupas the hand-back, not as drift. - Refusals that are the contract.
fast-forwardrefusing a non-ff,commitrefusing a dirty or empty stage, a--request-idreplay: an error is a friction only if the agent had to work around it (Step 2 says how to tell).
B. Transcripts. Regex over the corpus, newest first, always with
--since $W. Run each probe once across all repos, then narrow with
--repo where the hits cluster:
| Probe | Command |
|---|---|
| pixel call that failed | `pixel recall search '(error |
| agent bypassed pixel | `pixel recall search '⋮tool Bash {"command":"[^"]*\b(rg |
| retry loop | three or more pixel search-* / find-* calls on the same topic within a few turns of one session (pixel recall show <ref> --turn N..M) |
| empty or truncated answer | `pixel recall search '\b(unresolved |
| human complaint | pixel recall search 'pixel' --role user --human-only --since $W (--human-only alone keeps assistant and tool turns, it only drops injected user text), read for "marche pas", "lent", "pourquoi", "bug", "encore", "wrong" |
| harness or install drift | `pixel recall search '(doctor |
| prompts older than the binary | pixel recall search 'deployed by .pixel setup. differs? from' --role tool --since $W (#243): how many sessions ran on a stale prompt, and whether the agent or the user acted on it |
Sessions that ran in the pixel repo itself are mostly about pixel's code: there, "capped" or "error" usually sits in a diff or a test, not in a pixel answer. Count a hit only when the matched text is pixel's output to the agent.
recall prints timestamps in UTC, the action log's ts_ms is epoch: convert
before matching the two.
C. The pixel repo's own development loop. Only when the window has
sessions in this repository, or when the question is where agents wait
("bottleneck", "idle", "lead time", « où l'agent attend »). CONTRIBUTING.md
("Agent validation workflow") measures the loop from the first edit to a
fully validated pull request, CI queue and fix/push cycles included; agent
activity alone is not a throughput metric. lead_time.py does that per pull
request opened in the window:
python3 .agents/skills/pixel-retro/lead_time.py $W # reads gh pr view per PR
python3 .agents/skills/pixel-retro/lead_time.py $W --no-gh # offline: edit → PR open only
It reads every Claude Code session (subagents included) and Codex rollout
(sessions/ and archived_sessions/) written to in the window, whatever
directory it ran in (narrow with --projects <dir> / --codex <dir>), and
keeps the PRs whose gh pr create URL names this repository's origin
slug: a sibling checkout opens PRs here, and a sibling repository's #33 is
not this one's. It prints per PR the time from its first edit to gh pr create, from there to all-check completion and separately to successful validation
on the final head (SUCCESS, NEUTRAL or SKIPPED check runs; SUCCESS commit
statuses), the pushes in that session, and the
session's time split into tool, model, idle (waiting on a background task)
and human; then the median lead time and the commands with the most
blocking time. Read the numbers with their limits:
- Completed is not validated. Failed, cancelled, timed-out, unknown or pending results never enter the green median, even after merge. A pending review status on a merged PR leaves validation unknown. The report shows validated/local/GitHub PR counts; a failed or capped GitHub listing reports unknown coverage. JSON retains the observed head SHA, completion duration and missing local PR numbers. This is the observed rollup, not a branch protection audit.
- Idle is a ceiling, not a saving. It is recoverable only where the session had an independent unit to advance; the data does not say whether it did.
- One session per PR. Follow-up pushes from another session count in open → green but not in the split.
- Codex edits are inferred. A Codex unit starts at its first
apply_patchor at the first shell command that writes a file (sed -i, a script callingwrite_text, a redirection into a source file); an edit done another way starts it later. - A PR opened elsewhere is missing. Cloud sessions, another machine or a
person opening it by hand leave no local transcript: compare the count
with
gh pr list --search 'created:>=<window start>'. - Compare windows, not sessions. A rule change (#418 on 2026-09-30, say) shows as a shift of the median and of the top blocking commands between a window before it and one after, quoted with both commands.
A finding here is a workflow change, not a pixel bug: its destination is
CONTRIBUTING.md, .agents/rules/*.md, a script under scripts/ or a CI
workflow, and its report block gives the before/after numbers.
D. Adherence: do agents use Pixel, and use it well? Whenever the
question is whether a hook, prompt or routing change moved agent behaviour
("coherence", « est-ce que l'agent utilise pixel », adoption), and in every
retro whose window spans such a change. adherence.py reduces each session
in a Pixel-indexed repository, Claude Code and Codex alike, to its retrieval
events and prints per host (never pooled):
python3 .agents/skills/pixel-retro/adherence.py $W # table
python3 .agents/skills/pixel-retro/adherence.py $W --json # for a before/after diff
the Pixel share of searches, how often the first search was Pixel, how often
a Pixel call's very next event was a native search, unbounded and wide reads
overall and right after a Pixel call, and the editing sessions that ran
impact/who-calls/call-path before their first edit. The baseline,
adherence.py 30d on 2026-10-04, before the #703/#704/#706/#707/#711 fixes:
Claude 503 sessions, Pixel share 0.011 (74 Pixel against 6 458 native
searches), first search Pixel 6 %, a native search right after Pixel 32 %
(24/74), unbounded reads right after Pixel 50 %, impact before the first edit
1 % (3/311); Codex 76 sessions, share 0.059 (85 against 1 350), first search
Pixel 20 %, a native search right after Pixel 22 %, impact before the first
edit 65 % (20/31). Read them
with their limits:
- It records order, not intent. A native search right after Pixel is a
sequence, not proof the answer went unused: it can be the right move (a
string Pixel does not index). The A/B in
eval/(#626) says where Pixel should win; this says what agents did. - Compare windows on the same host, before and after the change, each quoted with its command; a Codex number is never read against a Claude one.
For each action-log error worth keeping, find its transcript turn with a
distinctive token from args (a --request-id, a path, a pattern):
pixel recall search '<token>' --since $W. The turns after it show the
cost: how many calls the agent spent, and whether it fell back to a native
tool.
Step 2 — Verify each candidate
Session memory and a single log line both lie. For every candidate:
- Reproduce on the current binary. Re-run the same command only when
it is a read op (
search-*,find-*,impact,who-calls,call-path,scope-task,pack-context,repo-state,review-changes,diff,commit-history,action-logwithout--clear,recallsearch/show/sessions/status). A repository mutation (commit,push,new-branch,fast-forward,sync-branch,build-index) runs only inside a throwawaygit initfixture, never in the user's repo. Never replay a host-wide command (install,uninstall,self-update,daemon start/stop,recall setup): read its code path instead. No longer reproduces → checkpixel commit-history/pixel search-history '<token>'for the fix and mark itfixedwith the commit, not as a suggestion. Judge it against the binary that produced the log, not onlymain: a fix merged after the installed release (pixel --versionon that machine,git tag --contains <sha>) is reported as « corrigé surmain(#N), pas encore publié », with what the user runs until the release. The 2026-09-23 retro of a 0.4.0 machine proposed three changes thatmainalready carried: the pi guard location (#224), the checkout slowdown (#238),doctor's fixes (#240). - Name the cause in the code.
pixel find-symbol/pixel search-contenton the error string, thenpixel pack-contexton the function that emits it. A suggestion names the file and function to change. - Separate pixel from its surroundings. An
index.lockheld by another git process, a pre-commit hook failing, a daemon lock held by a live daemon: pixel's part is at most the error wording or a retry, never the root cause. Say which. - Measure the cost. Occurrences, distinct sessions, distinct repos,
agents, and turns or seconds spent working around it. Quote the command
that produced each number (
.agents/rules/measuring.md).
Step 3 — Classify and rank
| Kind | Destination |
|---|---|
| Bug (wrong answer, crash, hang) | crates/… fix + a regression test that fails without it (.agents/rules/mutation-gate.md) |
| Error that does not say what to do next | the message at its emit site: name the flag, the valid value, the next command |
| Agent misuse of a flag or command | the prompt pixel installs: crates/pixel-install/assets/pixel-agent-prompt.md (and pixel-subagent-prompt.md), or the clap help text |
| Agent bypassed pixel because the answer was worse | the command's output (truth markers, caps, ranking) — not the prompt; a stronger "MUST" does not fix a weak answer |
| Slow read op | profile first, suggest only with a measured number |
| Install, doctor or daemon drift | first check whether a rerun of the install would clear it, without running it on the user's machine (Step 2 forbids replaying host-wide commands, and --repo writes into their repository): run it against a copy, HOME=<scratch> CODEX_HOME=<scratch>/.codex XDG_CONFIG_HOME=<scratch>/.config pixel setup then pixel doctor with the same three variables (all on the command line: CODEX_HOME and XDG_CONFIG_HOME otherwise point the install back at the real files), or for a repo.* check pixel setup --repo <fixture> on a git init fixture seeded with the drifted file; failing that, read the install code path. If a rerun clears it, the install is fine and the friction is that nobody reran it: an upgrade path that skips it, a note nobody read. Propose a change to pixel-install only when the install itself leaves the check red, or a pixel doctor check when nothing reported the drift at all |
| Repo rule or skill gap | .agents/rules/*.md or .agents/skills/*/SKILL.md |
| Not pixel's (user repo, git, another tool) | one line in the report, then drop it |
Score = occurrences × cost per occurrence (turns or seconds) × spread (repos × agents). Rank on it; break ties toward the smaller change. Keep the top five; the rest go under "also seen" in one line each.
Step 4 — Report, then stop
Terminal output, in French, one block per suggestion:
### N. <titre court> — <kind>, score S
Symptôme : ce que l'agent a vu (la commande, le message d'erreur exact)
Preuves : <n> occurrences, <s> sessions, <r> repos · agent:id #turn, invocation_id
Reproduit sur <version> : oui / non (corrigé par <sha>) / corrigé sur main (#N), pas encore publié
Route (lente) : <route> <reason> · <phase dominante> <ms> — ligne `slow.py`
Cause : <fichier>:<fonction> — une phrase
Proposition : le changement, où, et le test qui le prouverait
Effort : S / M / L
End with the dropped items (not pixel's, already fixed, already in the ledger) and ask which suggestions to implement. Implementation then follows CONTRIBUTING.md and the PR doctrine, one branch per suggestion.
Guardrails
- Transcripts from other repos carry business data. Quote only pixel
commands, pixel output and error text. Never copy a customer, subscriber,
plate, email, amount or commit message body from any repository other than
pixel, neither into the local report nor into anything public: an issue or
PR on the pixel repo gets a generic reproduction (
git initfixture, placeholder paths). - Nothing leaves the machine without the user's go. No
gh issue create, no PR, no comment until the user picks a suggestion in the chat. - Read-only by default. Reproductions of mutation ops run in a temp
fixture;
pixel action-log --clearis never part of a retro. - A miss is not an absence. "No friction found" means none in the indexed agents over the window; say which agents were indexed and fresh.
Ledger
After the user answers, append one row per reported or dropped item. The
values are data, never source: a fingerprint is built from error text,
which can hold $(…), quotes or newlines. Write the items as a JSON list
with the file-writing tool (not through a shell command), in the scratchpad,
then hand the file to ledger.py, which validates every item (verdict one of
suggested, picked, fixed, wontfix, not-pixel; ref an agent:id #turn or a GitHub URL), refuses the whole file on one bad item, and appends
with tabs and newlines flattened:
[{"fingerprint": "<command>|<normalised error>", "verdict": "suggested", "ref": "claude:5e6585e2 #300"}]
python3 .agents/skills/pixel-retro/ledger.py <scratchpad>/pixel-retro-items.json
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |