general-fair-data-review

---
name: general-fair-data-review
description: Review a manuscript or code repository for FAIR data compliance (Findable, Accessible, Interoperable, Reusable), producing a structured report with pass/fail per principle and actionable remediation steps.
category: [general]
---

# General FAIR Data Review

## Goal

Assess whether a manuscript submission or standalone code/data repository satisfies the FAIR Guiding Principles (Wilkinson et al., *Sci. Data* 2016). The output is a structured reviewer report — analogous to a peer-review report — that scores each FAIR sub-principle, identifies gaps, and provides concrete remediation steps the authors can act on before publication.

This skill is complementary to [general-peer-review](../general-peer-review/SKILL.md), which focuses on scientific methodology. Run both in sequence for a complete review.

---

## Prerequisites

- A manuscript (PDF or markdown) **and/or** a link to a code/data repository (GitHub, Zenodo, Figshare, etc.)
- Read access to any supplementary files, Data Availability Statements (DAS), or README files provided by the authors

---

## Instructions

### 1. Identify Review Scope

Determine what artifacts are under review. Three modes exist:

| Mode | Input | Focus |
|------|-------|-------|
| **Manuscript + data/code** | PDF + repo URL | Full FAIR review |
| **Manuscript only** | PDF | DAS quality, metadata richness, identifier presence |
| **Code/data repo only** | Repo URL / directory | Repository-level FAIR compliance |

State the mode explicitly at the start of the review report.

---

### 2. Read the Manuscript and Data Availability Statement

Load the manuscript. Locate and extract:
- The **Data Availability Statement** (DAS) — usually a dedicated section near the end.
- Any **Code Availability Statement**.
- All **data/code repository URLs** or DOIs mentioned.

If no DAS exists, flag immediately as a **Critical Finding** (fails F4, A1, R1.1).

---

### 3. Inspect the Data/Code Repository

For each repository URL found, check the following. If no repository exists, mark all sub-principles below as **Fail**.

```
Repository inspection checklist:
- Does a persistent identifier (DOI, Handle) exist? → F1
- Is metadata present and rich (title, authors, description, keywords, license)? → F2, R1
- Does the metadata explicitly reference the dataset/code identifier? → F3
- Is the repository indexed in a searchable resource (Zenodo, Figshare, OSF, etc.)? → F4
- Can the data/code be accessed via a standard protocol (HTTP/HTTPS, FTP)? → A1
- Is the protocol open and free (no proprietary portal login required)? → A1.1
- If restricted, is there a documented access procedure? → A1.2
- Does metadata remain accessible even if data is removed? → A2
- Are standard, community-recognized formats used (CIF, JSON, CSV, HDF5, not .xlsx or proprietary)? → I1
- Are domain ontologies or controlled vocabularies used for metadata fields? → I2
- Are cross-references to related datasets or publications included? → I3
- Is a clear, machine-readable license present (CC-BY, MIT, Apache 2.0, etc.)? → R1.1
- Is provenance documented (how data was generated, software versions, parameters)? → R1.2
- Do files conform to domain community standards (e.g., CIF for crystal structures, SMILES for molecules, HDF5 for trajectories)? → R1.3
```

---

### 4. Score Each FAIR Sub-Principle

For every sub-principle (F1–F4, A1–A2, I1–I3, R1–R1.3) assign:

- **Pass** — requirement fully met
- **Partial** — requirement partially met; improvement needed
- **Fail** — requirement not met or artifact absent
- **N/A** — not applicable to this submission type

---

### 5. Atomistic/Computational Science Specific Checks

In addition to the generic FAIR checklist, evaluate the following domain-specific criteria:

**Structures & Trajectories**
- Crystal structures deposited as `.cif` (not as images or in supplementary PDF tables)
- MD trajectories deposited in open formats (`.xyz`, `.extxyz`, `.h5md`, `.lammpsdump`) with a `README` specifying units, timestep, ensemble
- Force field / MLIP checkpoints deposited with version, training set provenance, and validation metrics

**Computational Parameters**
- DFT: INCAR/POTCAR/KPOINTS or equivalent included or described with exact values (not "similar to ref. X")
- MLIP: model architecture, training hyperparameters, and train/val/test split recorded
- MD: timestep, thermostat/barostat settings, equilibration protocol documented

**Software Environment**
- `environment.yml` or `requirements.txt` present with pinned versions
- Scripts runnable from the deposited repository without undocumented external dependencies

---

### 6. Generate the Structured Review Report

Produce a report in the following format:

