analyzing-sessions
Analyzes Codex sessions from a user-defined start date through today. Executes SWOT analyses, self-critiques, and self-reflections for each skill, sub-agent, command, workflow-skill, and rule active in the session range, reading generated output artifacts (concept cards, plans, handoff reports) in scope and re-verifying their stated open items against current repo state rather than trusting them at face value. Generates classified improvement suggestions grouped by component and priority, persisted to .codex/output/analyzing-sessions/. Use when running a post-session retrospective, auditing skill or agent performance, building an improvement backlog, or identifying systemic issues across skills, agents, and rules from a session or date range.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- analyzing-sessions
- description
- Analyzes Codex sessions from a user-defined start date through today. Executes SWOT analyses, self-critiques, and self-reflections for each skill, sub-agent, command, workflow-skill, and rule active in the session range, reading generated output artifacts (concept cards, plans, handoff reports) in scope and re-verifying their stated open items against current repo state rather than trusting them at face value. Generates classified improvement suggestions grouped by component and priority, persisted to .codex/output/analyzing-sessions/. Use when running a post-session retrospective, auditing skill or agent performance, building an improvement backlog, or identifying systemic issues across skills, agents, and rules from a session or date range.
- allowed-tools
- Read Glob Grep Write Edit Agent Bash(git:* date:*)
02 资源文件 3
- 参考文档references/critique-reflection-framework.md5.8 KB
- 参考文档references/suggestion-taxonomy.md3.4 KB
- 参考文档references/swot-framework.md3.7 KB
03 SKILL.md 正文
Session Analysis
Produce SWOT analyses, self-critiques, and improvement suggestions for every component used across a session range.
Quick Start
- Choose scope — "This conversation" for the current session, or provide a start date for a date range.
- Confirm the Phase 2 component inventory before the analysis runs — output artifacts in scope are read in full, not just listed.
- Skim SWOT + critique output in P1 → P3 priority order.
- Act on the Top 5 Actions from Phase 6, then check the persisted report path.
For date-range retrospectives or deep taxonomy guidance, read the full phases below.
When to Use
- Post-session retrospective after completing a development task
- Auditing how skills, sub-agents, commands, or rules performed during a session
- Building an improvement backlog from multiple observed failures
- After acting on improvement suggestions that affect skill behavior, validate the fix using
skill-tester—skill-evaluation-protocolgoverns the evaluation criteria - Identifying systemic issues that span more than one component
- Any session involving: skills · sub-agents · commands · workflow-skills · rules
When NOT to Use
- Real-time monitoring — this skill is retrospective; it analyzes past behavior, not live state
- No
.codex/components were active — if no skills, agents, commands, or rules were involved, there is nothing to analyze - Single-component review — use
skill-reviewerfor one skill orplugin-validatorfor one plugin; this skill adds overhead without benefit for isolated reviews - Code quality — use
/code-reviewfor diff analysis; this skill covers skill and agent behavior, not code correctness - Want the retrospective's suggestions applied, tested, documented, and committed as a guided pipeline, not just surfaced — use
plugin-lifecycle-maintenance'simprove-a-pluginworkflow after this skill's report is produced; this skill stops at "Top 5 Actions," it never applies them - Full permission-candidate extraction across session transcripts — use
pdk-find-permissions; this skill's own Permission Friction note (Phase 6) is a qualitative observation only, not a substitute for that command's systematic scan
Phase 1: Scope
If a scope was supplied as an argument (a date string, "today", "this conversation", or similar), skip the question UI and proceed directly to Phase 2 using that argument as the scope.
Timezone pitfall — "since last retro" boundaries: a prior retro's own header timestamp is UTC (Z-suffixed, e.g. 2026-07-24T10:44:23Z), but local file mtimes (used to locate output artifacts and session transcripts in Phase 2) are in local time. Convert the UTC boundary to local before comparing — e.g. 10:44:23Z on a UTC+2 machine is 12:44:23+02:00 local, not 10:44:23 local. Treating the boundary as already-local silently shifts the window earlier than intended and can wrongly exclude or include artifacts near the boundary.
Ask for the session range only when no argument was provided:
questions: [
{
question: "What should this analysis cover?",
header: "Session scope",
options: [
{ label: "This conversation", description: "Analyze only the current conversation context" },
{ label: "From a start date", description: "Provide a YYYY-MM-DD start date; analysis runs through today" },
{ label: "Today", description: "All sessions from today (default)" }
],
multiSelect: false
}
]
If "From a start date" → ask for the date. If sessions from prior conversations are in scope, check for on-disk transcripts first — see "Prior-session data" in Gotchas below for the resolution procedure. Only ask the user to paste in transcript excerpts or summaries when no matching file exists on disk for the requested scope.
Phase 2: Component Inventory
Run these Globs first, unconditionally — before evaluating scope or waiting for confirmation:
Glob(pattern='*', path='.codex/output')— output artifacts from prior runsGlob(pattern='*.md', path='.codex/rules')— rules that load automatically, often without being mentioned in conversationGlob(pattern='*.local.md', path='.draft')— local, gitignored planning documents (e.g. a roadmap or architecture draft) — this repo's only recurring*.local.mdconvention lives here, not under.temp/or elsewhere in.draft/; don't broaden the pattern to those, they hold staged plugin source components, not planning documents
Use the path parameter form above, not a bare relative pattern like Glob('.codex/rules/*.md') — on at least one observed environment, a pattern with a literal leading .codex/ segment silently returned no results even though matching files existed, while pointing path directly at the target directory with a bare pattern resolved correctly. A silent false negative here means rules or prior output artifacts go uncounted without any visible error, so treat an empty result from either call as suspect: retry once with a broader pattern (e.g. Glob(pattern='**/*', path='.codex/rules')) before concluding the category is genuinely empty.
These seed the inventory regardless of scope. Then identify every additional component from the current conversation context.
Read output artifacts, don't just list them. For every file the first Glob found whose modification time falls inside the session range, and that looks like a generated/linked artifact from a plugin-devkit pipeline skill (concept cards under plugin-ideation/, plans under plugin-planning/, handoff reports under build-handoff-writer/, comparison reports under plugin-comparison/, grader reports under plugin-grader/, dev-rules reports under rules/), Read it in full — not just its path. The artifact's content is itself evidence about the component(s) that produced or consumed it: a Concept Card's Overlap Check section is evidence for plugin-ideation's SWOT, a handoff report's Commits section is evidence for build-handoff-writer's SWOT, and so on. A component whose only evidence is "it ran" (from the conversation) but whose actual output was never read is assessed on incomplete information.
Verify Open Items — don't trust an artifact's self-report. For every handoff-report-shaped artifact read above (or any artifact with an "Open Items"/"Findings"/"Unresolved" section), independently re-check each listed item against current repository state before treating it as still accurate:
- A commit SHA or count claimed in the artifact → verify with
Bash(git log)/Bash(git show)directly (e.g. compare${#SHA}against the actualgit log -1 --format=%Houtput) - A "deferred" or "not yet fixed" item →
Grep/Readthe referenced file(s) to check whether it was actually addressed in a later commit or session, even if the artifact itself was never updated to reflect that - A "still open" claim → check whether a later artifact in the same scope (e.g. a subsequent handoff-report update, a later plugin-grader re-audit) already resolved it, and the earlier artifact is simply stale rather than wrong
Record any discrepancy found — an item marked open that's actually resolved, an item marked resolved that isn't, or a factual claim (a SHA length, a file count) that doesn't match a direct check — as a Weakness in the SWOT of the component that produced the artifact, not as a note about the artifact file itself. This mirrors a documented real incident in this plugin's own session history: a
build-handoff-writerreport flagged its own inline-supplied commit SHA as "41 hex characters" (a miscount) rather than the correct 40, and a fix-pass's own dispatch prompt claimed "4 new commits" when there was exactly one — both were only caught because a later step independently re-verified rather than trusting the artifact's own text.
Commit SHA doesn't resolve at all — fix it, don't just flag it. This is a standing responsibility of this skill, distinct from the general Weakness-recording treatment above: if a SHA referenced in a handoff-report-shaped artifact doesn't resolve via git show <SHA> at all (not merely miscounted, but genuinely absent from history), the most common cause is a rebase-merge (gh pr merge --rebase) rewriting the commit after the report was written. Search git log --oneline on the merge target branch for a commit with matching message and file scope. If found with high confidence, ask via AskUserQuestion whether to fix the stale reference(s) directly in the source artifact now — Edit, scoped narrowly to the exact stale-SHA-to-correct-SHA replacement(s), nothing else in the file. If approved, apply the fix and note it in this report's own Weakness entry as [FIXED] rather than [FLAGGED], naming the old and new SHA. Do not rewrite a SHA that still belongs to an unmerged branch — verify it against that branch's own history, not the merge target's, and annotate it as branch-only rather than treating it as stale. If no confident message-match exists, fall back to the general Weakness-recording treatment above rather than guessing.
Read local planning documents as state, not as pipeline artifacts. For every file the third Glob found (.draft/*.local.md) whose modification time falls inside the session range, Read it in full — this is the session's actual durable work-product when the session involved planning/roadmap/architecture work, and it's easy to miss because it never produces an invocation event the way a Skill/Agent call does. Unlike the handoff-report-shaped artifacts above, don't run these through the Verify Open Items check — a planning document doesn't carry "Open Items"/commit-SHA claims to re-verify, it just carries current decisions and scope. Because these files are gitignored, there's no git history to diff against for a prior version; for a scope that starts before the current conversation, recovering an earlier state of a .draft/*.local.md file requires the user to paste it in, same as any other prior-conversation content (see Phase 1's note above and the Gotchas below).
| Category | What counts |
|---|---|
| Skill | Slash-command invocations that loaded a SKILL.md (e.g. /skill-refiner-interactive) — or a skill's SKILL.md/references/*.md/scripts/* files that were directly edited this session, even without an invocation event (see note below) |
| Sub-agent | Agent tool spawns (named agent type or description used) |
| Command | .codex/commands/*.md invocations |
| Workflow-skill | Skills invoked as sub-steps inside another skill's workflow |
| Rule | .codex/rules/*.md files loaded and applied during the session |
Invoked vs. edited components: both count, and both get their own SWOT — but frame them differently. An invoked component is assessed on how well it performed when run (did its checks fire, did its output need correction). An edited component (one whose files you modified as a task, without ever loading it via Skill/Agent) is assessed on how well its existing structure/docs supported making that edit correctly, and what defects the edit surfaced. Don't skip edited components just because there's no invocation event to point to as evidence — the edit itself is the evidence.
Emit the inventory before proceeding:
📦 Session Inventory <start> → <end>
| # | Component | Category | Evidence |
Confirm: "Found N components. Proceed with full analysis?"
Phase 3: SWOT Analysis
For each component, produce a SWOT grounded in observed session behavior — not design intent.
### SWOT: <name> (<category>)
| Quadrant | Observations |
| Strengths | … |
| Weaknesses | … |
| Opportunities| … |
| Threats | … |
See references/swot-framework.md for quadrant prompts and common patterns per component category.
Phase 4: Self-Critique and Self-Reflection
For each component, immediately after its SWOT:
Self-Critique — what went wrong:
- Errors, omissions, wrong assumptions made during execution
- Checklist items skipped or gates bypassed
- Output produced that should not have been
Self-Reflection — what would change:
- Alternative approach that would produce better results next time
- Cross-component patterns pointing to a systemic issue
- Meta-lessons that apply beyond this specific component
See references/critique-reflection-framework.md for question sets by category and rationalizations to reject.
Phase 5: Generate and Classify Suggestions
Derive one or more concrete suggestions from each SWOT entry and each critique/reflection point. Discard observations with no actionable change. Merge duplicate suggestions across components into one cross-cutting entry.
Each suggestion:
[S##] [P1|P2|P3] [TYPE] <one-line description>
Source: <SWOT quadrant | Critique | Reflection> Component: <name>
Detail: <what to change and why>
Priority: P1 Critical (breaks behavior), P2 Major (degrades quality), P3 Minor (polish).
Types: FIX · ENHANCE · ADD · REMOVE · AUDIT
See references/suggestion-taxonomy.md for classification rules, merge criteria, and examples.
Phase 6: Grouped Report
Output two views.
By component — each component with its suggestions in P1→P3 order:
## <name> (<category>)
[S01] P1 FIX …
[S02] P2 ADD …
By classification — all suggestions across components by priority then type:
### P1 — Critical
[S01] skill-reviewer · FIX …
### P2 — Major
…
### P3 — Minor
<details><summary>N minor suggestions</summary>…</details>
Permission friction (if observed): if the session showed the user repeatedly approving or denying the same or similar Bash commands, add a short qualitative note — pattern and approximate frequency, e.g. "approved git push 4x this session." This is a narrative observation only, not an extraction pass; for a full candidate list of permission-rule gaps across session transcripts, point the user to pdk-find-permissions rather than attempting to replicate its extraction here.
Close with Top 5 Actions: the five highest-impact suggestions across all components, in order.
Persist the report: get a timestamp (Bash(date -u +%Y-%m-%dT%H-%M-%SZ)) and Write the full Phase 3-6 output to .codex/output/analyzing-sessions/<scope-slug>-<timestamp>.md, where <scope-slug> is a short kebab-case description of the scope (e.g. this-conversation, 2026-07-10-to-today). Present the confirmation as its own line before the rest of Phase 6's output:
📄 Session Analysis Report written: `.codex/output/analyzing-sessions/<scope-slug>-<timestamp>.md`
This per-run-file format (<scope-slug>-<timestamp>.md, one file per run) is the canonical convention going forward — resolved as of 2026-07-24. .codex/output/analyzing-sessions/ also contains older files from a prior per-component-file convention (one file per component analyzed, predating this format); those are not migrated or deleted by this decision, and don't need to be before persisting a new report — Glob the directory first only if a specific old file's content matters for the current run. Persisting in the per-run format lets other components (notably plugin-lifecycle-maintenance's improve-a-plugin workflow) link back to a specific retro run instead of re-deriving one, and gives the Verify-Open-Items check above something concrete to point future re-checks at.
Suggested next step: for any P1/P2 suggestion, ask with AskUserQuestion: "Expand this suggestion into a full WHAT/WHY/HOW action plan using enhancement-suggestor?" — options "Yes" / "No". If yes, invoke the enhancement-suggestor agent (via Agent) against that suggestion — this skill's own suggestions are intentionally terse (one line + Detail) for cross-component scanning. Never invoke it without asking first.
Testing & Validation
After Phase 6, verify these gates before presenting output as final:
- [ ] Inventory names at least one component per category present in the session
- [ ] Every SWOT quadrant has at least one observation (no empty rows)
- [ ] Every P1 suggestion names a specific file, section, or step in its Detail field
- [ ] Top 5 Actions are drawn from P1 first; P2 entries appear only when no P1 remain
- [ ] No two suggestions share the same Detail description — merge duplicates before emitting
- [ ] Every output artifact found in scope (concept cards, plans, handoff reports, comparison/grader/dev-rules reports) was actually
Read, not just listed by path - [ ] Every Open Items entry found in a re-checked artifact was independently re-verified against current repo state, not copied forward as still-accurate
- [ ] Every non-resolving commit SHA found in a re-checked artifact was searched for a rebase-merge match and, if found, offered to the user as a direct fix — not just recorded as a Weakness and left stale
- [ ] Any
.draft/*.local.mdplanning document modified in scope wasReadfor its current state, not just listed - [ ] The report was persisted to
.codex/output/analyzing-sessions/and its path confirmed with the standard📄 ... written:line - [ ] A date-range scope always checks
~/.codex/sessions/for on-disk transcripts first — the user is only asked to paste transcripts when no matching file exists on disk
Gotchas
- Absence of evidence ≠ absence of use. Rules in
.codex/rules/load automatically — check the directory even if they were never mentioned in conversation. .draft/*.local.mdplanning documents are gitignored, so they have no git history to fall back on. If a scope needs a prior version of one (not just its current state), there's nogit log/git showto recover it — same limitation as "Prior-session data" below, ask the user to paste it.- Weakness vs. Threat confusion. Weaknesses are internal to the component (a missing gate, a wrong threshold). Threats are external (a stale dependency, an upstream change that will break the component). Do not cross-file them.
- Over-suggestion. Not every observation earns a suggestion. If two components produced the same fixable pattern, emit one cross-cutting suggestion, not two identical ones.
- Prior-session data — check on-disk transcripts before asking the user to paste anything. Codex
session transcripts are stored at
~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl(or.json) — seecodex-session-lookup's owninspect-session-file.pyfor reading one file's metadata (id, timestamp, cwd) to confirm it's the right session before mining it. Filter candidates by mtime/directory date against the requested range, then run a cheapGreppre-filter before any full read of a large transcript — for a large transcript, delegate the digest extraction to a background agent dispatch rather than reading it directly in this conversation. Only when no matching transcript file exists on disk for the requested scope does this fall back to asking the user to paste transcripts or summaries. - Self-referential sessions. When
analyzing-sessionsis itself one of the components being analyzed, the assessment is inherently limited — the skill cannot objectively observe its own execution from outside. Note this explicitly in the SWOT weakness quadrant rather than producing inflated self-assessments. - Don't trust an artifact's own "Open Items" section at face value. A handoff report (or similar) reflects what its author believed was true at write time — it is not re-verified just by existing. Treat every "still open" or "resolved" claim as a hypothesis to check against current repo state (Phase 2's Verify Open Items step), not a fact to relay forward. An artifact that's wrong about its own open items is itself a finding about the component that produced it, not noise to filter out.
- Verify prior-state claims before writing them into a commit message or report — including this skill's own. A claim like "this is new" or "X didn't exist before" is a testable assertion about current repo state, the same category as an artifact's Open Items claim above. This skill's own persistence feature was once introduced with exactly this unverified claim ("prior versions only ever showed the report in chat") — false, since an older per-component-file convention already existed on disk and was never checked for first.
Glob/Readthe relevant directory before asserting novelty, whether the claim is about another component or about this one.
Reference Guide
| File | Purpose | When to read |
|---|---|---|
references/swot-framework.md |
Quadrant prompts and category-specific patterns | Phase 3 |
references/critique-reflection-framework.md |
Question sets per category; rationalizations to reject | Phase 4 |
references/suggestion-taxonomy.md |
Priority tiers, type definitions, merge rules, examples | Phase 5 |
enhancement-suggestor agent |
Expands a single P1/P2 suggestion into a full classified WHAT/WHY/HOW plan | Phase 6, on request |
.codex/output/analyzing-sessions/ |
Where this skill's own reports are persisted, one file per run | Phase 6 (write), Phase 2 of a later run (read, if in scope) |
plugin-lifecycle-maintenance's improve-a-plugin workflow |
Typical downstream consumer — takes this skill's persisted report and drives it through a human-decision gate into an applied, committed fix | After this skill's report is produced |
04 同仓库更多 Skills
demo
Fixture skill used by scripts.marketplace_ci sync tests.
export-demo
Fixture skill used by scripts.marketplace_ci export tests.
work-to-development
Validate an accepted Linear Issue's readiness for implementation (criteria, dependencies, duplicate/existing artifacts) and request governed branch/worktree creation through git-kit:starting-work — recording work-started Git/GitHub evidence and a deliberate Linear Started transition only after Git identity is read back and verified. Use when asked to start work on a Linear issue, begin development for an accepted issue, or prepare an accepted issue for implementation. Never creates a branch directly — always delegates to git-kit.
work-linking
Create and maintain stable cross-system links and authority labels between Notion and Linear records, and detect/repair drift between them. Use when asked to link a Notion record to a Linear record, check for drift between Notion and Linear, or repair a broken/stale link. Repairs only the bounded non-authoritative copy or link — never chooses by newest timestamp, and never creates a reverse-write loop against either system's own authority.
status-and-learning
Produce a dated, explicitly non-live Linear-to-Notion progress summary, or capture an outcome/learning after work completes. Use when asked to summarize progress to Notion, report portfolio status, or capture what was learned from a completed piece of work — not to disposition open follow-up items (see open-item-management for that). Never runs automatically or continuously — every summary is a deliberate, approved snapshot, not a live sync.
repository-gates
Discover, delegate, record, and invalidate this repository's actual Git/GitHub lifecycle gates (pre-commit, pre-push, PR required checks, Codex delta review, review requirements, merge rights) and the repository-policy provider profile that maps governed operations to git-kit. Use when asked what gates apply to this repository, to discover repository policy before starting Wave 2 work, or to check whether prior gate evidence is still valid after new commits. Discovery and delegation only — never executes a gate's own internal logic, and never invents a gate the repository doesn't actually define (in particular, never assumes a "Review Changes" gate exists).