storytelling

Cria/Atualiza:

• .planning/storytelling/<module-slug>.md — relatório com story + inventário + CRC + hot spots

Após: o user reduz tempo de comprehension de codebase desconhecido de 4-8h (leitura cega manual) para 30 min (revisão informada de IA primeiro draft). Pré-requisito recomendado para /encontrar-seams ou /refactor-seguro em código novo.

Exemplos:

/storytelling src/orders/                                       # diretório completo
/storytelling src/orders/OrderService.ts                        # arquivo específico
/storytelling src/orders/ --depth=shallow                       # rápido — só story + inventário
/storytelling src/orders/ --include-tests                       # incluir tests no scope
/storytelling supabase/functions/process-payments/              # Edge Function module

Quando este comando é o caminho:

• Você herdou módulo desconhecido (onboarding, transferência, post-acquisition)
• Vai modificar código que não conhece
• Pré-requisito de /encontrar-seams ou /refactor-seguro
• Precisa identificar candidates de extract class antes de planejar refactor
• Code review onde reviewer não conhece o módulo

Quando NÃO é o caminho:

• Codebase < 200 linhas — leitura direta é mais rápida
• Você já trabalhou no módulo nas últimas 2 semanas — mental model fresco
• Mudança trivial (typo, comment) — overhead > valor

1. Parsear argumentos

TARGET=$(echo "$ARGUMENTS" | awk '{print $1}')
DEPTH=$(echo "$ARGUMENTS" | grep -oE -- '--depth[= ][^ ]+' | sed 's/--depth[= ]//')
MAX_LINES=$(echo "$ARGUMENTS" | grep -oE -- '--max-lines [0-9]+' | awk '{print $2}')
OUTPUT_PATH=$(echo "$ARGUMENTS" | grep -oE -- '--output [^ ]+' | awk '{print $2}')
INCLUDE_TESTS=false
echo "$ARGUMENTS" | grep -qE -- '--include-tests' && INCLUDE_TESTS=true

[ -z "$DEPTH" ]     && DEPTH="deep"
[ -z "$MAX_LINES" ] && MAX_LINES=1500

if [ -z "$TARGET" ]; then
  echo "ERROR: target obrigatório (arquivo ou diretório)"
  exit 1
fi

if [ ! -e "$TARGET" ]; then
  echo "ERROR: target não encontrado: $TARGET"
  exit 1
fi

# auto-output path
if [ -z "$OUTPUT_PATH" ]; then
  SLUG=$(basename "$(realpath "$TARGET")" | sed 's/[^a-zA-Z0-9]/-/g')
  OUTPUT_PATH=".planning/storytelling/${SLUG}.md"
fi

mkdir -p "$(dirname "$OUTPUT_PATH")"