handoff

name	handoff
description	Generate decision-focused session retrospectives at the end of Claude Code sessions. This skill should be used automatically when wrapping up multi-step work to capture decision traces, cognitive bottlenecks, parallelization opportunities, and actionable insights for future sessions.

Session Handoff Retrospective

This skill generates decision-focused retrospectives that capture how decisions were made, not just what was built. The goal is to create session logs that enable faster decision-making in future sessions by learning from cognitive bottlenecks and missed parallelization opportunities.

Purpose

Transform the Configuration Log Loop from outcome-focused documentation to decision-trace documentation that answers:

1. What decisions could have been parallelized? (Missed concurrency opportunities)
2. Why were things done serially? (Cognitive bottlenecks)
3. What judgments could be eliminated next time? (Decision optimization)
4. What core decisions changed and why? (Learning evolution)
5. What rules guide the next session? (Actionable patterns)

When to Use

This skill should be invoked automatically:

• At the end of any multi-step project (3+ steps)
• When wrapping up a session with significant decision-making
• Before transitioning work to another session or agent
• When completing work that modified CLAUDE.md, AGENTS.md, or vault structure

Do NOT use for:

• Simple single-task sessions (e.g., "fix typo in README")
• Pure informational queries with no decisions made
• Sessions that only read/explored code without changes

How to Use

Automatic Invocation Pattern

When completing multi-step work, invoke this skill automatically:

1. Review the session transcript to identify:

   • Key decision points and their context
   • Tasks that were done serially vs. could have been parallel
   • Moments of uncertainty, analysis, or bottlenecks
   • How initial assumptions evolved over the session
   • Patterns that emerged during problem-solving

2. Check for today's configuration log:

   Path: 10. Time/02. Project/YYYYMMDD Claude Code Configuration.md
   

3. Create or update the log following the decision-focused structure:

   • If file doesn't exist: Create using structure from references/retrospective-structure.md
   • If file exists: Append new session content with clear separator
   • Set frontmatter: type: log, up: ["[[Claude Code Configuration]]"]

4. Apply the retrospective structure (see references/retrospective-structure.md):

   • Session Goal (What problem were we solving?)
   • Decisions Made (What/why/alternatives/confidence)
   • Parallelization Analysis (What could have been concurrent?)
   • Cognitive Bottlenecks (What slowed decision-making?)
   • What Changed (How did understanding evolve?)
   • Actionable Insights (Rules for next session)
   • Technical Summary (Brief reference - optional)

5. DO NOT commit - User will manually review and commit when ready

Key Principles

Focus on Decision Traces, Not Outcomes

❌ Outcome narration: "Implemented X, created Y, tested Z" ✅ Decision trace: "Chose X over Y because of constraint Z, enabling W"

Capture Alternatives and Confidence

Every significant decision should include:

• What: The decision made
• Alternatives: Other options considered (even if briefly)
• Why: Context that drove the decision
• Confidence: 0.0-1.0 (how certain)
• Reversible: Can this be changed later?

Identify Parallelization Opportunities

Analyze the session for:

• Opportunities taken: What was done concurrently
• Opportunities missed: What could have been parallel but wasn't
• Why missed: Cognitive reason (false dependency, unclear requirements, etc.)

Name Cognitive Bottlenecks

For decision delays, capture:

• Type: Information gap / Uncertainty / Over-analysis / False assumption
• Trigger: What initiated the bottleneck
• Resolution: How it was resolved
• Prevention: How to avoid next time

Extract Actionable Insights

Generate concrete rules:

• "When X, prefer Y because Z"
• "Avoid pattern A unless condition B"
• "Always check X before doing Y"

These should be specific enough to follow in future sessions.

Formatting Guidelines

Follow Obsidian vault conventions (from AGENTS.md):

YAML Frontmatter:

---
type: log
date_created: YYYY-MM-DD
up:
  - "[[Claude Code Configuration]]"
---

Markdown Structure:

• Use heading hierarchy: ## for main sections, ### for subsections
• Use tabs for list nesting (not spaces)
• Quote wikilinks in YAML: up: ["[[Link]]"]
• Use ISO 8601 dates

Decision Format:

