csml-rpi/ai-cfd-scientist/cfd-paper

cfd-paper

⚠ HARD STOP — read this before any other step

For routes 1, 2, 6: if <out-dir>/checkpoints/analysis_done.json does not exist, STOP. Return to Skill cfd-orchestrator. For route 5 (paper-only): <out-dir>/analysis.json must exist before entry.

How this skill works

This skill is a strict numbered protocol. You walk it step by step. Each step is ONE concrete agent action — either an LLM call (where your next response IS the prompted output), a bash invocation, or a validation gate. Each step ends with a literal GOTO Step N instruction. The cycle loops by GOTO-ing back to an earlier step.

You ARE every LLM in this pipeline. When a step says "your next response must be the planner JSON", that means: read the embedded system prompt, treat it as your operating instructions for that single response, fill in the user-message placeholders from disk, then your literal next message is the planner's JSON output. No meta-commentary. No "I will now run the planner." Just the output.

Forbidden behaviors that triggered past failures (do not repeat any of these):

• Do not write `paper/main.tex` by hand without going through Step 5 (the writer prompt). A hand-written .tex with sections "Objective", "Audit Trail", "Implementation Location" instead of "Introduction / Related Work / Methods / Results / Discussion / Conclusion" is the failure mode this skill exists to prevent.
• Do not write `review.json` with your own schema (e.g. {pages, min_pages, findings}). The reviewer LLM (which is you, in role) returns a specific schema with recommendations[], formatting_ok, figures_ok, etc. Without those keys, downstream gates reject it as fabricated.
• Do not write `paper_unified_plan.json` with your own schema (e.g. {title, sections, figures}). The planner (which is you, in role) returns {figure_jobs[], unified_viz_brief, case_order_for_paper, case_display_labels, omit_case_ids, analysis_narrative_hints, topic_paragraph_for_intro}.
• Do not write `audit_passed.json` yourself. Only scripts/stage_gate_audit.py writes that file. The orchestrator runs the audit at Step 5 of its own protocol.
• Do not skip the per-image vision QA in Step 3. You ARE the vision LLM. Open each PNG and judge it.
• Do not skip pdflatex (Step 6). PDF generation is real; the agent doesn't get to declare "compiled".

Library availability

You can import pyvista, matplotlib, numpy, pandas, anything in the conda env. PyVista renders contour fields, slices, streamlines, profiles directly from OpenFOAM case directories — that's what Steps 2 and 3 do. You can write and run Python scripts via Bash; you can read PNGs as images with your native multimodal capability for Step 3's vision QA.

Stage 0 — Paper experiment planner

ONE LLM call. Decides whether the paper needs additional experiments before figure work begins. Run this once, immediately on skill entry.

Step 0.0 — Literature precheck (HARD; H18 enforcement)

The OED + BFS smoke runs both produced unciteable papers because literature retrieval was silently skipped at some point in the chain and the paper stage didn't notice. This step is the gate. Do not proceed past it.

OUT=<out-dir>
MODE=$(jq -r '.mode // empty' "$OUT/state.json")
LIT="$OUT/lit.json"
[ -f "$OUT/lit_enriched.json" ] && LIT="$OUT/lit_enriched.json"
NEEDS_LIT=0
case "$MODE" in
  research|code_mod|paper_only|open_discovery) NEEDS_LIT=1 ;;
esac
if [ "$NEEDS_LIT" = "1" ]; then
  if [ ! -f "$LIT" ]; then
    echo "H18 precheck FAIL — $LIT missing for mode=$MODE."
    echo "Invoke Skill cfd-skills/cfd-literature before continuing. Do NOT author the paper without literature."
    exit 1
  fi
  N=$(jq 'if type=="array" then length elif .records then (.records|length) elif .papers then (.papers|length) elif .results then (.results|length) else 0 end' "$LIT")
  if [ "$N" -lt 5 ]; then
    echo "H18 precheck FAIL — $LIT has only $N record(s) for mode=$MODE (need ≥ 5)."
    echo "Re-invoke Skill cfd-skills/cfd-literature with broader queries (S2_API_KEY must be set)."
    exit 1
  fi
fi

If this check fails, stop the paper stage and re-invoke Skill cfd-skills/cfd-literature first. The audit's H18 / H19 / H10 gates will reject any paper authored on an empty lit.json — there is no value in proceeding.

Step 0.1 — Build the Stage-0 input

Concatenate into one string (≤ 60,000 chars):

TOPIC: <state.json#topic>
MODE: <state.json#mode>
 
CURRENT SUCCESSFUL CASES (from manifest.json or built from cases/):
<list of case_ids that have run_result.status=success AND decision.status=PROCEED>
 
ANALYSIS:
<analysis.json verbatim, truncated to 30000 chars>
 
REQUIREMENTS:
<requirements.json verbatim, truncated to 15000 chars>

If <out-dir>/manifest.json doesn't exist, build it now from cases/case_*/run_result.json + decision.json:

OUT=<out-dir>
python3 - <<'PY'
import json, glob, os
from pathlib import Path
out = Path(os.environ.get("OUT", "."))
cases = []
for cd in sorted(glob.glob(str(out / "cases" / "case_*"))):
    cd_p = Path(cd)
    rr = cd_p / "run_result.json"
    dj = cd_p / "decision.json"
    status, decision = "unknown", ""
    if rr.is_file():
        try: status = json.loads(rr.read_text()).get("status", "unknown")
        except: pass
    if dj.is_file():
        try: decision = json.loads(dj.read_text()).get("status", "")
        except: pass
    paper_status = "success" if (status == "success" and decision == "PROCEED") else status
    cases.append({"case_id": cd_p.name, "case_dir": str(cd_p.resolve()),
                  "status": paper_status, "run_status": status, "decision": decision})
