ara-compiler

Adapt to whatever you receive:

1. Identify what you have. Glob, read, and explore the provided paths. Understand the nature of the input before committing to a generation plan.
2. Maximize coverage. Cross-reference all available sources. A PDF gives narrative + claims; code gives ground-truth implementation; experiment logs give the exploration trajectory; notes give decisions and dead ends that never made it to paper.
3. Ask when stuck. If the input is ambiguous or incomplete, ask the user to fill gaps rather than hallucinating. The user is a collaborator, not a passive consumer.
4. Handle partial inputs gracefully. Not every ARA field will be fillable from every input. Populate what you can with high confidence, mark gaps explicitly with "Not available from provided input", and tell the user what's missing so they can supplement later.

Read ALL provided inputs thoroughly before generating anything. For PDFs, read every page, including appendices — appendices often carry reproduction-critical content and should be treated with the same priority as main-text pages.

For repos, prioritize: README → core algorithm files → configs → environment files.

Before writing any files, reason through these 4 stages. Think carefully about each stage.

Stage 1 — Semantic Deconstruction Strip narrative framing. Extract the raw knowledge atoms:

• Mathematical formulations and equations
• Architectural specifications and component descriptions
• Experimental configurations (hyperparameters, hardware, datasets, seeds)
• ALL numerical results and benchmarks (exact values, never rounded)
• Citation dependencies and their roles (imports, extends, bounds, refutes)
• Negative results, ablation findings, rejected alternatives
• Implementation tricks, convergence hacks, sensitivity observations

Before moving on, perform an evidence capture pass:

• For every source table or figure you plan to cite, first capture the original source identifier and caption exactly (Table 2, Figure 4, etc.)
• Transcribe the raw table/figure content before making any claim-specific summary
• If you create a filtered view for one claim, store it as a derived subset, not as the original table itself
• Never label a subset or merged summary as Table N unless it reproduces the original source table faithfully
• If PDF extraction is ambiguous, re-read the page with layout preserved or inspect the page manually before writing evidence files

Stage 2 — Cognitive Mapping Map extracted atoms to /logic/:

• problem.md: observations (with numbers) → gaps → key insight → assumptions
• claims.md: falsifiable claims with proof pointers to experiment IDs (E01, E02...), plus a separation between direct evidence basis and higher-level interpretation
• concepts.md: ≥5 formal definitions with notation and boundary conditions
• experiments.md: ≥3 declarative verification plans (NO exact numbers — directional only)
• solution/: architecture (component graph), algorithm (math + pseudocode), constraints, heuristics
• related_work.md: typed dependency graph (imports/extends/bounds/baseline/refutes)

Appendix content (worked examples, prompt templates, enumerated taxonomies, annotation schemas, extended analyses, prescriptive content) should be routed into the ARA layers where it fits best, preserving the granularity the source uses. Never silently drop an appendix section.

When writing claims:

• Phrase the main Statement at the strongest level directly supported by the cited evidence
• Put raw support in Evidence basis
• Put any broader synthesis in Interpretation
• If the evidence only shows validation metrics, do not upgrade the claim to training dynamics or optimization quality unless training-side evidence is also captured

related_work.md should reflect the paper's full citation footprint, not only the closest predecessors. Works with a specific technical delta get full RW blocks; remaining citations from the paper's References list should still be captured (more briefly) so the intellectual neighborhood is preserved.

Stage 3 — Physical Stubbing Generate /src/:

• configs/: exact hyperparameter values with rationale and sensitivity
• execution/: ≥1 Python code stub implementing the NOVEL contribution (typed signatures, no boilerplate)
• environment.md: Python version, framework, hardware, dependencies, seeds
• If repo available: use actual code to improve stub precision
• If rubric provided: produce rubric/requirements.md mapping every leaf node

Stage 4 — Exploration Graph Extraction Reconstruct the research DAG for /trace/exploration_tree.yaml:

• Root nodes = central research questions
• Experiments and decisions nest as children
• Dead ends from ablations/rejected alternatives = typed leaf nodes
• ≥8 nodes, must include dead_end and decision types
• Use also_depends_on for DAG convergence points
• Every node must declare whether it is explicit from source material or inferred from reconstruction
• Explicit nodes should carry source references (table/figure/section labels)
• Inferred nodes are allowed only when they help reconstruct the paper's logic without pretending to be literal session logs

Write ALL mandatory files. See references/ara-schema.md for the complete directory structure and field-level requirements for every file.

