/crystallize

description: "After a session or an incident, turn what happened into reusable knowledge — `learn` captures this session's lessons, review/approve promotes incident patterns into agent improvements, `skill` turns a repeating procedure into a skill."
argument-hint: '[learn [focus] | approve GP-NNNN [--no-eval "reason"] | reject GP-NNNN <reason> | rollback GP-NNNN | prune | status | skill [name]]'
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task
model: sonnet

<!-- great_cto-managed -->

You are the great_cto knowledge crystallization command. You read incident knowledge extractions (KE files), promote them to global patterns (GP files), and propose concrete improvements to agent workflow files. Human approves every agent change. `learn` feeds this flow from the current session (continuous-learner → `lessons.md`); `skill` captures a repeating procedure as a skill.

**Privacy rule:** GP files and proposals never contain project names, client names, URLs, credentials, or identifying data. Generic technology descriptors only. See `skills/great_cto/references/knowledge-extraction.md` for the full privacy checklist.

---

Setup

KE_DIR=~/.great_cto/extractions
GP_DIR=~/.great_cto/global-patterns
PROPOSAL_DIR=~/.great_cto/proposals
METRICS_DIR=~/.great_cto/metrics

mkdir -p "$KE_DIR" "$GP_DIR" "$PROPOSAL_DIR" "$METRICS_DIR"

# Plugin dir (for agent files)
PLUGIN_DIR=$(find ~/.claude -name "ARCHETYPES.md" -path "*/great_cto/*" 2>/dev/null | sort -V | tail -1 | xargs dirname)
[ -z "$PLUGIN_DIR" ] && PLUGIN_DIR=$(dirname "$(find . .great_cto \
  -name "ARCHETYPES.md" 2>/dev/null | head -1)" 2>/dev/null)

TODAY=$(date +%Y-%m-%d)

---

Dispatch by argument

ARG="${1:-status}"
case "$ARG" in
  # `approve GP-NNNN [--no-eval "<reason>"]` — the flag is the ONLY way to
  # activate a pattern that carries no eval evidence, and the reason is logged.
  approve)   SUBCOMMAND=approve; GP_ID="$2"
             if [ "$3" = "--no-eval" ]; then NO_EVAL_REASON="${*:4}"; fi ;;
  reject)    SUBCOMMAND=reject;  GP_ID="$2"; REASON="${@:3}" ;;
  rollback)  SUBCOMMAND=rollback; GP_ID="$2" ;;
  propose)   SUBCOMMAND=propose; GP_ID="$2" ;;   # NEW: Sprint 3 — PR-gate
  prune)     SUBCOMMAND=prune ;;
  skill)     SUBCOMMAND=skill; SKILL_ARG="${*:2}" ;;   # a repeating procedure → skills/<name>/SKILL.md (was /skillify)
  learn)     SUBCOMMAND=learn; FOCUS="${*:2}" ;;       # run continuous-learner on this session → .great_cto/lessons.md (was /learn)
  status)    SUBCOMMAND=status ;;
  *)         SUBCOMMAND=review ;;  # default: show pending KEs + proposals
esac

---

Subcommand: status / review (default)

Show all pending KE files not yet promoted + all proposals awaiting approval.

echo "=== CRYSTALLIZE STATUS ==="
echo ""

# Pending KE files
PENDING_KE=$(ls "$KE_DIR"/KE-*.yaml 2>/dev/null | while read f; do
  if ! grep -q "^promoted_to:" "$f" 2>/dev/null; then echo "$f"; fi
done)

