jinko-task-paper2model

Paper to Jinkō model

Reconstruct the model the publication specifies, measure what was reproduced, and report what remains uncertain.

PREREQUISITE: This skill needs an initialized jinko-sdk connection and an SDK satisfying its metadata.requires_sdk range. Run the jinko-sdk-setup skill (../jinko-sdk-setup/SKILL.md) and proceed only once its check passes. If that skill is not found, install it from novainsilico/jinko-skills.

Rules

• Do not require author code. Reconstruct from equations, reaction diagrams, definitions, parameter tables, initial conditions, and scenario descriptions.
• Treat paper, supplement, OCR, digitized data, and code as distinct evidence. Keep a source locator and extraction method for each implemented fact.
• Use native extraction for clean PDFs. For scans or unreliable extracted math and tables, discover and prefer an available dedicated OCR capability. Accept any provider that produces the packet in references/evidence-and-ocr.md. PyPDF text extraction is not OCR. OCR is derived evidence and needs visual review where it affects equations, values, subscripts, signs, or units.
• Do not invent a missing target-driving value. Record an approved assumption or stop with blocked_evidence before creating a model.
• Apply source-supported corrections automatically when precise source evidence and a passed check support the change. Record the original statement, defense, and affected components. Follow references/interpretation-policy.md for translations, source conflicts, assumptions, and decision history.
• Freeze targets, comparison metrics, tolerances, event-side semantics, and source precedence before comparing simulations. Never tune until a plot looks similar.
• A target used to choose an interpretation is not independent validation. Link it to the decision, preserve this dependency through later revisions, and report held-out comparisons separately. Curated-model agreement and publication fidelity are separate assessments.
• Use jinko-model for model inspection and mutation, jinko-protocol for experimental arms or theoretical intervention scenarios, jinko-vpop for subject or cell-line variability and explicit deterministic grids, jinko-trial for trials, jinko-task-extract-data-table for figure or table values, jinko-reference for project evidence, and jinko-document only when the user wants the report published.
• Re-fetch each applied model version. Require no error diagnostics and a measured solve before calling it executable. A skipped check is unavailable, not passed.
• Always generate reproduction-report.md, including for blocked and failed work. Fidelity to one paper scenario does not establish general biological validity.
• In a planning-only handoff, label hashes, retrievals, and execution checks as pending unless a supplied receipt proves completion. Proposed actions are not completed evidence.

Workflow

1. Define the claim. Identify the exact paper, model variant, scenario, outputs, and whether the task is structural implementation, numerical reproduction, or both.

2. Build the evidence packet. Read references/evidence-and-ocr.md and retrieve linked supplements, appendices, data, and model-defining references before declaring evidence missing. Record each attempt and its result. After reasonable web attempts fail, ask whether the user has access to the precise missing primary paper or supplement and can upload it or provide a link. Record awaiting_user_source; continue independent sources. An access failure does not establish that the scientific evidence is intrinsically absent. Hash all local sources. Extract equations, symbols, values, units, initial conditions, events, and target results with page, equation, table, figure, or code locators.

3. Reconcile evidence. Check symbols, dimensions, initial-state consistency, and platform semantics. Record conflicts, alternatives, and their defense in the interpretation ledger. Apply verified source-supported corrections. Separate each correction from any missing value it leaves unresolved. Paper text, supplements, and code each need evidence to take precedence.

4. Test adequacy. After reconciliation, require enough information to execute every target-driving path, including approved assumptions. If values remain unresolved, create the report with blocked_evidence and do not mutate Jinkō.

5. Write the specification. Create reproduction-spec.json from assets/reproduction-spec.schema.json using schema version 1.0. Bind each experiment to its Protocol arm, Vpop rows, outputs, and target names as specified in references/workflow.md. Distinguish a deterministic initial-condition sweep from measured or sampled biological variability. In a planning handoff, name the planned arm and row IDs even while remote item IDs are null. A Protocol overrides model inputs; events, including washout and dosing, are defined in the model. Keep treatment and subject axes separate: reuse treatment arms across Vpop rows. Do not create a new arm solely because the subject or cell line changes. Run:

   python scripts/paper2model_report.py validate --spec reproduction-spec.json
   

