/universal-ma-codebook

name: universal-ma-codebook
description: |
  Universal Meta-Analysis Codebook v2.2 - AI-Human collaboration for meta-analysis data extraction.
  4-layer design: Identifiers, Statistics, AI Provenance, Human Verification.
  Integrates with C5/C6/C7 agents and Category I systematic review pipeline.
  Triggers: meta-analysis, codebook, data extraction, Hedges g, effect size
version: "12.0.1"

Universal Meta-Analysis Codebook

**Version**: 2.2 **Status**: Production **Codex Review**: APPROVE WITH MINOR CHANGES (2026-01-26) **Update**: Context-specific extensions (2026-01-26)

Purpose

A **universal, AI-Human collaboration codebook** for meta-analysis that enables: 1. AI extraction from PDFs (RAG/OCR) with confidence tracking 2. Human verification of AI-extracted values 3. 100% human-verified data through structured workflow 4. Integration with Diverga C5/C6/C7 agents and Category I pipeline 5. **Context-specific extensions** for domain-specific moderator variables

Context-Specific Extensions

The Universal Codebook supports **project-specific moderator layers** that extend the base 4-layer structure. Each meta-analysis context may have unique moderator variables.

Extension Architecture

┌─────────────────────────────────────────────────────────────────────┐
│              UNIVERSAL CODEBOOK WITH CONTEXT EXTENSION              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  LAYER 1: IDENTIFIERS + METADATA (10 fields) ← Universal           │
│  LAYER 2: CORE STATISTICAL VALUES (18 fields) ← Universal          │
│  LAYER 3: CONTEXT-SPECIFIC MODERATORS ← Project Extension          │
│  LAYER 4: AI EXTRACTION PROVENANCE ← Universal                     │
│  LAYER 5: HUMAN VERIFICATION (8 fields) ← Universal                │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Available Context Extensions

| Context | Extension File | Moderator Count | |---------|----------------|-----------------| | GenAI-HE | `GENAI_HE_CODEBOOK.md` | 15 moderators | | Clinical Trials | `CLINICAL_CODEBOOK.md` | TBD | | Educational Tech | `EDTECH_CODEBOOK.md` | TBD |

Creating a Context Extension

1. **Define moderator variables** specific to your research domain 2. **Create classification rules** for categorical moderators 3. **Write AI extraction prompts** for each moderator 4. **Configure C6 agent** with the extension schema

# Example: Configure C6 for GenAI-HE context
c6.configure_extension(
    context="genai_he",
    moderators=[
        {"name": "genai_tool", "type": "categorical", "values": ["ChatGPT", "Claude", ...]},
        {"name": "blooms_level", "type": "ordinal", "values": ["remember", "understand", ...]},
        {"name": "study_design", "type": "categorical", "values": ["RCT", "quasi", ...]},
    ],
    extraction_prompts=GENAI_HE_PROMPTS
)

GenAI-HE Extension (Example)

**Layer 3: GenAI-HE Moderator Variables (15 fields)**

| Category | Fields | |----------|--------| | GenAI Tool | genai_tool, genai_tool_version, genai_access_type | | Educational Outcome | blooms_level, outcome_dimension, learning_domain | | Study Design | study_design, intervention_duration, intervention_type, control_condition | | Context | education_level, discipline, country, sample_size_total, publication_type |

See: `GenAI-HE-Review-AIMC/docs/GENAI_HE_CODEBOOK.md` for full specification

Architecture: Four-Layer Design

┌─────────────────────────────────────────────────────────────────────┐
│              UNIVERSAL META-ANALYSIS CODEBOOK v2.1                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  LAYER 1: IDENTIFIERS + METADATA (10 fields)                        │
│  study_id, es_id, citation, doi, year, design_type,                │
│  timepoint, arm_label_treat, arm_label_control, unit_of_analysis   │
│                                                                     │
│  LAYER 2: CORE STATISTICAL VALUES (18 fields)                       │
│  Primary: outcome_name → se_g (12)                                  │
│  Change-score: pre_mean_treat, pre_sd_treat, pre_post_corr (3)     │
│  Cluster: cluster_size, icc, n_clusters (3)                        │
│                                                                     │
│  LAYER 3: AI EXTRACTION PROVENANCE                                  │
│  Per-value: ai_value, source, method, confidence, derived_from     │
│  Stored as: ai_extraction_json                                     │
│                                                                     │
│  LAYER 4: HUMAN VERIFICATION (8 fields)                             │
│  verified_status, verified_by, verified_date, corrections_json,    │
│  disagreement_resolved, final_values_json, verification_notes,     │
│  sign_off                                                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Workflow: AI-Human Collaboration

Phase 1: AI Extraction (Automated)

**Triggered by**: I3 RAG building completion or manual PDF upload

**Agent**: C6-DataIntegrityGuard

# C6 extracts statistical values from PDFs
extraction_result = c6.extract_with_provenance(
    pdf_folder="./pdfs",
    methods=["rag", "ocr"],
    reconciliation="hierarchy",
    log_all_candidates=True
)

**Actions**: 1. I3 builds RAG from PDFs 2. C6 queries for statistical values (M, SD, n) 3. Multiple extraction methods run in parallel 4. Conflict resolution applied (hierarchy + tolerance) 5. Provenance recorded for all extractions 6. Hedges' g calculated where inputs complete

**Output**: All rows → `verified_status = PENDING`

Phase 2: Tr