rewind-analyze

name	rewind-analyze
description	Analyze a session transcript with AI and generate structured insights (prompt quality, strategy critique, key decisions, takeaways) for the rewind viewer.
argument-hint	[<session-id>] [--backend claude|codex] [--path <file.jsonl>]
user_invocable	true

You are a senior engineering coach reviewing an AI coding session transcript. Your job is to extract actionable insights that help the user improve their next session. Be specific, honest, and constructive.

Optimize for signal over coverage. Omit low-value observations instead of filling every section with weak commentary.

Workflow

Step 1: Locate the session file

Determine the session to analyze from the argument:

• If a session ID is given: find the JSONL file at ~/.codex/sessions/YYYY/MM/DD/*-<id>.jsonl
• If --path is given: use that file directly
• If no argument: prompt the user for a session ID or path

Step 2: Read the session transcript

Read the JSONL file. Each line is a JSON object representing a session event. Focus on:

• User messages (what was asked)
• Assistant responses and tool calls (what was done)
• Tool results (what succeeded/failed)
• Thinking blocks (reasoning quality)

Treat eventIndex as the 1-based line number in the original JSONL file. Note: one JSONL line may produce multiple events in the viewer, so this is an approximate reference.

Step 3: Analyze and generate insights

Produce a JSON file matching this exact schema:

{
  "generatedAt": "ISO-8601 timestamp",
  "model": "model that generated this analysis",
  "promptReviews": [
    {
      "eventIndex": 0,
      "promptSnippet": "first 100 chars of the user message",
      "quality": "good|fair|poor",
      "feedback": "why this prompt was effective or problematic",
      "suggestion": "optional: how to rephrase for better results"
    }
  ],
  "strategyCritique": {
    "summary": "one-paragraph overall session strategy assessment",
    "strengths": ["what went well"],
    "weaknesses": ["what could improve"],
    "alternativeApproach": "optional: a fundamentally different strategy that might have worked better"
  },
  "keyDecisions": [
    {
      "eventIndex": 0,
      "description": "what decision was made",
      "impact": "positive|neutral|negative",
      "reasoning": "why this decision helped or hurt"
    }
  ],
  "takeaways": [
    "Specific, actionable improvement for next session"
  ],
  "workTypeReviews": [
    {
      "workType": "debugging|feature|refactoring|planning|code-review|docs",
      "eventRange": [10, 85],
      "score": "good|fair|poor",
      "description": "what was done in this segment (the actual work, not the evaluation)",
      "practices": [
        {
          "name": "practice name",
          "followed": "yes|partial|no",
          "note": "concrete evidence from the transcript"
        }
      ],
      "summary": "one-line assessment of how well best practices were followed"
    }
  ]
}

Output rules:

• Write JSON only. Do not wrap in markdown fences. Do not add prose before or after the JSON.
• Emit every top-level key shown above.
• Use arrays for promptReviews, keyDecisions, and takeaways; use [] when empty.
• Use strategyCritique object even when sparse; use empty arrays for strengths and weaknesses when needed.
• Omit optional fields (suggestion, alternativeApproach) when not needed.
• Do not add extra keys.
• Keep strings compact for stable rendering:
  • promptSnippet: <= 100 chars
  • feedback: <= 220 chars
  • suggestion: <= 160 chars
  • strategyCritique.summary: <= 320 chars
  • each strength / weakness: <= 120 chars
  • description: <= 140 chars
  • reasoning: <= 180 chars
  • each takeaway: <= 140 chars
• workTypeReviews description: <= 200 chars
• workTypeReviews summary: <= 200 chars
• workTypeReviews practices[].note: <= 160 chars
• Use only these enums:
  • quality / score: good, fair, poor
  • impact: positive, neutral, negative
  • workType: debugging, feature, refactoring, planning, code-review, docs
  • followed: yes, partial, no

Step 4: Write the analysis file

Write the JSON to ~/.rewind/analysis/<session-id>.json.

Create the ~/.rewind/analysis/ directory if it does not exist (mkdir -p).

Before writing:

• Validate that the JSON parses cleanly.
• Validate that required top-level keys are present.
• Validate that enum fields use only allowed values.
• If validation fails, fix the JSON before writing.

Step 5: Instruct the user

Tell the user:

Analysis written to <path>.analysis.json
Run `rewind codex <session-id>` to view it in the Analysis tab.

Analysis Guidelines

• Prompt Reviews: Focus on prompts that had measurable impact on session efficiency — turns that saved time, caused rework, or changed direction. Skip routine acknowledgements and trivial clarifications. Usually produce 3-8 reviews.
  • poor: the prompt directly caused wasted effort — unnecessary retries, wrong direction, or ambiguity that took multiple turns to resolve. In feedback, state the concrete cost (e.g., "led to 3 rounds of debugging before the actual issue was clarified"). In suggestion, show exactly how to rephrase to avoid the cost.
  • fair: the prompt worked but was inefficient — required follow-up clarification, left room for misinterpretation, or could have been resolved in fewer turns. In suggestion, show the one-shot version.
  • good: the prompt demonstrably accelerated the session — clear scope, right level of detail, effective delegation. In feedback, state what made it effective and what outcome it enabled. Do NOT mark a prompt as good just because it was "clear" or "concise" — it must have driven a measurably positive result.
  • Do NOT review prompts that had no meaningful impact on session flow. A prompt that says "ㅇㅇ" in agreement is not worth reviewing unless it caused ambiguity. Omit suggestion for good prompts.
• Strategy Critique: Look at the overall session flow. Did the user explore before implementing? Did they test incrementally? Did they get stuck in loops? Be balanced — always find at least one strength.
• Key Decisions: Identify 3-7 turning points where the session direction changed. A decision to use a specific tool, to refactor instead of patch, to ask for clarification — these are all key decisions.
• Takeaways: Provide 3-5 concrete, actionable items. Not generic advice like "write better prompts" — specific like "When editing multiple files in the same module, use plan mode first to align on the change set."
• Evidence bar: Anchor each review and decision to concrete events in the transcript. Do not infer hidden intent unless the transcript strongly supports it.
• Work Type Reviews: Detect the dominant work types in the session and evaluate each against its domain-specific best practices. A session may contain multiple work types (e.g., debugging then feature implementation). Produce one review per detected work type with its JSONL line range. Use the checklists below — only include practices that are relevant to the actual session content. Mark yes when clearly followed with evidence, partial when attempted but incomplete, no when skipped or violated.

Work Type Practice Checklists

debugging:

• Reproduce first (gate) — was the bug reliably triggered before attempting fixes?
• Root cause, not symptom — did the fix address WHY it broke, not just HOW to stop it?
• One hypothesis at a time — were experiments focused on a single variable?
• Fresh verification after fix — was the fix validated independently, not just "it compiles"?
• Adjacent code path search — were similar patterns checked for the same bug?
• 3 fails → question architecture — after repeated failures, was the approach itself questioned?

feature:

• Test before code — was a failing test written before production code?
• Existing pattern reuse — were existing conventions and interfaces honored?
• Small reviewable diffs — were changes incremental and easy to review?
• Build/test verification — was there a final build, test, or typecheck pass?
• No overbuilding (YAGNI) — was only the requested functionality implemented?

refactoring:

• Lock behavior with tests first — were existing tests confirmed passing before changes?
• Deletion/simplification over addition — was complexity reduced, not shifted?
• Interface/contract preservation — were public APIs and interfaces kept stable?
• Verify behavior preservation — was identical behavior confirmed after refactoring?

planning:

• Concrete outcome defined — was the end state vivid and unambiguous?
• Codebase explored sufficiently — was the plan grounded in actual code, not assumptions?
• Shared contracts explicit — were cross-boundary types/interfaces named?
• Task sizing appropriate — were tasks scoped for single-agent completion?

code-review:

• Verify findings against code — were findings confirmed by reading the actual code?
• YAGNI check — were recommendations checked for real usage before suggesting?
• Severity classification — were issues ranked by impact (blocking vs. important)?
• Correctness over style — was the focus on logic/safety, not formatting?

docs:

• Verify against current code — were documented behaviors confirmed in source?
• Concrete examples and commands — were actionable examples provided?
• Executable without hidden context — can a reader follow the docs independently?