--- name: review-research description: This skill should be used for RESEARCH.md artifact reviewer — validates that all findings cite evidence, confidence levels are justified, pitfalls are actionable, and recommendations are concrete and implementable argument-hint: "" user-invocable: false version: 0.1.0 --- # review-research RESEARCH.md reviewer skill. Implements the artifact-reviewer framework interface to validate a RESEARCH.md file against SB research quality criteria. Returns structured PASS/ISSUES_FOUND findings. ## Loading Rules This reviewer MUST load the following before executing any review: - `@skills/artifact-reviewer/rules/reviewer-interface.md` — interface contract (input/output shape, prohibitions) - `@skills/artifact-reviewer/rules/review-loop.md` — 2-pass loop mechanism and audit trail format ## Usage ``` /artifact-reviewer ``` Or invoke directly: ``` /review-research ``` ## Input | Field | Type | Required | Description | |-------|------|----------|-------------| | artifact_path | string | YES | Path to RESEARCH.md file to review | | source_inputs | string[] | NO | Optional paths (e.g., phase CONTEXT.md for key questions) | | review_context | string | NO | Additional context string (e.g., phase name for key question matching) | ## Quality Criteria Read the artifact at `artifact_path` completely before evaluating any criterion. Validate every criterion explicitly — do NOT skip sections. ### QC-1: Key Questions Are Addressed (when review_context available) If `review_context` or `source_inputs` includes a phase CONTEXT.md with a list of key research questions, every listed key question MUST have a corresponding finding or section in the RESEARCH.md that addresses it. **If any key question is unanswered:** Emit ISSUE finding `RES-F01` (increment suffix per missing question) with location = the unanswered question from CONTEXT.md, suggestion = "Add a finding or section addressing this key question: '[question text]'." ### QC-2: Findings Are Evidence-Based — No Speculative Findings Every finding stated in the RESEARCH.md MUST cite at least one piece of evidence. Acceptable evidence includes: - A documentation URL (e.g., `https://docs.example.com/...`) - A library version number with a source reference (e.g., "v4.2.1, see npm registry") - Benchmark data with a named test or source - A named RFC, standard, or specification A finding is speculative if it makes a factual claim without citing any source. Phrases like "I believe", "it seems", "generally", "typically" without evidence are speculative. **If any speculative finding found:** Emit ISSUE finding `RES-F10` (increment suffix per speculative finding) with severity ISSUE, location = the finding, description = "Speculative finding — no evidence cited", suggestion = "Add a citation: documentation URL, library version with source, benchmark data, or named standard that supports this claim." ### QC-3: Confidence Levels Are Justified If the RESEARCH.md uses confidence levels (high/medium/low, or percentage estimates), each confidence assertion MUST include reasoning explaining WHY that confidence level was assigned — not just the label. Unjustified confidence examples (fail): "Confidence: High", "Confidence: Medium — this is uncertain." Justified confidence examples (pass): "Confidence: High — official documentation explicitly states X, tested against v4.1.2", "Confidence: Low — only one source found, dated 2021, may be outdated." **If any unjustified confidence level found:** Emit ISSUE finding `RES-F20` with location = the confidence assertion, suggestion = "Add reasoning explaining the confidence level: what evidence supports it and what gaps or risks reduce it." ### QC-4: Pitfalls and Warnings Are Actionable If the RESEARCH.md contains pitfalls, "don't hand-roll" warnings, or anti-patterns, each MUST: 1. Name the specific risk (what goes wrong and why) 2. Name the alternative or mitigation (what to do instead) A pitfall that only says "avoid X" without explaining the risk or naming an alternative is not actionable. **If any non-actionable pitfall found:** Emit ISSUE finding `RES-F30` with location = the pitfall entry, suggestion = "Expand this pitfall to name the specific failure mode and the recommended alternative, e.g., 'Do not hand-roll JWT validation — use [library name] because [specific risk]'." ### QC-5: Recommendations Section Exists with Concrete Choices The RESEARCH.md MUST contain a `## Recommendations` (or equivalent concluding section) with at least one recommendation. Each recommendation MUST be: - **Concrete**: names a specific library, approach, version, or pattern — not a category - **Implementable**: actionable enough that an engineer can act on it without further research **If Recommendations section is missing or empty:** Emit ISSUE finding `RES-F40` with suggestion = "Add a `## Recommendations` section with at least one concrete, implementable recommendation derived from the research findings." **If any recommendation is too vague:** Emit ISSUE finding `RES-F41` with location = the vague recommendation, suggestion = "Make this recommendation concrete: name the specific library, version, or approach to use." ### QC-6: No Stale References (INFO-level) If the RESEARCH.md references version numbers, these SHOULD be current (within a reasonable timeframe). Version numbers that appear to be more than 2 major versions behind the current ecosystem norm, or that reference deprecated packages, are flagged at INFO level. **If potentially outdated version found:** Emit INFO finding `RES-F50` with location = the version reference, description = "Potentially outdated version reference — verify this is still current", suggestion = "Check whether [library/tool] has released a newer stable version since this research was written and update if necessary." ## Output Contract Return structured findings using the schema from `reviewer-interface.md`. Finding IDs MUST use the prefix `RES-F`. ``` status: "PASS" | "ISSUES_FOUND" findings: - id: "RES-F10" # unique within this review severity: "ISSUE" # or "INFO" description: "..." # what is wrong location: "..." # section header or line reference suggestion: "..." # specific, actionable fix ``` **Status rules:** - `PASS` — zero ISSUE-severity findings; INFO findings allowed - `ISSUES_FOUND` — one or more ISSUE-severity findings ## Reviewer Prohibitions - Do NOT modify the artifact — this reviewer is strictly read-only - Do NOT skip sections because they look complete — validate every QC criterion explicitly - Do NOT return PASS when any required section is missing or empty - Do NOT conflate INFO and ISSUE — only ISSUE findings block progression - Do NOT return unstructured prose as the primary output