### Decision: [Short Name]

**What:** [Decision made]

**Alternatives Considered:**
- Option A: [Why rejected]
- **Selected: Option B** [Why chosen]

**Context/Trigger:** [What drove this decision]
**Confidence:** [0.0-1.0]
**Reversible:** [Yes/No]
**Impact:** [Effect on system/workflow]

Reference Material

For detailed structure and examples, refer to:

• references/retrospective-structure.md - Complete template with examples and anti-patterns

Integration with Configuration Log Loop

This skill implements the Configuration Log Loop from CLAUDE.md:

Original requirement:

At the start of each conversation:
1. Check if today's log exists: `10. Time/02. Project/YYYYMMDD Claude Code Configuration.md`
2. If not exists, create using Project log.template with `up`: `[[Claude Code Configuration]]`
3. At session end, update the log with:
   - Changes made to CLAUDE.md, AGENTS.md, or settings
   - Reasoning behind changes
   - Next steps if any
4. Use command commit to commit changes

Enhanced implementation:

• Step 1-2: Same (check/create log file)
• Step 3: Use decision-focused retrospective structure instead of basic template
• Step 4: User manually commits after review (not automatic)

What Makes a Good Retrospective

✅ Good Signals

• Captures uncertainty: "Confidence: 0.6 - might need to switch for production"
• Names bottlenecks: "Spent 40min debating X because of Y"
• Identifies parallelization: "Could have researched A ↔ B concurrently"
• Tracks evolution: "Initially assumed X, learned Y when Z happened"
• Extracts patterns: "When deploying without Redis, prefer stateless auth"
• Honest about mistakes: "Over-analyzed refresh tokens (premature optimization)"

❌ Bad Signals

• Just lists outcomes: "Created file X, implemented Y"
• No alternatives: "Decided on approach X" (why not Y or Z?)
• No confidence: Every decision sounds certain and final
• No bottlenecks: Implies perfect execution (unrealistic)
• No parallelization: Everything appears to have been optimally ordered
• Post-hoc justification: Makes everything sound inevitable

Examples

❌ Current Style (Outcome-focused)

## Changes Made

### New Skill: obsidian-frontmatter

#### 1. Implemented Core Operations Script (fm-op.sh)
- **What:** Single composable function for all frontmatter operations
- **Operations:** get, set, delete, validate
- **Effect:** Zero dependencies, full Unicode support

[... continues with implementation details ...]

Problems:

• Doesn't capture WHY decisions were made
• No alternatives considered
• No cognitive bottlenecks identified
• No parallelization analysis
• Can't extract rules for next session

✅ Improved Style (Decision-focused)

## Session Goal

Create a vault-agnostic Obsidian frontmatter management skill that works without dependencies.

## Decisions Made

### Decision: Pure Shell vs. yq

**What:** Use pure bash/awk instead of yq YAML processor

**Alternatives Considered:**
- yq: Robust YAML parsing, semantic understanding
- Pure shell: No dependencies, universally available

**Context:** Obsidian frontmatter is relatively flat (scalars, arrays), not complex nested YAML

**Confidence:** 0.8 (might need yq for complex cases, but unlikely)

**Reversible:** Yes (can switch to yq later if needed)

**Impact:** Zero dependencies, works on any system with bash

### Decision: Functional Composition Pattern

**What:** Single minimal function (fm-op) that composes into bulk operations (fm-bulk)

**Alternatives Considered:**
- Monolithic script with all operations
- Separate scripts for each operation
- **Selected: Composable function** - Easier to test, more flexible

**Context:** Need both single-file and bulk operations

**Confidence:** 0.9 (well-established pattern)

**Reversible:** No (would require rewrite)

**Impact:** Easy to test, users can create custom workflows

## Parallelization Analysis

### Opportunities Missed

**Could have been parallel:**
- Core operation implementation ↔ Documentation skeleton
  - **Why missed:** Assumed docs needed working code to document
  - **Actual dependency:** None - could have written doc structure from design
  - **Potential time saved:** ~20 minutes

**Could have been parallel:**
- validate operation design ↔ bulk operation design
  - **Why missed:** Thought validate was core to bulk operations
  - **Actual dependency:** Weak - bulk just calls core operations
  - **Potential time saved:** ~15 minutes