6. Implement incrementally. Use jinko-model; keep each component linked to evidence, make algebraic assignments dynamic, and label meaningful versions. Represent reported experimental arms with a Protocol and reported subject or cell-line differences with a Vpop. Do not invent a population distribution. Keep dosing logic in the model and arm input overrides in the Protocol.

7. Validate execution. Inspect diagnostics, unit policy, state constraints, event behavior, time grid, and representative outputs. Compare with an independent calculation or authorized author code when available. Set the solving times from the paper, not from a default. Read the time horizon and the sampling resolution off each reported figure and record them with the target. A model with correct equations on the wrong time grid produces entirely different summary values, because min, max, tend, and timeofmax are all grid-dependent. When figures disagree on the horizon, prefer one run on the longest horizon and read the shorter figures from it, which is valid only when the resolution is fine enough for the shortest one. Otherwise use separate runs, or override tMax and tStep per protocol arm. Solving times live on the trial, not on the model, so they do not travel when a trial is copied or rebuilt: set them explicitly every time.

8. Compare the declared target. Apply predeclared metrics on the actual Jinkō time grid. Report every required series and scenario, including failures. If results justify another interpretation, start a new recorded decision and comparison round. Keep prior results and record targets used in selection. Report raw and transformed comparisons when a reporting convention changes.

9. Render and review the report. Populate outcomes in the specification and run:

   python scripts/paper2model_report.py render \
     --spec reproduction-spec.json \
     --out reproduction-report.md
   

   The default is concise. Use --profile audit for the complete local audit and --profile jinko for publication. Immediately after the title, place created artifact cards, then source cards, before findings. Store SDK .url values from the configured JINKO_URL in project_items. Every human-facing SID reference, including chat, captions, and appendices, must be a full link. Never print a naked SID or guess an app host. Resolve missing URLs before publication. Keep essential findings first and detailed tables local or in an explicitly requested appendix. When actual comparison results exist, add source-versus-simulation overlays, predeclared metrics, and uncertainty through visual_evidence. Include failed comparisons honestly. Never fabricate plots or insert placeholder images. By default, draw the overlays with the Jinkō plot style (jinko.plotting; recipes in jinko-trial, references/trial-plots.md). Use jinko-document for existing image upload mechanics, publication, and rendered inspection; retain the exact upload payload. Read references/report-delivery.md for fields, commands, and source requests. Use the renderer's layout even in a text-only handoff. Include no wrapper heading before the report. Check the entire response, including local notes, for naked SIDs. Keep unprovided independence and provenance claims pending. Embed each available measured comparison image as ![caption](actual-path); a filename in a list does not display the visual evidence. Copy target independence only from the inherited target record. If it is not supplied, omit the label or write unknown; a passed solve, failed target, or missing measurement cannot establish independence or qualitative agreement. End the delivery note with the local audit location or its pending status.

Read references/workflow.md for gates and artifact layout. Read references/fidelity-and-confidence.md before assigning the verdict or confidence.

Outcomes

• reproduced: executable model, all required publication targets pass without unresolved conflicts or selection-target leakage into the reproduction claim.
• partially_reproduced: executable model, but a required target fails or a material part of the declared scope is unresolved. Also use this outcome when a required publication target selected the current interpretation, including through a superseded decision, even if every numerical target passes. Lowering confidence alone does not satisfy this rule.
• implemented_not_assessed: executable model, but no quantitative publication target is available.
• failed_validation: a model exists, but diagnostics or execution failed.
• blocked_evidence: evidence is insufficient for a defensible executable model.

The report must state one outcome and one reproduction-confidence level. It must also state curated implementation agreement, or not_assessed when no curated comparison was performed. A defensible alternative can agree with the publication while differing from the curated implementation.