boshu2__agentops/skills-codex/post-mortem/references/context-gathering.md

Context Gathering

How to collect rich context from multiple sources for retrospectives.

Target Identification

If Epic ID Provided

bd show $ARGUMENTS
# Extract child issue IDs, query each for comments

If Topic/Plan Provided

ls .agents/plans/*$ARGUMENTS* 2>/dev/null
ls .agents/research/*$ARGUMENTS* 2>/dev/null

If No Argument

bd list --status closed | head -10

---

Conversation Analysis

If a session ID is available, analyze the Claude Code conversation to extract:

• Decisions made during implementation
• Friction encountered (errors, retries, workarounds)
• Patterns discovered or followed
• Lessons learned

# Analyze specific session
python3 ~/.claude/scripts/analyze-sessions.py --session=$SESSION_ID

# Analyze with extraction limits for large sessions
python3 ~/.claude/scripts/analyze-sessions.py --session=$SESSION_ID --limit=50

Conversation Data → Retro Output Mapping

Conversation Data	Retro Output
DecisionExtraction	.agents/council/ - Decisions section
QualityResult.issues	Friction detection
DocExtraction(type="warning")	.agents/learnings/
DecisionExtraction(type="pattern")	.agents/patterns/
DecisionExtraction(type="lesson")	What Worked / What Didn't

Session ID Sources

1. Environment variable: $CLAUDE_SESSION_ID (set by Claude Code)
2. Recent session detection: Find most recent .jsonl in ~/.claude/projects/
3. Beads comment: Sessions may be recorded in crank state

When No Session Available

Fall back to git analysis and beads comments. Note in retro that conversation analysis was unavailable.

---

Git Commit Analysis

git log --oneline --since="7 days ago" | grep -E "(ai-platform-[a-z0-9]+|$TOPIC)"
git show <commit-hash> --stat

Extract: Files modified, commit messages, lines changed.

---

Beads Comments

bd show <epic-id>
bd show <child-id>

Extract: Decisions, blockers, workarounds, root causes.

---

Blackboard State

ls .agents/blackboard/
cat .agents/blackboard/crank-state.json 2>/dev/null

---

Closure Integrity Quick-Check

When retrospecting an epic, run lightweight closure checks before extracting learnings. Full audit lives in skills/post-mortem/references/closure-integrity-audit.md; retro uses the subset below.

Phantom Bead Detection

EPIC_ID="$ARGUMENTS"
for child in $(bd children "$EPIC_ID" 2>/dev/null | grep -oP '\S+' | head -1); do
  TITLE=$(bd show "$child" 2>/dev/null | head -1 | sed 's/^.*· //' | sed 's/ \[.*$//')
  if echo "$TITLE" | grep -qP '^(task|fix|update|todo|item|work)$'; then
    echo "WARN: $child has generic title '$TITLE' — possible phantom closure"
  fi
done

Multi-Wave Regression Scan

For crank epics, check if later waves reverted earlier waves' work:

# Quick heuristic: count net lines added per scoped file across all wave commits
# If a file has 0 net additions but was touched in multiple waves, flag it
for f in $(git diff --name-only HEAD~5 2>/dev/null | sort -u); do
  ADDS=$(git log --oneline --numstat HEAD~5..HEAD -- "$f" 2>/dev/null | awk '/^[0-9]/{s+=$1}END{print s+0}')
  DELS=$(git log --oneline --numstat HEAD~5..HEAD -- "$f" 2>/dev/null | awk '/^[0-9]/{s+=$2}END{print s+0}')
  TOUCHES=$(git log --oneline HEAD~5..HEAD -- "$f" 2>/dev/null | wc -l | tr -d ' ')
  if [ "$TOUCHES" -gt 1 ] && [ "$ADDS" -le "$DELS" ]; then
    echo "WARN: $f touched $TOUCHES times but net additions <= deletions — possible wave regression"
  fi
done

Why: In na-vs9.4, Wave 2 removed 15 lines that Wave 1 added. Both waves passed tests independently. This check catches the pattern mechanically.

Retro Integration

• Include closure warnings in What Could Be Improved section
• If phantom beads found, add learning: "Require meaningful titles and descriptions for all child beads before closing epic"
• If wave regressions found, add learning: "Add cross-wave diff validation to crank post-wave checks"

---

Friction Detection

Friction Keywords

# Look for friction keywords in comments
grep -i "error\|failed\|retry\|workaround\|fixed by\|root cause" <comments>

# Look for fix commits
git log --oneline | grep -i "fix\|revert\|hotfix\|patch"

Search Prior Solutions

ls .agents/learnings/ | grep -i "$TOPIC"
ls .agents/patterns/ | grep -i "$TOPIC"

If found: Reference in proposal. If not found: Mark as "NEW" for learning extraction.

Friction Categories

Category	Indicators
Retry/Failure	"Error:", "Failed:", test failures
Manual Fix	User corrections after agent action
Blocking	Dependency issues
Pattern Deviation	Didn't follow established pattern
Missing Information	Had to search for docs

Friction → Fix Mapping

Friction	Fix Location
Command unclear	.claude/commands/*.md
Skill trigger missed	.claude/skills/**/*.md
Pattern not followed	.agents/patterns/*.md
Convention violated	CLAUDE.md

---

Supersession Check

Search Existing Artifacts

mcp__smart-connections-work__lookup --query="$TOPIC" --limit=10
grep -rl "$TOPIC" .agents/learnings/ .agents/patterns/ 2>/dev/null

Supersession Criteria

Criterion	Supersede?
Same topic, newer insight	Yes
Same topic, complementary	No (cross-reference)
Obsolete/incorrect info	Yes

Metadata

Old artifact:

superseded_by: .agents/learnings/YYYY-MM-DD-new.md

New artifact:

supersedes: .agents/learnings/YYYY-MM-DD-old.md