KE_COUNT=$(echo "$PENDING_KE" | grep -c "." 2>/dev/null || echo 0)
echo "Pending extractions (KE): $KE_COUNT"
if [ "$KE_COUNT" -gt 0 ]; then
  echo "$PENDING_KE" | while read ke; do
    KE_ID=$(grep "^ke_id:" "$ke" | awk '{print $2}')
    AGENT=$(grep "^target_agent:" "$ke" | awk '{print $2}')
    CONF=$(grep "^confidence:" "$ke" | awk '{print $2}')
    ITER=$(grep "^  iterations:" "$ke" | awk '{print $2}')
    MTTR=$(grep "^mttr_reduction_estimate:" "$ke" | sed "s/mttr_reduction_estimate: //")
    echo "  • $KE_ID → $AGENT (confidence=$CONF iter=$ITER mttr_reduction=$MTTR)"
  done
fi

echo ""

# Pending proposals
PENDING_PROP=$(ls "$PROPOSAL_DIR"/PROPOSAL-*.md 2>/dev/null | while read f; do
  if grep -q "^Status: PENDING_APPROVAL" "$f" 2>/dev/null; then echo "$f"; fi
done)

PROP_COUNT=$(echo "$PENDING_PROP" | grep -c "." 2>/dev/null || echo 0)
echo "Pending proposals (GP): $PROP_COUNT"
if [ "$PROP_COUNT" -gt 0 ]; then
  echo "$PENDING_PROP" | while read prop; do
    GP_ID=$(grep "^GP_ID:" "$prop" | awk '{print $2}')
    TARGET=$(grep "^Target agent:" "$prop" | sed "s/Target agent: //")
    EVIDENCE=$(grep "^Evidence:" "$prop" | sed "s/Evidence: //")
    echo "  • $GP_ID → $TARGET — $EVIDENCE"
  done
  echo ""
  echo "Run: /crystallize approve <GP-ID> | /crystallize reject <GP-ID> <reason>"
fi

# Active pattern stats
ACTIVE=$(ls "$GP_DIR"/GP-*.md 2>/dev/null | \
  xargs grep -l "^status: active" 2>/dev/null | wc -l | tr -d ' ')
TOTAL_HITS=$(grep -rh "^hits:" "$GP_DIR" 2>/dev/null | \
  awk -F': ' '{sum+=$2} END{print sum+0}')
echo ""
echo "Active patterns: ${ACTIVE:-0} | Total hits: ${TOTAL_HITS:-0}"
echo "Run /crystallize (no args) to review, or /crystallize prune to archive stale patterns"

---

Subcommand: review (promote KE → GP + generate proposals)

Run when there are pending KE files. For each qualifying KE: 1. Check noise filter (confidence + iterations thresholds) 2. Check deduplication (slug already in GP_DIR?) 3. Generate GP-NNNN file 4. Generate PROPOSAL-*.md with concrete agent diff

# Noise filter thresholds
MIN_ITERATIONS_MEDIUM=5   # medium confidence requires 5+ iterations
MIN_ITERATIONS_LOW=8      # low confidence requires 8+ iterations

echo "=== REVIEWING KE FILES ==="
echo ""

ls "$KE_DIR"/KE-*.yaml 2>/dev/null | while read ke_file; do
  # Skip already promoted
  grep -q "^promoted_to:" "$ke_file" 2>/dev/null && continue

  KE_ID=$(grep "^ke_id:" "$ke_file" | awk '{print $2}')
  CONFIDENCE=$(grep "^confidence:" "$ke_file" | awk '{print $2}')
  ITERATIONS=$(grep "^  iterations:" "$ke_file" | awk '{print $2}')
  IS_CANDIDATE=$(grep "^  pattern_candidate:" "$ke_file" | awk '{print $2}')
  TARGET_AGENT=$(grep "^target_agent:" "$ke_file" | awk '{print $2}')
  TARGET_SKILL=$(grep "^target_skill:" "$ke_file" | awk '{print $2}')
  SLUG=$(echo "$KE_ID" | sed 's/KE-[0-9-]*-//')

  # Validate routing: must have exactly one of target_agent / target_skill
  if [ -z "$TARGET_AGENT" ] && [ -z "$TARGET_SKILL" ]; then
    echo "  SKIP: KE has no target_