Use this skill when tasked with reviewing a body of existing documents, reports, or references on a topic. The goal is to synthesize what is already known, identify themes and patterns across sources, and surface gaps where information is missing or contradictory.

Common scenarios:

Reviewing all existing documentation before a project kickoff
Synthesizing prior research reports to inform a new initiative
Surveying internal knowledge bases on a topic before making recommendations
Building an annotated bibliography for a decision-making process

This skill is about reading and synthesizing existing materials, not about generating new primary research.

Output Template

# Literature Review: [Topic]

**Date:** YYYY-MM-DD
**Reviewer:** [agent name]
**Scope:** [what was reviewed — directories, document types, date range]
**Documents Reviewed:** N

## Executive Summary
[3-5 sentences: what the body of literature collectively says about the topic, where there is consensus, and where gaps remain]

## Annotated Bibliography

### [Document 1 Title]
- **Path:** [file path]
- **Type:** [report/memo/spec/guide/analysis/reference]
- **Date:** [when written or last modified]
- **Author:** [if identifiable]
- **Summary:** [2-3 sentence summary of what this document contributes]
- **Key Claims:** [bulleted list of the main assertions]
- **Relevance:** [High/Medium/Low] — [why]

### [Document 2 Title]
...

## Theme Matrix

| Theme | Doc 1 | Doc 2 | Doc 3 | Doc 4 | Coverage |
|-------|-------|-------|-------|-------|----------|
| [theme A] | X | X | | X | 3/4 |
| [theme B] | X | | X | | 2/4 |
| [theme C] | | | X | X | 2/4 |

## Synthesis Narrative

### [Theme A]: [Descriptive Title]
[What the documents collectively say about this theme. Cite specific documents. Note where they agree and where they diverge.]

### [Theme B]: [Descriptive Title]
...

## Gap Analysis
| Gap | Description | Impact | Recommendation |
|-----|-------------|--------|----------------|
| [gap 1] | [what is missing] | [why it matters] | [how to fill it] |
| [gap 2] | ... | ... | ... |

## Contradictions
| Topic | Source A Says | Source B Says | Assessment |
|-------|-------------|-------------|------------|
| [topic] | [claim] (Doc N) | [contrary claim] (Doc M) | [which is more credible and why] |

## Sources Reviewed
| # | Document | Path | Type | Date | Relevance |
|---|----------|------|------|------|-----------|
| 1 | [title] | [path] | [type] | [date] | [H/M/L] |

Procedure

1. Define Review Scope

# Read the task for topic and scope
TASK_ID="$1"
bash /home/shared/scripts/task.sh get "$TASK_ID" | jq -r '.description'

Before reading any documents, write down:

Topic: The subject of the review
Scope boundaries: What types of documents to include/exclude
Questions to answer: What should this review tell us when complete?

2. Collect All Candidate Documents

TOPIC="$2"  # e.g., "authentication" or "migration-plan"

# Find all documents that mention the topic
echo "=== Documents mentioning '$TOPIC' ==="
rg -l -i "$TOPIC" /home/shared/ ~/workspace/ 2>/dev/null \
  | grep -E '\.(md|txt|csv|json|yaml|yml|pdf|html|rst|adoc)$' \
  | sort

# Find documents by filename
echo ""
echo "=== Documents with '$TOPIC' in filename ==="
find /home/shared/ ~/workspace/ -type f \
  -iname "*${TOPIC}*" 2>/dev/null | sort

# Find all reports and research documents
echo ""
echo "=== All reports in shared workspace ==="
find /home/shared/ -name '*.md' -type f 2>/dev/null | sort

# Check artifact registry for relevant prior work
echo ""
echo "=== Registered artifacts ==="
bash /home/shared/scripts/artifact.sh list 2>/dev/null \
  | jq -r '.[] | "\(.name) — \(.type) — \(.path)"' 2>/dev/null

Build a candidate list:

# Create a manifest of documents to review
REVIEW_DIR="/tmp/literature-review"
mkdir -p "$REVIEW_DIR"

