[FEATURE] Return to planning session for post-implementation review

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code has a plan mode workflow: the user discusses a task, Claude creates a plan, the user approves it, the context is cleared, and a new session starts for implementation. During planning, the session accumulates deep context — project architecture, database schemas, existing code patterns, discussed edge
cases and decisions. This context cannot be fully conveyed through the plan text alone.

The core problem

A plan describes what to do, but cannot anticipate every implementation detail. The new session implements the plan literally, but may miss non-obvious issues that the planning session would catch instantly — because it has the context.

Today it is possible to manually return to the planning session via claude --resume or /resume in a new terminal, and ask it to review the changes. However:

• The user must already know this is possible and useful
• There is no automatic link between the plan session and the implementation session
• There is no automatic detection of which files were changed after the plan
• The planning session doesn't know it's being resumed for review — the user has to explain manually

Proposed Solution

What already works today (manual workflow)

1. User creates a plan in Session A (plan mode)
2. User approves the plan → context is cleared, Session B starts
3. Session B implements the plan
4. User opens a new terminal, runs claude --resume, and selects Session A
5. Manually asks: "Check the latest commit, review the implementation"
6. Session A catches issues thanks to its accumulated context

This works, but requires knowledge of the process and manual steps at every stage.

What is proposed

1. Session linking. When the user approves a plan and the context is cleared, Session A should:

• Save its session identifier and pass it to Session B
• Record a timestamp (or a file list, or git HEAD if the project is under git) to later determine what changed after the plan

2. One-command return. After implementing the plan in Session B, the user runs a single command (e.g., /review-plan or similar) that:

• Identifies which planning session is linked to the current one
• Switches the user back to Session A (the planning session)

3. Automatic review launch. When Session A is resumed, it should:

• Understand that it's being returned to after plan implementation
• Automatically detect changed files (via git diff, git status, or comparison with the saved timestamp/file list)
• Launch a critical analysis of the implementation with a built-in prompt: compare changes against context, verify patterns, find missed edge cases
• Suggest fixes to the user if issues are found

4. Git independence. The solution should work without Git as well:

• If Git is available → git diff from the saved HEAD
• If Git is not available → compare file mtimes against the saved timestamp from when implementation started

Alternative Solutions

1. Write more detailed plans

Include invariants, edge cases, and verification criteria in the plan itself.
Problem: it's impossible to predict which details will turn out to be critical until you see the implementation. Plans become excessively bloated.

2. Self-review in the implementing session

Ask Session B to re-read the code and check patterns.
Problem: it lacks context — it doesn't know why certain patterns were chosen or what discussions preceded the plan. It doesn't know what to look for.

3. Current manual workaround

Open a new terminal, claude --resume, select the session, manually ask to review.
Works, but is not discoverable — the user has to figure out this workflow on their own.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

A real case from a production project:

Planning

Session A analyzes a geo-data pipeline:

• Prisma schema with a compound unique constraint (countryCode, subdivisionId, nameEnglish) where subdivisionId is nullable
• Existing seed code that pre-loads cities by geonameId before inserting
• ~57 manual cities, of which 42 have NULL subdivisionId

Plan created

"Insert manual cities via createMany({ skipDuplicates: true })" At the plan level, this looked correct.

Implementation

Session B implements the plan faithfully: generates a UUID for each city, uses skipDuplicates, creates translations referencing those UUIDs.

Return to planning session

The user manually returns to Session A and asks it to review the implementation.

Session A instantly finds two critical bugs

1. NULL duplicates: skipDuplicates uses ON CONFLICT, but in PostgreSQL NULL != NULL in unique constraints — 42 cities would be duplicated on every run
2. Orphaned translations: UUIDs are generated before insertion, but if a city already exists (skipped by skipDuplicates), translations are created with UUIDs pointing to non-existent records

Session A caught this because it had in context: the Prisma schema, the MaxMind seed pattern (which pre-loads existing records), and the data distribution. Session B had none of this context.

Fix

Straightforward once identified: pre-load existing cities by compound key (matching the existing MaxMind pattern), reuse their UUIDs, deduplicate manually instead of relying on the database constraint.

Additional Context

Related issues

• #26832 — Plan mode creates a silent session split, no way to track or resume the planning session
• #30438 — Rework Plan Mode into a 1st-class Plan System (covers pre-execution review but not post-implementation review)
• #25689 — Context threshold hook for plan-and-continue workflow (forward direction only)

Key insight

The planning session's context is the most valuable review tool available, because it contains not just what was planned but why, and the full understanding of the project that led to the plan. No amount of plan documentation can fully substitute for this accumulated understanding.