## Cognitive Bottlenecks

### Bottleneck: YAML Parsing Correctness

**Description:** Repeatedly questioned whether shell parsing could handle edge cases

**Type:** Uncertainty / Over-analysis

**Trigger:** Reading about YAML specification complexity

**Duration:** ~45 minutes of back-and-forth

**Resolution:** Decided to support "Obsidian YAML subset" with clear documentation

**Prevention:** Next time, explicitly define supported subset upfront before implementation

### Bottleneck: Validate Function Bugs

**Description:** Spent significant time debugging mixed valid/invalid property handling

**Type:** Premature commitment

**Trigger:** Assumed validation was critical for v1

**Resolution:** Accepted bugs, downgraded to "convenience feature"

**Prevention:** Validate should be v2 feature unless blocking

## What Changed

### Validation Importance

**Initial belief:** Validation is core functionality, must work perfectly

**Final state:** Validation is convenience feature, can ship with known bugs

**Trigger for change:** Mixed-valid bug + time cost exceeded value

**Implication:** Should have questioned whether validation was needed for v1

### Core vs. Bulk Separation

**Initial belief:** Bulk operations need special design consideration

**Final state:** Bulk is just composition via find/xargs, trivial

**Trigger for change:** Realized bulk is just calling core operation repeatedly

**Implication:** Could have parallelized bulk and core design from the start

## Actionable Insights

### Decision Rules
- When choosing parser (yq vs shell), explicitly define supported YAML subset first
- Prefer pure shell for Obsidian vault tools (low dependency cost outweighs robustness)
- When designing operations, functional composition > monolithic scripts
- Validation features are v2 unless blocking (don't over-invest early)

### Process Improvements
- Write documentation skeleton in parallel with implementation
- Question whether "core" features are actually needed for v1
- Design core and bulk operations concurrently (false dependency)

### Patterns Identified
- **Heuristic parser documentation:** When implementing heuristic YAML parsing, lead with "Supported subset" section to manage expectations
- **Validate-bulk false coupling:** Bulk operations don't need special design - they're just composition

Why this is better:

• Captures decision reasoning with alternatives and confidence
• Identifies two parallelization opportunities with time estimates
• Names two specific cognitive bottlenecks (uncertainty, premature commitment)
• Tracks two conceptual shifts during the session
• Extracts four concrete, actionable rules for future sessions
• Can learn from these patterns in next session

Checklist for Good Retrospective

Before finishing the retrospective, verify:

• Session goal clearly states the problem, not the solution
• 3-7 key decisions captured with alternatives and confidence
• At least 1-2 parallelization opportunities identified (taken or missed)
• 1-3 cognitive bottlenecks named with type and prevention
• 1-3 conceptual shifts captured (what changed and why)
• 3-5 actionable insights extracted (specific rules, not vague principles)
• Technical summary is minimal (2-5 bullets) or omitted
• Honest about uncertainty, mistakes, and missed opportunities
• Focuses on decisions, not implementations
• File follows Obsidian formatting conventions

Common Questions

Q: How long should a retrospective be? A: 500-1500 words typically. Focus on quality over quantity. Better to have 3 well-analyzed decisions than 10 shallow ones.

Q: What if there were no major bottlenecks or missed opportunities? A: This is rare. Look harder. Even smooth sessions have micro-bottlenecks (brief uncertainty, minor false assumptions). Documenting these builds pattern recognition.

Q: Should I include every decision made? A: No. Focus on significant decisions (architectural, approach, scope). Omit trivial implementation details. Ask: "Would this decision matter in the next session?"

Q: What if I'm not confident about the retrospective structure? A: Start simple. Capture: (1) What problem was solved, (2) Key decision with alternatives, (3) One thing that could have been better. Build from there.

Q: How do I identify cognitive bottlenecks in the moment? A: Look for: repeated analysis of same topic, uncertainty lasting >10min, premature deep-dives, false assumptions discovered later, circular discussions.

Q: What if the session was just exploration/research? A: Focus on: What was learned, what hypotheses changed, what would be done differently next time, what are the key insights that inform future work.