Ar Evidence

Step 1: Load All Reading Notes

Read every reading note file from analysis/evidence/reading_notes/.

Step 2: Extract Evidence Units

For each notable finding, quote, data point, or argument across all reading notes, create an EvidenceUnit:

1. Generate an evidence ID: .venv/bin/python3 utils/schemas.py id ev

2. Populate the EvidenceUnit fields:

   • evidence_id: the generated ID
   • source_id: which source this came from
   • evidence_type: classify as quote / fact / statistic / event / interpretation
   • quote_text: the exact text (for quotes) or a precise description (for facts/events)
   • span_start / span_end: character offsets if available (0 if not)
   • page_or_section: where in the source this evidence appears
   • interpretation_note: what this evidence means for the research question
   • confidence: 0.0-1.0 based on source reliability and directness of evidence
   • tags: thematic tags linking to literature map clusters and sub-questions

3. Write each evidence unit to {workspace}/analysis/evidence/ev-{id}.json

Step 3: Group by Theme and Sub-Question

Organise evidence units into groups:

• By sub-question: which sub-question from the scoping report does this evidence address?
• By theme: which literature map cluster does this evidence relate to?
• By evidence type: quotes vs. facts vs. statistics vs. interpretations

Step 4: Identify Contradictions

Find pairs of evidence units that support opposing conclusions:

• Two sources that make conflicting claims about the same topic
• Evidence that supports a claim alongside evidence that undermines it
• Disagreements between empirical findings

For each contradiction pair, record:

• The two evidence IDs
• What they disagree about
• Which source is more reliable (based on reliability scores)

Step 5: Write Evidence Index

Write {workspace}/analysis/evidence/evidence_index.json:

{
  "total_evidence_units": 0,
  "by_sub_question": {
    "sub_q_1": ["ev-xxx", "ev-yyy"],
    "sub_q_2": ["ev-zzz"]
  },
  "by_theme": {
    "cluster_name": ["ev-xxx", "ev-yyy"]
  },
  "by_type": {
    "quote": ["ev-xxx"],
    "fact": ["ev-yyy"],
    "statistic": [],
    "event": [],
    "interpretation": ["ev-zzz"]
  },
  "contradictions": [
    {
      "evidence_a": "ev-xxx",
      "evidence_b": "ev-yyy",
      "topic": "what they disagree about",
      "stronger_source": "ev-xxx"
    }
  ]
}

Step 6: Update Status

Update {workspace}/status.json:

• Set state to EVIDENCE_BUILDING if not already
• Add "evidence" to stages_completed

Quality Rules

• Every evidence unit must trace back to a specific source — no orphaned evidence
• Quotes must be preserved exactly as found in the reading notes — do not paraphrase quotes
• Confidence scores must reflect source reliability (from audit) and directness of evidence
• Contradictions must be genuine disagreements, not differences in scope or framing
• Tags must use the actual cluster names from the literature map
• Aim for at least 20 evidence units across all sources for adequate coverage
• Use British English in all output text (but preserve original spelling in quotes)