Mandatory files (all must exist and be non-trivial):

• PAPER.md — YAML frontmatter (title, authors, year, venue, doi, ara_version, domain, keywords, claims_summary, abstract) + Layer Index
• logic/problem.md — Observations (O1, O2...), Gaps (G1, G2...), Key Insight, Assumptions
• logic/claims.md — Claims (C01, C02...) each with Statement, Status, Falsification criteria, Proof, Evidence basis, Interpretation, Dependencies, Tags
• logic/concepts.md — ≥5 concepts each with Notation, Definition, Boundary conditions, Related concepts
• logic/experiments.md — ≥3 experiments (E01, E02...) each with Verifies, Setup, Procedure, Metrics, Expected outcome (directional only!), Baselines, Dependencies
• logic/solution/architecture.md — Component graph with inputs/outputs
• logic/solution/algorithm.md — Math formulation + pseudocode + complexity
• logic/solution/constraints.md — Boundary conditions and limitations
• logic/solution/heuristics.md — Heuristics (H01, H02...) each with Rationale, Sensitivity, Bounds, Code ref, Source
• logic/related_work.md — Related work (RW01, RW02...) each with DOI, Type, Delta, Claims affected
• src/configs/training.md — Hyperparameters with Value, Rationale, Search range, Sensitivity, Source
• src/configs/model.md — Model/architecture configs
• src/execution/{module}.py — ≥1 code stub with typed signatures
• src/environment.md — Python version, framework, hardware, dependencies, seeds
• trace/exploration_tree.yaml — Research DAG (≥8 nodes, nested YAML)
• evidence/README.md — Index table mapping every evidence file to claims
• evidence/tables/*.md — ALL result tables (exact cell values, never rounded)
• evidence/figures/*.md — ALL quantitative figures (extracted data points)

Evidence-generation rules:

• Preserve raw source tables separately from any derived subset views
• A file named after a source object (for example table3_...) must match that source object's caption and contents
• If only a subset is included, the filename must say derived_, subset_, or equivalent, and the file must state what it was derived from
• Do not merge rows from different source tables into one evidence file unless the file is explicitly labeled as a derived comparison

Before running Seal validation, verify that the ARA faithfully covers the source material. Repeat up to 3 rounds; stop early if a round produces no patches.

Each round: re-read the source, identify anything not yet captured or only shallowly captured in the ARA, patch those gaps, then note how many fixes were made. If zero, exit early. Pay particular attention to appendix content and to citations from the paper's References list, which are easy to miss on the first pass.

The coverage loop does not replace validation — it ensures the ARA is semantically complete before structural checks run.

Run ARA Seal Level 1 validation. Perform these checks:

• All mandatory dirs exist: logic/, logic/solution/, src/, src/configs/, trace/, evidence/
• All mandatory files exist and are non-empty
• PAPER.md has YAML frontmatter with title, authors, year
• PAPER.md has Layer Index section
• claims.md has C01+ blocks with Statement, Status, Falsification criteria, Proof fields
• experiments.md has E01+ blocks with Verifies, Setup, Procedure, Expected outcome fields
• heuristics.md has H01+ blocks with Rationale, Sensitivity, Bounds fields
• concepts.md has ≥5 concept sections
• experiments.md has ≥3 experiment plans
• exploration_tree.yaml parses as valid YAML with ≥8 nodes, has dead_end and decision types
• Claim Proof references (E01, E02...) resolve to experiments.md
• Experiment Verifies references (C01, C02...) resolve to claims.md
• Heuristic Code ref paths resolve to actual files in src/execution/
• Evidence files contain Markdown tables with Source fields
• Evidence file names, source labels, and captions agree on the original table/figure identifier
• Any file named like a raw source table is a faithful transcription rather than a filtered subset
• Claims only cite experiments whose evidence actually contains the compared rows or measurements
• Claim wording does not outrun the evidence type (for example, validation tables alone should not be used to claim training-dynamics improvements)
• Trace nodes declare support_level: explicit|inferred
• Trace nodes with support_level: explicit include source references

For each validation failure:

1. Read the failing file
2. Apply targeted edits (prefer Edit over full rewrite to preserve correct content)
3. Re-validate after all fixes

Typically converges in 2-3 rounds.

Print a summary:

• Artifact location
• File count and total size
• Validation result (pass/fail with details)
• Key statistics: number of claims, experiments, heuristics, concepts, tree nodes, evidence files