# Collect all candidate file paths
rg -l -i "$TOPIC" /home/shared/ ~/workspace/ 2>/dev/null \
  | grep -E '\.(md|txt|csv|json|yaml)$' \
  > "$REVIEW_DIR/candidates.txt"

echo "Candidate documents: $(wc -l < "$REVIEW_DIR/candidates.txt")"
cat "$REVIEW_DIR/candidates.txt"

3. Triage and Prioritize

Not all documents deserve equal attention. Triage first:

# For each candidate, get size and a preview to assess relevance
while IFS= read -r filepath; do
  echo "=== $(basename "$filepath") ==="
  echo "Path: $filepath"
  echo "Size: $(wc -c < "$filepath") bytes, $(wc -l < "$filepath") lines"
  echo "Modified: $(stat -c '%y' "$filepath" 2>/dev/null || stat -f '%Sm' "$filepath" 2>/dev/null)"
  echo "Preview:"
  head -15 "$filepath"
  echo ""
  echo "---"
done < "$REVIEW_DIR/candidates.txt"

Assign each document a relevance tier:

Tier 1 (must read): Directly addresses the topic, from authoritative source
Tier 2 (should read): Partially relevant or provides useful context
Tier 3 (skim only): Tangentially related, read only if time permits

4. Read and Annotate Each Document

For each Tier 1 and Tier 2 document:

DOC_PATH="/home/shared/some-document.md"
DOC_NAME="$(basename "$DOC_PATH")"

# Read the full document
cat "$DOC_PATH"

# Extract headings to understand structure
grep -E '^#{1,3} ' "$DOC_PATH"

# Find key claims — sentences with strong assertion language
rg -n 'must|should|recommend|require|critical|essential|conclude|found that' \
  "$DOC_PATH" -i | head -20

Create an annotation entry:

cat >> "$REVIEW_DIR/annotations.md" <<EOF

### $(basename "$DOC_PATH")
- **Path:** $DOC_PATH
- **Type:** [report/memo/spec/guide/analysis]
- **Date:** $(stat -c '%y' "$DOC_PATH" 2>/dev/null | cut -d' ' -f1 || stat -f '%Sm' -t '%Y-%m-%d' "$DOC_PATH" 2>/dev/null)
- **Summary:** [2-3 sentences]
- **Key Claims:**
  - [claim 1]
  - [claim 2]
- **Relevance:** [High/Medium/Low]
EOF

5. Extract Themes Across Documents

# Identify recurring terms and concepts across all documents
echo "=== Recurring Terms ==="
cat "$REVIEW_DIR/candidates.txt" | xargs cat 2>/dev/null \
  | tr '[:upper:]' '[:lower:]' \
  | tr -cs '[:alpha:]' '\n' \
  | sort | uniq -c | sort -rn \
  | grep -v -E '^[[:space:]]+(the|and|is|of|to|in|a|for|that|with|this|it|on|are|be|as|was|from|or|an|by|at|not|but|has|have|had|which|will|can|been|would|their|they|all|its|may|more|also|into|than|any|each|only|these|our|such|other|some|new|when|about|could|no|should)$' \
  | head -30

# Find terms that appear in multiple documents
echo ""
echo "=== Cross-Document Terms ==="
while IFS= read -r filepath; do
  basename "$filepath"
  rg -oN '\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b' "$filepath" 2>/dev/null | sort -u | head -10
  echo "---"
done < "$REVIEW_DIR/candidates.txt"

Build the theme matrix:

# Create theme matrix as CSV
THEMES_FILE="$REVIEW_DIR/theme-matrix.csv"
echo "theme,$(cat "$REVIEW_DIR/candidates.txt" | xargs -I{} basename {} | tr '\n' ',' | sed 's/,$//')" > "$THEMES_FILE"

# For each theme, check which documents mention it
THEMES=("theme_a" "theme_b" "theme_c")
for theme in "${THEMES[@]}"; do
  ROW="$theme"
  while IFS= read -r filepath; do
    if rg -qi "$theme" "$filepath" 2>/dev/null; then
      ROW="${ROW},X"
    else
      ROW="${ROW},"
    fi
  done < "$REVIEW_DIR/candidates.txt"
  echo "$ROW" >> "$THEMES_FILE"
