Collect Results

Purpose

Extract work products from a completed subagent's worktree, including commit history, code changes, token metrics, and status information. Prepares the subagent's work for integration back into the parent task branch.

When to Use

• Subagent has signaled completion
• Subagent has hit context limits and partial results are needed
• Monitoring indicates subagent is stalled or needs intervention
• Before merging subagent branch to task branch

Workflow

1. Verify Subagent Completion

Check that the subagent has finished or is in a state where results can be collected:

WORKTREE=".worktrees/${TASK}-sub-${UUID}"
SESSION_FILE="/home/node/.config/claude/projects/-workspace/${SESSION_ID}.jsonl"

# Check for completion marker in session
jq -s 'last | select(.type == "result" or .content | contains("COMPLETED"))' "${SESSION_FILE}"

2. Extract Commit History

cd "${WORKTREE}"

# Get commits made by subagent (since branch creation)
git log --oneline origin/HEAD..HEAD

# Get detailed commit info
git log --format="%H %s" origin/HEAD..HEAD > /tmp/subagent-commits.txt

3. Parse Token Metrics

# Read session file for metrics
SESSION_FILE="/home/node/.config/claude/projects/-workspace/${SESSION_ID}.jsonl"

# Total tokens used
TOTAL_TOKENS=$(jq -s '[.[] | select(.type == "assistant") | .message.usage |
  (.input_tokens + .output_tokens)] | add' "${SESSION_FILE}")

# Input vs output breakdown
INPUT_TOKENS=$(jq -s '[.[] | select(.type == "assistant") |
  .message.usage.input_tokens] | add' "${SESSION_FILE}")
OUTPUT_TOKENS=$(jq -s '[.[] | select(.type == "assistant") |
  .message.usage.output_tokens] | add' "${SESSION_FILE}")

# Compaction events
COMPACTIONS=$(jq -s '[.[] | select(.type == "summary")] | length' "${SESSION_FILE}")

4. Read Subagent Work Products

cd "${WORKTREE}"

# List modified files
git diff --name-only origin/HEAD..HEAD

# Get full diff for review
git diff origin/HEAD..HEAD > /tmp/subagent-changes.diff

5. Extract Subagent Status

If subagent maintained a STATE.md or status file:

# Read subagent's final state
cat "${WORKTREE}/.claude/dog/tasks/${TASK}/STATE.md"

# Or check for completion report
cat "${WORKTREE}/COMPLETION_REPORT.md" 2>/dev/null

6. Update Parent STATE.md

Record collection results in parent's tracking:

subagents:
  - id: a1b2c3d4
    task: 1.2-implement-parser
    status: collected  # Changed from 'running'
    collected_at: 2026-01-10T15:00:00Z
    results:
      commits: 5
      files_changed: 12
      lines_added: 450
      lines_removed: 120
    metrics:
      total_tokens: 65000
      input_tokens: 45000
      output_tokens: 20000
      compaction_events: 0
    ready_for_merge: true

7. Prepare for Merge

# Ensure subagent branch is up to date
cd "${WORKTREE}"
git status

# Note any uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "WARNING: Uncommitted changes in subagent worktree"
  git status --short
fi

Examples

Successful Collection

collection_report:
  subagent_id: a1b2c3d4
  task: 1.2-implement-parser
  collection_status: success

  commits:
    - hash: abc123
      message: "feature: implement basic parser structure"
    - hash: def456
      message: "feature: add expression parsing"
    - hash: ghi789
      message: "test: add parser unit tests"

  metrics:
    total_tokens: 65000
    efficiency: 0.89  # commits per 10K tokens
    compactions: 0

  files_summary:
    - src/parser/Parser.java (new)
    - src/parser/ExpressionParser.java (new)
    - test/parser/ParserTest.java (new)

  next_action: ready_for_merge

Partial Collection (Context Limit Hit)

collection_report:
  subagent_id: b2c3d4e5
  task: 1.3-implement-formatter
  collection_status: partial

  reason: context_limit_reached
  compaction_events: 2

  commits:
    - hash: jkl012
      message: "feature: implement basic formatter"
    # Only 1 of 3 planned commits completed

  remaining_work:
    - "Implement indent handling"
    - "Add line wrapping"

  metrics:
    total_tokens: 195000
    efficiency: 0.05  # Low due to compaction overhead

  next_action: decompose_remaining
  recommendation: "Spawn new subagent for remaining work"

Anti-Patterns

Do NOT collect from running subagent without cause

# ❌ Interrupting active work
collect-results "${SUBAGENT}"  # Still processing!

# ✅ Wait for completion or explicit intervention reason
if is_complete "${SUBAGENT}" || needs_intervention "${SUBAGENT}"; then
  collect-results "${SUBAGENT}"
fi

Do NOT ignore uncommitted changes

# ❌ Proceeding with dirty worktree
collect-results "${SUBAGENT}"
merge-subagent "${SUBAGENT}"

# ✅ Handle uncommitted work
if has_uncommitted_changes "${SUBAGENT}"; then
  echo "WARNING: Uncommitted changes detected"
  # Either commit them or document as lost
fi

Do NOT skip metrics collection

# ❌ Only grabbing commits
git log --oneline > results.txt
# Done!

# ✅ Full metrics for learning
collect_commits "${SUBAGENT}"
collect_token_metrics "${SUBAGENT}"
collect_compaction_events "${SUBAGENT}"
update_parent_state "${SUBAGENT}"

Do NOT lose partial progress

# ❌ Discarding incomplete work
if [ "${STATUS}" != "complete" ]; then
  echo "Incomplete, discarding"
  cleanup_worktree "${SUBAGENT}"
fi

# ✅ Preserve partial progress
if [ "${STATUS}" != "complete" ]; then
  echo "Collecting partial results"
  document_remaining_work "${SUBAGENT}"
  # Results can still be merged
fi

Related Skills

• dog:monitor-subagents - Check if subagent is ready for collection
• dog:merge-subagent - Merge collected results to task branch
• dog:token-report - Detailed analysis of token usage
• dog:decompose-task - Split remaining work after partial collection