Gpd Literature Review

A physics literature review is not a bibliography. It is a map of the intellectual landscape: who computed what, using which methods, with what assumptions, getting what results, and where do they agree or disagree. The reviewer must think like a physicist surveying a field, not a librarian cataloging references. </objective>

<execution_context>

Called from $gpd-literature-review command. </purpose>

<core_principle> A physics literature review is not a bibliography. It is a structured map of who computed what, using which methods, with what assumptions, getting what results, and where they agree or disagree. The goal is to understand the state of a field well enough to identify what is known, what is open, and where new work can contribute. </core_principle>

<source_hierarchy> MANDATORY: Authoritative sources BEFORE general search

1. Textbooks and monographs -- For established results, standard methods, and field context

   • Use specific textbooks by subfield (Peskin & Schroeder for QFT, Sakurai for QM, Jackson for E&M, Landau & Lifshitz series, etc.)
   • These define conventions and standard results

2. Review articles -- For field overviews and method surveys

   • Rev. Mod. Phys., Physics Reports, Annual Reviews of Physics
   • Recent reviews (last 5 years) for current state-of-the-art

3. Seminal papers -- Original derivations of key results

   • Identify the papers everyone in the field cites
   • Read the actual papers, not just the citations

4. Recent arXiv preprints -- For cutting-edge developments

   • arXiv categories: hep-th, hep-ph, hep-lat, cond-mat., quant-ph, gr-qc, astro-ph., nucl-th, etc.
   • Sort by relevance and citation count

5. Conference proceedings -- For very recent results and community direction

   • Lattice, ICHEP, APS meetings, etc.

6. web_search -- Last resort for community discussions, code repos, numerical benchmarks

</source_hierarchy>

INIT=$(/home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local init progress --include state,config)
if [ $? -ne 0 ]; then
  echo "ERROR: gpd initialization failed: $INIT"
  # STOP — display the error to the user and do not proceed.
fi

Parse JSON for: commit_docs, state_exists, project_exists, project_contract, contract_intake, effective_reference_intake, active_reference_context, reference_artifact_files, reference_artifacts_content.

Read mode settings:

AUTONOMY=$(/home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw config get autonomy 2>/dev/null | /home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .value --default balanced 2>/dev/null || echo "balanced")
RESEARCH_MODE=$(/home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local --raw config get research_mode 2>/dev/null | /home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local json get .value --default balanced 2>/dev/null || echo "balanced")

Mode-aware behavior:

• research_mode=explore: Comprehensive review (30+ papers), include tangential fields, map full citation network, identify open questions.

• research_mode=exploit: Focused review (8-12 papers), direct relevance only, extract key results and methods.

• research_mode=adaptive: Start with 15 papers, expand if citation network reveals critical gaps.

• autonomy=supervised: Pause after each review round for user feedback on scope and direction.

• autonomy=balanced (default): Complete the full review pipeline automatically. Pause only if the literature reveals scope ambiguity, contradictory evidence, or a change in recommendation.

• autonomy=yolo: Complete the review pipeline without pausing, but do NOT drop contract-critical anchors or user-mandated references.

• If state_exists is true: Extract convention_lock for notation context (helps identify which conventions are used in papers being reviewed). Extract active research topic, phase context, and any contract-critical references from active_reference_context.

• If state_exists is false (standalone usage): Proceed — the user will specify the topic directly.

• Treat effective_reference_intake as the machine-readable carry-forward ledger for anchors, prior outputs, baselines, user-mandated context, and unresolved gaps. Re-surface those items in the review even if the broader search expands beyond them.

• Use reference_artifacts_content as supporting evidence when existing literature/research-map artifacts already pin down benchmark values, prior outputs, or anchor wording that should remain stable.

Project context helps focus the review on conventions and methods relevant to the current research. </step>

• Topic and focus: Specific physics question or subfield
• Depth: Quick (~10 refs) | Standard (~30 refs) | Comprehensive (~50+ refs)
• Time range: All time | Last N years | Since specific result
• Purpose: Background | Method selection | Gap identification | Manuscript prep
• List the seed anchors already present in project_contract, contract_intake, effective_reference_intake, and active_reference_context before broadening the search

Define explicit include/exclude boundaries:

• Include: specific phenomena, methods, energy ranges, dimensions
• Exclude: tangential fields, historical reviews (unless depth=comprehensive)
• Record any contract-critical anchor that must be surfaced even if it falls outside the default search breadth </step>

