lev-evidence-review

name	lev-evidence-review
description	Use when verifying a LEV candidate bundle. Checks source fidelity, interpretation, and evidence-audit mappings; writes evidence-review records without publishing.

LEV Evidence Review

Use this after research has produced a candidate bundle and before editorial approval or publish.

Read First

• data/candidate-bundles/<bundle-id>.json
• staged files under data/staged-records/<bundle-id>/
• live target files referenced by each file_path
• existing data/evidence-reviews/ records for the same bundle
• related data/review-comments/ when they affect the current revision
• related research/coverage-assessments/ records when the bundle changes a track outlook or support map
• schemas/evidence-review.schema.json
• schemas/candidate-bundle.schema.json
• schemas/source.schema.json, schemas/study.schema.json, schemas/finding.schema.json, and schemas/outlook.schema.json when those records are staged
• scripts/research-bundle.mjs
• scripts/review-evidence.mjs
• src/lib/site-data.ts if publish or approval behavior matters

Read references/output-contract.md before writing anything.

Workflow

1. Work on one bundle revision and one review lane at a time.
2. Run npm run research:bundle -- status --bundle <bundle-id> and npm run research:bundle -- validate --bundle <bundle-id> before writing the review.
3. Confirm the lane:
   • source_fidelity
   • interpretation_forecast
   • safety_limitations
   • taxonomy_mapping
   • forecast_calibration
4. Use npm run research:review-evidence -- scaffold --bundle <bundle-id> --lane <lane> when starting a new lane review.
5. Compare the staged change against the live record and the claimed evidence boundaries.
   • For track outlooks, verify that supporting_evidence[] maps each rating rationale to concrete findings, sources, support roles, and limitations.
   • For track outlooks, check the latest coverage assessment when one exists and flag any known gap that should qualify or block the proposed interpretation.
   • For staged findings, verify that each finding has source/study provenance, endpoint boundaries, confidence, direction, and caveats.
   • Verify rating_change_criteria describes what would move the rating without implying the current evidence is stronger than it is.
6. Apply the completed review with npm run research:review-evidence -- apply --file <draft-path>.
7. Run npm run research:review-evidence -- status --bundle <bundle-id> and npm run research:bundle -- validate --bundle <bundle-id> after applying.
8. If the new record replaces an older review in the same lane for the same revision, confirm the older record is marked superseded.
9. Stop after the evidence-review layer is updated. Editorial comments, approval, and publish belong to other skills.

Review Standard

• Treat the bundle as potentially wrong or overstated.
• Distinguish activity from evidence.
• Distinguish biomarker movement from functional benefit.
• Default to narrower claims when the source boundary is ambiguous.
• Check extracted source facts: population/model, sample size, duration, intervention/exposure, endpoint, quantitative result, safety, funding/conflicts, and directness boundary.
• Do not accept a higher stage unless the support map contains current evidence for that stage and the public wording states the boundary.
• A source list is not sufficient support by itself; require explicit source -> study -> finding -> outlook rationale mapping when rating claims are public.
• Keep caveats near the claim they qualify, including sponsor, duration, population, endpoint, and attribution limits.
• Treat coverage_verdict: "thin" or high-priority coverage gaps as a reason to preserve conservative public language unless the bundle explicitly repairs those gaps.
• Use needs_human_judgment when the evidence is bounded but the public wording still depends on curator judgment.

Boundaries

• Do not do new source discovery in this skill.
• Do not change public live records or staged record contents unless the task explicitly includes revising the bundle after review.
• Do not approve or publish bundles.
• Do not leave findings implied in prose only. Put them in structured findings[].
• Do not accept a track outlook rating change if its evidence audit trail is missing or materially stale.

Expected Outputs

• one new or revised data/evidence-reviews/<review-id>.json
• bundle metadata updated so evidence_review_ids[] includes the review
• older same-lane review records marked superseded when replaced