(out / "manifest.json").write_text(json.dumps({"cases": cases}, indent=2))
PY

Step 0.2 — Run the Stage-0 LLM call

Your next response after reading this step MUST be the planner JSON output. Use this system prompt as your operating instructions for that single response, fill the user-message placeholders from Step 0.1's input, then emit the JSON.

System prompt (you are the Stage-0 planner)

You are the paper experiment planner. Given the current run's analysis and manifest, decide whether the manuscript would benefit from additional experiments before figure work begins. Acceptable extensions: (a) parametric sweeps completing a partially-explored sensitivity story; (b) held-out reference cases for DNS/experiment validation; (c) secondary flow configurations testing model-change generalization. Reject: re-runs of failed cases (those belong in the rerun loop), upstream methodology changes (belong in cfd-requirements), speculative extensions unrelated to the topic.
 
Return ONE JSON object:
{
  "needs_additional_experiments": bool,
  "rationale": "1-2 sentences",
  "additional_cases": [
    {"case_id": "case_NNN", "user_requirement_text": "<paragraph for FoamAgent>", "purpose": "what this adds"}
  ]
}
 
Constraints: empty additional_cases if needs_additional_experiments=false; unique case_ids not colliding with existing manifest; ≤ 3 cases; prefer false if unsure. Return ONLY valid JSON.

User message

The string built in Step 0.1.

Step 0.3 — Validate and persist

Write the JSON response to <out-dir>/paper_experiment_plan.json. Then:

PLAN=<out-dir>/paper_experiment_plan.json
jq -e '.needs_additional_experiments != null and (.additional_cases | type == "array")' "$PLAN" \
  || { echo "Stage 0 JSON invalid; redo Step 0.2"; exit 1; }

If validation fails: redo Step 0.2 (re-emit the JSON with the correct schema). If it passes, write <out-dir>/checkpoints/paper_experiment_plan_done.json with {"stage": "paper_experiment_plan", "ts": "...", "needs_additional_experiments": <bool>} and continue.

Step 0.4 — Branch on Stage 0 verdict

The cycle — Phases A through F

After Stage 0 + (any additional experiments) + cfd-cross-analyze have produced cross_experiment_analysis/ with comparison figures and cross_experiment_interpretation.md, the paper writing cycle begins. You will execute up to max_review_loops = 10 iterations of the following six-phase cycle:

Phase A — Planner (one LLM call; only on iteration 0)
Phase B — Batch PyVista figure script (one LLM call to author; bash to run; inner-loop revise if needed)
Phase C — Per-image vision QA (one vision pass per PNG; revise script via Phase B if any fail)
Phase D — Writer (iter 0) OR Reviser (iter ≥ 1) — one LLM call
Phase E — pdflatex compile (bash; compile-fix LLM call on failure, capped at 3 retries)
Phase F — Reviewer (one LLM call) → branch on verdict

Initialize the cycle state file before Phase A:

OUT=<out-dir>
mkdir -p "$OUT/checkpoints" "$OUT/paper" "$OUT/paper_figs" "$OUT/paper/history"
test -f "$OUT/paper_cycle_state.json" || cat > "$OUT/paper_cycle_state.json" <<'EOF'
{
  "iteration": 0,
  "max_review_loops": 10,
  "score_threshold": 0.7,
  "stage": "starting",
  "regenerate_batch_figures": true,
  "needs_additional_visualization": false,
  "additional_viz_specs": [],
  "recommendations": [],
  "pass": false,
  "viz_inner_attempts": 0,
  "compile_inner_retries": 0
}
EOF
echo "cycle state initialized: $(cat $OUT/paper_cycle_state.json)"

Append {"stage": "paper_review", "event": "cycle_started", "ts": "<iso>"} to <out-dir>/timeline.json.

GOTO Phase A.

Phase A — Planner (one LLM call; iteration 0 only)

Only runs once. If paper_unified_plan.json already exists and passes schema validation, skip Phase A and GOTO Phase B.

A.1 — Build the planner input string

Concatenate (≤ 120,000 chars; trim lowest-citation lit entries first if larger):

TOPIC: <state.json#topic>
 
MANIFEST SUCCESSFUL CASES (from manifest.json):
<the case objects with status=success>
 
REQUIREMENTS:
<requirements.json>
 
ANALYSIS:
<analysis.json>
 
LITERATURE (top 40 by citation count desc, year desc):
<lit.json top 40 entries, each with title/authors/year/venue/paperId/externalIds.DOI/abstract truncated to 400 chars>
 
MESH INDEPENDENCE BUNDLE:
<mesh_independence_context.json if present else {}>
 
STARTER UNDERSTANDING:
<starter_understanding.json relevant fields if present>
 
CROSS-EXPERIMENT CASE CONTEXT:
<cross_experiment_analysis/case_context.json if present>

A.2 — Run the planner LLM call

Your next response MUST be the planner's JSON output. Nothing else.

System prompt (you are the planner)

You are the planning head for a CFD journal manuscript tied to an automated experiment run.