agentleFS
Sign inStart free
levyfluxlevyflux/codex-skills/skills/codex-session-retrospective/SKILL.md

codex-session-retrospective

Skill1 starsChanged 3 months agoMITView on GitHub

Review recent Codex session logs for repeated repair loops, missing handoffs, weak validation, and evidence gaps. Use for weekly agent-workflow retrospectives, prompt or instruction improvement, and privacy-preserving scorecards across one workspace; do not use it as proof that product behavior is correct.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Treat the analyzer's classifications as heuristics, not product or runtime proof.

    line 12
  2. Distinctive:

    Never emit user prompts, tool arguments, secrets, or source snippets in the scorecard.

    line 13
  3. Distinctive:

    Keep review read-only unless the user separately authorizes instruction, skill, or repository changes.

    line 15
  4. Distinctive:

    Run the analyzer and record parse errors, excluded current-session behavior, and sampling limits.

    line 37

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Codex Session Retrospective

Turn recent Codex session history into a prompt-safe workflow scorecard and a small set of durable improvements.

Boundaries

  • Treat the analyzer's classifications as heuristics, not product or runtime proof.
  • Never emit user prompts, tool arguments, secrets, or source snippets in the scorecard.
  • The report retains workspace and session-file metadata for investigation; review it before sharing.
  • Keep review read-only unless the user separately authorizes instruction, skill, or repository changes.
  • Compare representative findings with current Git, test, runtime, or deployment evidence before recommending a change.

Run the analyzer

Requires Ruby 2.6 or newer and only the standard library.

ruby scripts/analyze_sessions.rb --workspace "$PWD" --days 7 --json

Useful options:

  • --since YYYY-MM-DD selects a fixed local start date.
  • --sessions-root PATH overrides ~/.codex/sessions.
  • --output-dir PATH writes prompt-safe JSON and Markdown scorecards.
  • --strict exits with status 1 when heuristic findings exist.
  • --include-current includes the active CODEX_THREAD_ID; omit it for stable reviews.

Review workflow

  1. Fix the workspace, time window, and timezone before comparing review periods.
  2. Run the analyzer and record parse errors, excluded current-session behavior, and sampling limits.
  3. Inspect representative sessions for the highest-frequency findings without copying prompt text into durable artifacts.
  4. Cross-check repository state, final answers, tests, runtime evidence, and external target evidence as applicable.
  5. Separate workflow friction from product defects and from harmless variance.
  6. Recommend the smallest durable intervention: clarify instructions, improve a reusable skill, add a deterministic helper, or leave the system unchanged.
  7. Re-run the same fixed-window scorecard after changes and report what the comparison does and does not prove.

Output contract

Report:

  • exact time window and workspace;
  • session, turn, compaction, tool-call, and tool-failure counts;
  • repeat-repair cues and evidence-gap findings;
  • representative evidence checked outside the heuristic scorecard;
  • changes made, if authorized;
  • remaining gaps and the next review condition.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free