Every subfield has seminal papers that defined the field. Identify them:

1. Search for review articles first (they cite the seminal works):

   web_search: "[topic] review" site:arxiv.org
   web_search: "[topic]" site:journals.aps.org/rmp
   

2. From review articles, extract:

   • The 5-10 most-cited papers
   • The textbook treatments
   • The original derivation of key results

3. For each foundational work, record:

   • Full citation (authors, title, journal, year)
   • Stable anchor_id and concrete locator if the work is contract-critical or likely to be reused downstream
   • Key contribution (what they showed/computed/proved)
   • Method used
   • Conventions (units, metric signature, normalization)
   • Where the result is used downstream
   • Whether it should be treated as a contract-critical anchor for later planning or verification

4. Build a citation timeline showing how the field developed. </step>

Catalog all methods that have been applied to this problem:

For each method:

Organize methods by approach type:

• Exact methods: Bethe ansatz, integrability, conformal bootstrap, etc.
• Perturbative: Weak coupling, 1/N, epsilon expansion, etc.
• Variational: Trial wavefunctions, DMRG, tensor networks, etc.
• Monte Carlo: DQMC, PIMC, VMC, AFQMC, etc.
• Mean-field and beyond: Hartree-Fock, RPA, GW, DMFT, etc.
• Effective theories: EFT, renormalization group, etc.

Note which methods agree and where they disagree -- this reveals the interesting physics. </step>

For each significant result in the literature:

Tabulate results for the SAME quantity across different papers/methods to expose:

• Agreement (convergence of independent methods)
• Disagreement (controversial values)
• Trends (how results evolved as methods improved)
• Which values are decisive benchmarks versus optional background comparisons </step>

Map intellectual lineages:

1. Method lineages: paper_A -> paper_B -> paper_C (each improving on the previous)
2. Competing approaches: lineage_X vs lineage_Y (different methods for same problem)
3. Reconciliation: papers that compared or unified different approaches
4. Branching points: where the field split into sub-problems

This reveals:

• Which methods are still actively developed (recent citations)
• Which are considered superseded (cited only for historical context)
• Which groups are leading each approach
• Where cross-pollination between approaches has been fruitful </step>

Actively search for disagreements in the literature:

1. Numerical discrepancies: Different groups get different values for the same quantity

   • How significant is the disagreement? (In sigma)
   • Is the discrepancy resolution-dependent? (Finite-size, continuum limit)
   • Has anyone explained the discrepancy?

2. Methodological disagreements: Different methods give inconsistent results

   • Which method is more reliable in this regime?
   • Are the approximations comparable?
   • Could both be right in different limits?

3. Conceptual disagreements: Different physical interpretations of the same result

   • Is this a genuine physics disagreement or a convention difference?
   • What experiment or calculation could distinguish between interpretations?

4. Convention conflicts: Different papers use different conventions

   • Catalog convention choices across the major references
   • Note where convention mismatches could cause apparent disagreements </step>

Systematically identify what has NOT been done:

1. Uncomputed quantities: Observables mentioned in the literature but never calculated
2. Unexplored regimes: Parameter ranges where no reliable method works
3. Unresolved puzzles: Anomalous results with no accepted explanation
4. Missing connections: Two related results that nobody has connected
5. Unverified predictions: Theoretical predictions awaiting experimental confirmation
6. Long-standing conjectures: Claims without proof, supported only by numerical evidence

For each gap:

• Why hasn't it been addressed? (Too hard? Not important enough? Technical obstacle?)
• What would it take to address it? (Better methods? More computing power? New data?)
• What would we learn? (Is it worth the effort?)
• Whether a missing anchor or missing benchmark is currently blocking downstream planning </step>

Map the state-of-the-art:

1. Most recent results (last 1-2 years)

   • What has been computed or measured recently?
   • How does it change the picture from the review articles?

2. Active groups

   • Which groups are producing results in this area?
   • What methods are they using?
   • What are their current projects? (Check recent arXiv submissions)

3. Emerging methods

   • New theoretical or computational approaches being applied
   • Machine learning / AI applications to this problem
   • New experimental techniques

4. Community direction

   • What was discussed at recent conferences?
   • Where is the field heading? </step>

mkdir -p .gpd/literature

Write .gpd/literature/{slug}-REVIEW.md:

---