done

column -t -s',' "$THEMES_FILE"

6. Identify Gaps and Contradictions

# Check for contradictions — same topic, different claims
echo "=== Potential Contradictions ==="

# Find documents that discuss the same subtopic differently
SUBTOPICS=("performance" "security" "scalability" "cost")
for subtopic in "${SUBTOPICS[@]}"; do
  FILES=$(rg -l -i "$subtopic" "$REVIEW_DIR/candidates.txt" 2>/dev/null | head -5)
  if [ $(echo "$FILES" | wc -l) -gt 1 ]; then
    echo "--- $subtopic mentioned in multiple docs ---"
    for f in $FILES; do
      echo "  $f:"
      rg -i "$subtopic" "$f" | head -3
    done
  fi
done

Gaps are topics you expected to find but did not:

# Check for expected topics that are NOT covered
EXPECTED_TOPICS=("implementation" "timeline" "budget" "risks" "alternatives")
echo "=== Gap Check ==="
for topic in "${EXPECTED_TOPICS[@]}"; do
  COUNT=$(cat "$REVIEW_DIR/candidates.txt" | xargs rg -li "$topic" 2>/dev/null | wc -l)
  if [ "$COUNT" -eq 0 ]; then
    echo "GAP: '$topic' — not found in any reviewed document"
  else
    echo "OK:  '$topic' — found in $COUNT document(s)"
  fi
done

7. Write the Review

REPORT_FILE="/home/shared/literature-review-$(date +%Y%m%d)-${TOPIC}.md"

cat > "$REPORT_FILE" <<'REPORT'
# Literature Review: [Topic]

**Date:** YYYY-MM-DD
**Reviewer:** [agent name]
**Scope:** [directories and document types reviewed]
**Documents Reviewed:** N

## Executive Summary

[What the body of literature collectively says. Where there is consensus. Where there are gaps.]

## Annotated Bibliography

### [Document 1]
- **Path:** [path]
- **Type:** [type]
- **Date:** [date]
- **Summary:** [what this document contributes]
- **Key Claims:** [main assertions]
- **Relevance:** [H/M/L]

### [Document 2]
...

## Theme Matrix

| Theme | Doc 1 | Doc 2 | Doc 3 | Coverage |
|-------|-------|-------|-------|----------|
| [theme] | X | X | | 2/3 |

## Synthesis Narrative

### [Theme A]
[What documents collectively say about this theme, citing specific sources]

### [Theme B]
...

## Gap Analysis

| Gap | Description | Impact | Recommendation |
|-----|-------------|--------|----------------|
| [gap] | [what is missing] | [why it matters] | [how to fill it] |

## Contradictions

| Topic | Source A Says | Source B Says | Assessment |
|-------|-------------|-------------|------------|
| [topic] | [claim] | [contrary claim] | [resolution] |

## Sources Reviewed

| # | Document | Path | Type | Date | Relevance |
|---|----------|------|------|------|-----------|
| 1 | [title] | [path] | [type] | [date] | [H/M/L] |
REPORT

echo "Review written to: $REPORT_FILE"

8. Register and Notify

bash /home/shared/scripts/artifact.sh register \
  --name "literature-review-${TOPIC}" \
  --type "research" \
  --path "$REPORT_FILE" \
  --description "Literature review on ${TOPIC} covering N documents"

# Notify the requesting agent
bash /home/shared/scripts/send-mail.sh \
  --to "$REQUESTING_AGENT" \
  --subject "Literature review complete: ${TOPIC}" \
  --body "Review of N documents available at: $REPORT_FILE"

Quality Checklist

All relevant documents in the workspace were found and considered
Each document has an annotation entry (summary, key claims, relevance)
Theme matrix shows which themes appear in which documents
Synthesis narrative cites specific documents, not vague references
Gaps are identified with concrete impact and recommendations to fill them
Contradictions between sources are documented with an assessment of which is more credible
Executive summary accurately reflects the collective findings
Review scope and boundaries are clearly stated (what was and was not included)
Report is registered as an artifact in the shared workspace