```markdown
# FAIR Data Review Report

**Manuscript title:** [title]
**Review date:** [date]
**Reviewer:** AI FAIR Data Reviewer (general-fair-data-review skill)
**Review mode:** [Manuscript + data/code | Manuscript only | Code/data repo only]

---

## Summary

[2–4 sentences: overall FAIRness level, most critical gaps, overall recommendation: Ready / Minor Revisions / Major Revisions / Not Acceptable]

---

## FAIR Scorecard

| Principle | Sub-principle | Status | Evidence / Gap |
|-----------|--------------|--------|----------------|
| **Findable** | F1: Persistent identifier | Pass/Partial/Fail | ... |
| | F2: Rich metadata | | |
| | F3: Metadata references data ID | | |
| | F4: Indexed in searchable resource | | |
| **Accessible** | A1: Retrievable via standard protocol | | |
| | A1.1: Protocol open and free | | |
| | A1.2: Auth procedure documented | | |
| | A2: Metadata accessible if data removed | | |
| **Interoperable** | I1: Formal/shared knowledge representation | | |
| | I2: FAIR vocabularies used | | |
| | I3: Qualified references to other data | | |
| **Reusable** | R1: Rich, accurate, relevant attributes | | |
| | R1.1: Clear data usage license | | |
| | R1.2: Detailed provenance | | |
| | R1.3: Domain community standards met | | |

---

## Major Concerns

[Number sequentially. For each: state issue → why problematic → actionable fix.]

1. **[Issue title]**
   - *Problem:* ...
   - *Impact:* ...
   - *Fix:* ...

---

## Minor Concerns

- ...

---

## Atomistic/Computational Specific Findings

[Report on structure formats, trajectory deposits, software environments, parameter completeness.]

---

## Questions for Authors

1. ...

---

## Recommended Repositories (if none provided)

If no repository was deposited, suggest domain-appropriate options:

| Data type | Recommended repository |
|-----------|----------------------|
| Crystal structures | CCDC, ICSD, Materials Cloud, Zenodo |
| Molecular dynamics trajectories | Materials Cloud, Zenodo, NOMAD |
| ML models / checkpoints | Hugging Face, Zenodo, MACE-Models |
| General datasets | Zenodo, Figshare, Dryad |
| Code | GitHub + Zenodo DOI via Zenodo GitHub integration |
```

---

## Document-Specific Workflows

### Manuscript Review (PDF)

> [!WARNING]
> Read the PDF text directly. Do **not** assume data exists unless a DOI or repository URL is explicitly present in the manuscript body or supplement.

Steps:
1. Extract DAS and Code Availability Statement verbatim.
2. Resolve any DOIs or URLs found.
3. If DOIs resolve to a live repository, proceed with repository inspection (Step 3).
4. If only "data available upon request" is stated: flag as **Fail** for F1, F4, A1, R1.1 — this does not meet FAIR standards.

### Code/Data Repository Review Only

Steps:
1. Read top-level `README.md`.
2. Check for `LICENSE`, `environment.yml`/`requirements.txt`, `CITATION.cff`.
3. Inspect directory structure for data files and their formats.
4. Check metadata on the repository platform (Zenodo record, GitHub About section, etc.).

---

## Constraints

- **Scope**: Focus strictly on data/code FAIRness. Scientific methodology critique belongs in [general-peer-review](../general-peer-review/SKILL.md).
- **Tone**: Objective and constructive. Every Fail must include a concrete, actionable fix.
- **"Data available upon request"**: Always flag as non-FAIR. Not acceptable per RSC Digital Discovery and FAIR principles.
- **Proprietary formats**: `.xlsx`, `.mat`, Gaussian `.chk`, VASP `WAVECAR` without open alternatives are I1/R1.3 failures.
- **License absence**: Unlicensed ≠ open. Always flag missing licenses as R1.1 Fail.

---

## References

- Wilkinson, M. D. et al., "The FAIR Guiding Principles for scientific data management and stewardship", *Sci. Data* **3**, 160018 (2016). [DOI: 10.1038/sdata.2016.18](https://doi.org/10.1038/sdata.2016.18)
- RSC Digital Discovery Data Review Guidelines. [rsc.org/publishing](https://www.rsc.org/publishing/publish-with-us/publish-a-journal-article/digital-discovery)

## See Also

- [general-peer-review](../general-peer-review/SKILL.md)
- [general-deep-research](../general-deep-research/SKILL.md)

---

**Author:** Magdalena Lederbauer
**Contact:** [GitHub @mlederbauer](https://github.com/mlederbauer)

More agent context in learningmatter-mit/AtomisticSkills

133 other files this repository gives its agents, the first 60 shown.