retrospective

SpecSwarm Chunk Retrospective

Auto-distills the lessons from a completed feature/chunk into 1–3 durable memory entries. Combats the failure mode where a Claude Code session ends and its accumulated wisdom (corrections, decisions, drifts caught) disappears — only memory files persist.

The subagent (chunk-retrospective) reads structured signals from the chunk and writes new feedback_*.md / project_*.md / intervention_*.md files directly to the project's memory directory. This command then updates MEMORY.md per file.

Recommended workflow: run this BEFORE /ss:ship, so the new memory files are part of the squash commit.

Phase 1: Resolve feature + parent branch

PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
# shellcheck disable=SC1091
source "${PLUGIN_DIR}/lib/features-location.sh"
# shellcheck disable=SC1091
source "${PLUGIN_DIR}/lib/references-loader.sh"
# shellcheck disable=SC1091
source "${PLUGIN_DIR}/lib/intervention.sh"
# shellcheck disable=SC1091
[ -f "${PLUGIN_DIR}/lib/notify.sh" ] && source "${PLUGIN_DIR}/lib/notify.sh"

# Parse args
FEATURE_NUM=""
PARENT_OVERRIDE=""
DRY_RUN=false

while [ $# -gt 0 ]; do
  case "$1" in
    --parent)  PARENT_OVERRIDE="$2"; shift 2 ;;
    --dry-run) DRY_RUN=true;          shift ;;
    -h|--help)
      cat <<EOF
Usage: /ss:retrospective [FEATURE_NUM] [options]

Auto-retrospective for a completed SpecSwarm feature.

Options:
  --parent BRANCH    Override parent branch (default: build-loop.state, then main/master)
  --dry-run          Show what would be sent to the agent; don't dispatch or write

Examples:
  /ss:retrospective
  /ss:retrospective 002
  /ss:retrospective --parent develop
  /ss:retrospective --dry-run
EOF
      exit 0
      ;;
    *)
      if [ -z "$FEATURE_NUM" ]; then FEATURE_NUM="$1"; fi
      shift
      ;;
  esac
done

REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

# Resolve feature
if [ -z "$FEATURE_NUM" ]; then
  # Try current branch (NNN-slug)
  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
  FEATURE_NUM=$(echo "$BRANCH" | grep -oE '^[0-9]{3}' || echo "")
fi

if [ -z "$FEATURE_NUM" ]; then
  # Fall back to latest feature dir
  get_features_dir "$REPO_ROOT"
  FEATURE_NUM=$(find "$FEATURES_DIR" -maxdepth 1 -type d -name '[0-9][0-9][0-9]-*' 2>/dev/null \
    | sort | tail -1 | xargs -n1 basename 2>/dev/null \
    | grep -oE '^[0-9]{3}' || echo "")
fi

if [ -z "$FEATURE_NUM" ]; then
  echo "❌ No feature number provided and no feature dirs found." >&2
  exit 2
fi

if ! find_feature_dir "$FEATURE_NUM" "$REPO_ROOT"; then
  echo "❌ Feature $FEATURE_NUM not found under $FEATURES_DIR" >&2
  exit 2
fi
FEATURE_ID=$(basename "$FEATURE_DIR")

# Resolve parent branch
PARENT_BRANCH="$PARENT_OVERRIDE"
if [ -z "$PARENT_BRANCH" ]; then
  STATE="${REPO_ROOT}/.specswarm/build-loop.state"
  if [ -f "$STATE" ]; then
    PARENT_BRANCH=$(grep -E '^parent_branch=' "$STATE" 2>/dev/null | head -n1 | cut -d= -f2- | tr -d '"' || echo "")
  fi
fi
if [ -z "$PARENT_BRANCH" ]; then
  for candidate in main master; do
    if git -C "$REPO_ROOT" rev-parse --verify "$candidate" >/dev/null 2>&1; then
      PARENT_BRANCH="$candidate"
      break
    fi
  done
fi
PARENT_BRANCH="${PARENT_BRANCH:-main}"

echo "🔍 Retrospective target"
echo "  feature:        $FEATURE_ID"
echo "  feature_dir:    $FEATURE_DIR"
echo "  parent_branch:  $PARENT_BRANCH"
echo ""