scholar-evaluation · diff
git:20260721.831d49e to v2.0
217 added, 219 removed. Audit A to A.
---
name: scholar-evaluation
- description: Systematically evaluate scholarly work using the ScholarEval framework, providing structured assessment across research quality dimensions including problem formulation, methodology, analysis, and writing with quantitative scoring and actionable feedback.
- license: MIT license
- required_environment_variables: [{"name": "OPENROUTER_API_KEY", "prompt": "OpenRouter API key for the skill's LLM-powered steps.", "required_for": "optional features"}]
- metadata: {"version": "1.2", "skill-author": "K-Dense Inc.", "openclaw": {"primaryEnv": "OPENROUTER_API_KEY", "envVars": [{"name": "OPENROUTER_API_KEY", "required": false, "description": "OpenRouter API key for the skill's LLM-powered steps."}]}}
+ description: Provide qualitative-first, evidence-traceable developmental review of scholarly works and audit low-stakes research-assessment rubrics with optional local quality controls. Never use for ranking people or consequential decisions.
+ license: MIT
+ compatibility: Requires Python 3.11+ for optional bundled standard-library CLIs. All tooling is local JSON/CSV processing with no network, credentials, external models, or subprocesses.
+ allowed-tools: Read, Write, Bash, Glob, Python
+ metadata:
+ version: "2.0"
+ skill-author: K-Dense Inc.
---
# Scholar Evaluation
- ## Overview
+ ## Purpose
- Apply the ScholarEval framework to systematically evaluate scholarly and research work. This skill provides structured evaluation methodology based on peer-reviewed research assessment criteria, enabling comprehensive analysis of academic papers, research proposals, literature reviews, and scholarly writing across multiple quality dimensions.
+ Provide developmental, evidence-traceable feedback on a **scholarly work**:
+ paper, draft, protocol, literature synthesis, or research idea. Use
+ qualitative judgment first. Optional scores only describe how submitted
+ evidence maps to a predeclared bounded rubric.
- ## When to Use This Skill
+ This skill also audits whether a low-stakes assessment process documents its
+ construct, provenance, rater quality, uncertainty, traceability, sensitivity,
+ fairness, accessibility, privacy, and human governance.
- Use this skill when:
- - Evaluating research papers for quality and rigor
- - Assessing literature review comprehensiveness and quality
- - Reviewing research methodology design
- - Scoring data analysis approaches
- - Evaluating scholarly writing and presentation
- - Providing structured feedback on academic work
- - Benchmarking research quality against established criteria
- - Assessing publication readiness for target venues
- - Providing quantitative evaluation to complement qualitative peer review
+ ## Hard safety boundary
- ## Visual Enhancement with Scientific Schematics
+ Never use this skill to automate, recommend, materially influence, or score:
- **When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.**
+ - hiring, promotion, or tenure;
+ - admissions;
+ - grants or other funding;
+ - prizes, honors, or awards;
+ - discipline, dismissal, or sanctions; or
+ - any other high-impact personnel decision.
- If your document does not already contain schematics or diagrams:
- - Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams
- - Simply describe your desired diagram in natural language
- - Nano Banana Pro will automatically generate, review, and refine the schematic
+ Never rank people. Never reduce a person to a composite score. Never infer
+ ability, character, integrity, protected traits, future performance, or worth.
+ A nominal human-in-the-loop does not remove this boundary.
- **For new documents:** Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text.
+ If asked for a prohibited use, stop. Offer developmental comments on a
+ scholarly work or a process-only audit that does not process applications,
+ compare people, recommend an outcome, or advise a decision.
- **How to generate schematics:**
- ```bash
- python scripts/generate_schematic.py "your diagram description" -o figures/output.png
- ```
+ Do not issue publication-readiness, accept/reject, or “top-tier” judgments.
- The AI will automatically:
- - Create publication-quality images with proper formatting
- - Review and refine through multiple iterations
- - Ensure accessibility (colorblind-friendly, high contrast)
- - Save outputs in the figures/ directory
+ Read `references/responsible_assessment.md` before any organizational use.
- **When to add schematics:**
- - Evaluation framework diagrams
- - Quality assessment criteria decision trees
- - Scholarly workflow visualizations
- - Assessment methodology flowcharts
- - Scoring rubric visualizations
- - Evaluation process diagrams
- - Any complex concept that benefits from visualization
+ ## ScholarEval status
- For detailed guidance on creating schematics, refer to the scientific-schematics skill documentation.
+ The referenced ScholarEval project is an **experimental
+ literature-grounded research-idea evaluation framework**, not validated
+ psychometrics.
- ---
+ The verified primary record is Moussa et al., *ScholarEval: Research Idea
+ Evaluation Grounded in Literature*, arXiv:2510.16234v2, revised 2026-02-28.
+ It reports a retrieval-augmented soundness/contribution framework, a
+ 117-idea four-discipline dataset, coverage experiments, and a user study.
- ## Evaluation Workflow
+ Do not generalize those results to person assessment, consequential decisions,
+ all disciplines, or this skill's rubric. No peer-reviewed publication status
+ was verified during the dated review. See `references/source_ledger.md`.
- ### Step 1: Initial Assessment and Scope Definition
+ ## Metric and prestige policy
- Begin by identifying the type of scholarly work being evaluated and the evaluation scope:
+ Do not score or infer quality from:
- **Work Types:**
- - Full research paper (empirical, theoretical, or review)
- - Research proposal or protocol
- - Literature review (systematic, narrative, or scoping)
- - Thesis or dissertation chapter
- - Conference abstract or short paper
+ - Journal Impact Factor or other journal measures;
+ - h-index, publication counts, or citation counts;
+ - altmetrics or attention;
+ - journal, conference, venue, institution, employer, or geographic prestige;
+ - author affiliation, reputation, network, or career path.
- **Evaluation Scope:**
- - Comprehensive (all dimensions)
- - Targeted (specific aspects like methodology or writing)
- - Comparative (benchmarking against other work)
+ The rubric validator rejects common proxy-measure criteria.
- Ask the user to clarify if the scope is ambiguous.
+ If a qualified reviewer mentions an indicator descriptively outside the
+ scoring tools, record its exact purpose, source, coverage, field and time
+ effects, uncertainty, missingness, biases, gaming risk, and why it does not
+ directly measure quality. Never hide indicators inside an opaque composite.
- ### Step 2: Dimension-Based Evaluation
+ ## Data boundary
- Systematically evaluate the work across the ScholarEval dimensions. For each applicable dimension, assess quality, identify strengths and weaknesses, and provide scores where appropriate.
+ Bundled scripts accept only strict local JSON/CSV containing pseudonymous IDs,
+ bounded ratings, statuses, uncertainty, and local references.
- Refer to `references/evaluation_framework.md` for detailed criteria and rubrics for each dimension.
+ Do not put raw private applications, CVs, letters, reviewer identities,
+ contact details, protected attributes, or source-document text in inputs,
+ outputs, logs, examples, or prompts. Keep source content in the authorized
+ records system and use opaque local references.
- **Core Evaluation Dimensions:**
+ Allowed classifications are:
- 1. **Problem Formulation & Research Questions**
- - Clarity and specificity of research questions
- - Theoretical or practical significance
- - Feasibility and scope appropriateness
- - Novelty and contribution potential
+ - `synthetic`
+ - `public_scholarly_work`
+ - `deidentified_low_stakes`
- 2. **Literature Review**
- - Comprehensiveness of coverage
- - Critical synthesis vs. mere summarization
- - Identification of research gaps
- - Currency and relevance of sources
- - Proper contextualization
+ No script searches the web, loads environment files, reads credentials, calls a
+ model, executes supplied text, deserializes executable objects, or launches a
+ process.
- 3. **Methodology & Research Design**
- - Appropriateness for research questions
- - Rigor and validity
- - Reproducibility and transparency
- - Ethical considerations
- - Limitations acknowledgment
+ Use Bash only to invoke the documented local `python3` commands.
- 4. **Data Collection & Sources**
- - Quality and appropriateness of data
- - Sample size and representativeness
- - Data collection procedures
- - Source credibility and reliability
+ ## Workflow
- 5. **Analysis & Interpretation**
- - Appropriateness of analytical methods
- - Rigor of analysis
- - Logical coherence
- - Alternative explanations considered
- - Results-claims alignment
+ ### 1. Confirm allowed use and authorization
- 6. **Results & Findings**
- - Clarity of presentation
- - Statistical or qualitative rigor
- - Visualization quality
- - Interpretation accuracy
- - Implications discussion
+ Record:
- 7. **Scholarly Writing & Presentation**
- - Clarity and organization
- - Academic tone and style
- - Grammar and mechanics
- - Logical flow
- - Accessibility to target audience
+ - developmental purpose;
+ - unit of assessment: `scholarly_work`;
+ - work type, stage, discipline, language, and audience;
+ - authorized source location and data classification;
+ - accountable committee owner;
+ - conflicts and recusals;
+ - accessibility and accommodation process;
+ - appeal or correction route; and
+ - data purpose, access, retention, and deletion.
- 8. **Citations & References**
- - Citation completeness
- - Source quality and appropriateness
- - Citation accuracy
- - Balance of perspectives
- - Adherence to citation standards
+ Stop on a prohibited decision context or unnecessary private data.
- ### Step 3: Scoring and Rating
+ ### 2. Define the construct before criteria
- For each evaluated dimension, provide:
+ State:
- **Qualitative Assessment:**
- - Key strengths (2-3 specific points)
- - Areas for improvement (2-3 specific points)
- - Critical issues (if any)
+ - what quality or support is being examined;
+ - excluded constructs;
+ - intended interpretation;
+ - contexts where the interpretation does not travel;
+ - evidence requirements; and
+ - known limitations.
- **Quantitative Scoring (Optional):**
- Use a 5-point scale where applicable:
- - 5: Excellent - Exemplary quality, publishable in top venues
- - 4: Good - Strong quality with minor improvements needed
- - 3: Adequate - Acceptable quality with notable areas for improvement
- - 2: Needs Improvement - Significant revisions required
- - 1: Poor - Fundamental issues requiring major revision
+ Start with values and disciplinary context, not available metrics.
- To calculate aggregate scores programmatically, use `scripts/calculate_scores.py`.
+ ### 3. Adapt and validate the rubric
- ### Step 4: Synthesize Overall Assessment
+ Begin with `assets/rubric_template.json`, then obtain qualified disciplinary,
+ assessment-methods, stakeholder, accessibility, privacy, and fairness review.
- Provide an integrated evaluation summary:
+ The template deliberately records content validity as `not_established`.
+ Do not change that status without documented evidence for the exact intended
+ use.
- 1. **Overall Quality Assessment** - Holistic judgment of the work's scholarly merit
- 2. **Major Strengths** - 3-5 key strengths across dimensions
- 3. **Critical Weaknesses** - 3-5 primary areas requiring attention
- 4. **Priority Recommendations** - Ranked list of improvements by impact
- 5. **Publication Readiness** (if applicable) - Assessment of suitability for target venues
+ Validate structure:
- ### Step 5: Provide Actionable Feedback
+ ```bash
+ PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_rubric.py \
+ --rubric assets/rubric_template.json
+ ```
- Transform evaluation findings into constructive, actionable feedback:
+ Read `references/evaluation_framework.md` for construct, anchor, validity, and
+ rater guidance.
- **Feedback Structure:**
- - **Specific** - Reference exact sections, paragraphs, or page numbers
- - **Actionable** - Provide concrete suggestions for improvement
- - **Prioritized** - Rank recommendations by importance and feasibility
- - **Balanced** - Acknowledge strengths while addressing weaknesses
- - **Evidence-based** - Ground feedback in evaluation criteria
+ ### 4. Build traceable evidence records
- **Feedback Format Options:**
- - Structured report with dimension-by-dimension analysis
- - Annotated comments mapped to specific document sections
- - Executive summary with key findings and recommendations
- - Comparative analysis against benchmark standards
+ Reviewers may read an authorized work outside the scripts. Record only stable
+ local locators and claim references in
+ `assets/evidence_manifest_template.json`.
- ### Step 6: Contextual Considerations
+ For every criterion, distinguish:
- Adjust evaluation approach based on:
+ - observed evidence from interpretation;
+ - supporting from contrary evidence;
+ - available from unavailable evidence;
+ - `missing` from `not_applicable`; and
+ - uncertainty from absence.
- **Stage of Development:**
- - Early draft: Focus on conceptual and structural issues
- - Advanced draft: Focus on refinement and polish
- - Final submission: Comprehensive quality check
+ Failure to find prior work does not prove novelty.
- **Purpose and Venue:**
- - Journal article: High standards for rigor and contribution
- - Conference paper: Balance novelty with presentation clarity
- - Student work: Educational feedback with developmental focus
- - Grant proposal: Emphasis on feasibility and impact
+ ### 5. Rate independently
- **Discipline-Specific Norms:**
- - STEM fields: Emphasis on reproducibility and statistical rigor
- - Social sciences: Balance quantitative and qualitative standards
- - Humanities: Focus on argumentation and scholarly interpretation
+ Use `assets/evaluation_template.json`. Each criterion must be:
- ## Resources
+ - `rated` with an anchor score, bounded uncertainty, evidence IDs, and a local
+ rationale reference;
+ - `missing` with null score/uncertainty and a rationale reference; or
+ - `not_applicable` with null score/uncertainty and a rationale reference.
- ### references/evaluation_framework.md
+ Do not encode missing or not-applicable as zero. Raters should train, calibrate,
+ disclose conflicts, rate independently, and document disagreement.
- Detailed evaluation criteria, rubrics, and quality indicators for each ScholarEval dimension. Load this reference when conducting evaluations to access specific assessment guidelines and scoring rubrics.
+ ### 6. Run local quality checks
- Search patterns for quick access:
- - "Problem Formulation criteria"
- - "Literature Review rubric"
- - "Methodology assessment"
- - "Data quality indicators"
- - "Analysis rigor standards"
- - "Writing quality checklist"
+ Bounded scoring, without labels or recommendation:
- ### scripts/calculate_scores.py
+ ```bash
+ PYTHONDONTWRITEBYTECODE=1 python3 scripts/calculate_scores.py \
+ --rubric assets/rubric_template.json \
+ --evaluation assets/evaluation_template.json
+ ```
- Python script for calculating aggregate evaluation scores from dimension-level ratings. Supports weighted averaging, threshold analysis, and score visualization.
+ Evidence traceability:
- Usage:
```bash
- python scripts/calculate_scores.py --scores <dimension_scores.json> --output <report.txt>
+ PYTHONDONTWRITEBYTECODE=1 python3 scripts/check_traceability.py \
+ --rubric assets/rubric_template.json \
+ --evaluation assets/evaluation_template.json \
+ --evidence assets/evidence_manifest_template.json
```
- ## Best Practices
+ Inter-rater agreement:
- 1. **Maintain Objectivity** - Base evaluations on established criteria, not personal preferences
- 2. **Be Comprehensive** - Evaluate all applicable dimensions systematically
- 3. **Provide Evidence** - Support assessments with specific examples from the work
- 4. **Stay Constructive** - Frame weaknesses as opportunities for improvement
- 5. **Consider Context** - Adjust expectations based on work stage and purpose
- 6. **Document Rationale** - Explain the reasoning behind assessments and scores
- 7. **Encourage Strengths** - Explicitly acknowledge what the work does well
- 8. **Prioritize Feedback** - Focus on high-impact improvements first
+ ```bash
+ PYTHONDONTWRITEBYTECODE=1 python3 scripts/summarize_agreement.py \
+ --rubric assets/rubric_template.json \
+ --ratings assets/ratings_template.csv
+ ```
- ## Example Evaluation Workflow
+ Weight sensitivity requires two or more distinct scholarly-work evaluation
+ files:
- **User Request:** "Evaluate this research paper on machine learning for drug discovery"
+ ```bash
+ PYTHONDONTWRITEBYTECODE=1 python3 scripts/weight_sensitivity.py \
+ --rubric assets/rubric_template.json \
+ --evaluation /tmp/work-a-evaluation.json \
+ --evaluation /tmp/work-b-evaluation.json
+ ```
- **Response Process:**
- 1. Identify work type (empirical research paper) and scope (comprehensive evaluation)
- 2. Load `references/evaluation_framework.md` for detailed criteria
- 3. Systematically assess each dimension:
- - Problem formulation: Clear research question about ML model performance
- - Literature review: Comprehensive coverage of recent ML and drug discovery work
- - Methodology: Appropriate deep learning architecture with validation procedures
- - [Continue through all dimensions...]
- 4. Calculate dimension scores and overall assessment
- 5. Synthesize findings into structured report highlighting:
- - Strong methodology and reproducible code
- - Needs more diverse dataset evaluation
- - Writing could improve clarity in results section
- 6. Provide prioritized recommendations with specific suggestions
+ Process controls:
- ## Integration with Scientific Writer
+ ```bash
+ PYTHONDONTWRITEBYTECODE=1 python3 scripts/check_process.py \
+ --process assets/process_checklist_template.json
+ ```
- This skill integrates seamlessly with the scientific writer workflow:
+ The checklist template is intentionally unconfirmed and fails closed.
+ Instructions and exact schemas are in `references/local_tooling.md`.
- **After Paper Generation:**
- - Use Scholar Evaluation as an alternative or complement to peer review
- - Generate `SCHOLAR_EVALUATION.md` alongside `PEER_REVIEW.md`
- - Provide quantitative scores to track improvement across revisions
+ ### 7. Synthesize qualitative findings
- **During Revision:**
- - Re-evaluate specific dimensions after addressing feedback
- - Track score improvements over multiple versions
- - Identify persistent weaknesses requiring attention
+ Lead with criterion-level evidence, not the composite. For each criterion:
- **Publication Preparation:**
- - Assess readiness for target journal/conference
- - Identify gaps before submission
- - Benchmark against publication standards
+ 1. cite evidence references;
+ 2. state `rated`, `missing`, or `not_applicable`;
+ 3. explain the anchor interpretation;
+ 4. report score and uncertainty only if rated;
+ 5. note disagreements and context;
+ 6. identify strengths and limitations; and
+ 7. offer non-prescriptive improvement options.
- ## Notes
+ Generate an empty-reference scaffold if useful:
- - Evaluation rigor should match the work's purpose and stage
- - Some dimensions may not apply to all work types (e.g., data collection for purely theoretical papers)
- - Cultural and disciplinary differences in scholarly norms should be considered
- - This framework complements, not replaces, domain-specific expertise
- - Use in combination with peer-review skill for comprehensive assessment
+ ```bash
+ PYTHONDONTWRITEBYTECODE=1 python3 scripts/generate_report_scaffold.py \
+ --rubric assets/rubric_template.json \
+ --evaluation assets/evaluation_template.json \
+ --output /tmp/developmental-report-scaffold.json
+ ```
- ## Citation
+ The scaffold does not read source documents or draft findings.
- This skill is based on the ScholarEval framework introduced in:
+ ### 8. Human review and release
- **Moussa, H. N., Da Silva, P. Q., Adu-Ampratwum, D., East, A., Lu, Z., Puccetti, N., Xue, M., Sun, H., Majumder, B. P., & Kumar, S. (2025).** _ScholarEval: Research Idea Evaluation Grounded in Literature_. arXiv preprint arXiv:2510.16234. [https://arxiv.org/abs/2510.16234](https://arxiv.org/abs/2510.16234)
+ Before releasing an organizational report, a qualified accountable human
+ committee must verify:
- **Abstract:** ScholarEval is a retrieval augmented evaluation framework that assesses research ideas based on two fundamental criteria: soundness (the empirical validity of proposed methods based on existing literature) and contribution (the degree of advancement made by the idea across different dimensions relative to prior research). The framework achieves significantly higher coverage of expert-annotated evaluation points and is consistently preferred over baseline systems in terms of evaluation actionability, depth, and evidence support.
+ - construct and rubric provenance;
+ - content-validity evidence and limits;
+ - rater training, agreement, inter-rater reliability evidence, and drift;
+ - evidence traceability and source access;
+ - missingness, not-applicable rationales, and uncertainty;
+ - weight sensitivity and order instability;
+ - disciplinary and subgroup bias review;
+ - conflicts and recusals;
+ - accessibility and accommodations;
+ - privacy, minimization, retention, and output controls; and
+ - correction or appeal information.
+ Document dissent. Do not imply consensus, validity, or precision beyond the
+ evidence. Periodically evaluate the evaluation and retire harmful criteria.
+
+ ## Interpretation rules
+
+ - A score is an ordinal rubric summary, not a natural measurement.
+ - Normalization does not repair incomplete evidence.
+ - The bundled uncertainty range is not a confidence interval.
+ - Agreement does not establish reliability, validity, fairness, or correctness.
+ - Stable results under tested weights do not establish validity.
+ - The overall score never overrides criterion evidence or qualified judgment.
+ - No output is a decision recommendation.
+
+ ## Bundled resources
+
+ - `references/responsible_assessment.md` — safety, metrics, governance,
+ accessibility, privacy, and bias.
+ - `references/evaluation_framework.md` — ScholarEval boundary, construct,
+ criteria, anchors, validity, and interpretation.
+ - `references/local_tooling.md` — strict schemas, formulas, commands, and
+ output behavior.
+ - `references/source_ledger.md` — authoritative sources and publication-status
+ verification dated 2026-07-23.
+ - `references/security_validation.md` — baseline remediation, validation, and
+ residual security-scan record.
+ - `assets/rubric_template.json` — bounded rubric template.
+ - `assets/evaluation_template.json` — rating template.
+ - `assets/evidence_manifest_template.json` — traceability template.
+ - `assets/process_checklist_template.json` — fail-closed process checklist.
+ - `assets/ratings_template.csv` — synthetic agreement data.