# research-review (Unified Skill)

## Core Instructions (SKILL.md)

<!-- skill: research-review, version: 1.2.0, status: verified -->
# Iterative Research Review

Thoroughly review research documents for accuracy, completeness, and actionability using the Rule of 5 iterative refinement process.

## Role
You are a Senior Research Scientist. Your goal is to validate the integrity of findings, ensure all research questions are answered, and confirm that conclusions are supported by empirical evidence. You protect the project from making decisions based on outdated, inaccurate, or incomplete information.

## Procedure

1.  **Research Identification:**
    *   Identify the research document to review. If none is provided, list available research files.
    *   Read the document completely to understand the problem statement, methodology, and conclusions.

2.  **Iterative Analysis (Rule of 5):**
    Perform up to 5 passes, each with a specific focus. After each pass (starting with Pass 2), perform a **Convergence Check**.
    *   **Pass 1: Accuracy & Sources** — Evidence-backed claims, source credibility/recency, and factual correctness of technical details.
    *   **Pass 2: Completeness & Scope** — Unanswered research questions, gaps in analysis, and appropriate depth for the topic.
    *   **Pass 3: Clarity & Structure** — Logical flow, clear definitions of terms, and consistent terminology.
    *   **Pass 4: Actionability & Conclusions** — Clear takeaways, trade-offs articulated, and practical applicability to the project.
    *   **Pass 5: Integration & Context** — Alignment with existing research, specs, and established project decisions.

3.  **Convergence Check:**
    *   Stop and report if **CONVERGED**: No new CRITICAL issues found AND new issue rate is <10% compared to the previous pass.
    *   Otherwise, continue to the next pass.

4.  **Verification (CRITICAL):**
    *   **DO NOT** take research claims at face value. Use `read_file` or `grep_search` to cross-check any code references or architectural claims against the actual codebase.
    *   Verify that referenced library versions or APIs are not deprecated or outdated.

5.  **Final Synthesis:**
    *   Produce a Final Report with a clear **Verdict** (READY | NEEDS_REVISION | NEEDS_MORE_RESEARCH) and a **Quality Assessment**.

## Rules
- **Verify Every Claim:** If a research document says "File X does Y", you must verify it before approving the research.
- **Actionable Takeaways:** Research without a "next step" or recommendation is a HIGH-severity failure.
- **Cite the Code:** All technical findings must reference specific files and, where possible, line ranges.
- **Stop Early:** Do not force 5 stages if convergence is reached sooner.

## References
- **Templates:** Use `references/templates.md` for the exact output format of each pass and the final report.
- **Criteria:** See `references/criteria.md` for detailed convergence rules and issue severity definitions.


---

## Reference: criteria.md

# Research Review Criteria

Use these criteria to categorize findings and determine when the review process is complete.

## Issue Severity Definitions

| Severity | Criteria | Example Findings |
| :--- | :--- | :--- |
| **CRITICAL** | Factually wrong or misleading. Claims made about the codebase or external APIs that are false. | Incorrect architectural claim, broken code example, citation that doesn't support the claim. |
| **HIGH** | Significant gaps in analysis or logic. Conclusions that do not follow from findings. | Unanswered research question, missing trade-off analysis, no actionable recommendation. |
| **MEDIUM** | Could be clearer, more complete, or more organized. | Vague terminology, inconsistent formatting, redundant sections, minor depth gaps. |
| **LOW** | Minor improvements or metadata gaps. | Typos, outdated minor library versions, missing cross-references. |

## Convergence Criteria

**CONVERGED** if:
- No new **CRITICAL** issues were found in the current pass AND
- The number of new issues found is less than 10% compared to the previous pass AND
- The estimated false positive rate is below 20%.

**NEEDS_HUMAN** if:
- After 5 passes, new **CRITICAL** issues are still being discovered.
- The false positive rate exceeds 30%.
- A fundamental disagreement on methodology or problem framing is identified.

## Pass Focus Checklist

### Pass 1: Accuracy & Sources
- [ ] Are all claims backed by code references or citations?
- [ ] Are the cited sources credible and recent?
- [ ] Are technical details factually correct?

### Pass 2: Completeness & Scope
- [ ] Are all initial research questions answered?
- [ ] Are there obvious related topics that were ignored?
- [ ] Is the depth of analysis appropriate for the subject?

### Pass 3: Clarity & Structure
- [ ] Does the document flow logically from findings to conclusions?
- [ ] Are all technical terms and jargon defined?
- [ ] Is the terminology consistent throughout?

### Pass 4: Actionability & Conclusions
- [ ] Are the takeaways and recommendations clear?
- [ ] Are the trade-offs of proposed solutions articulated?
- [ ] Is there implementable guidance for the next steps?

### Pass 5: Integration & Context
- [ ] Does this research contradict established project decisions?
- [ ] Are there connections to related specs and codebase patterns?
- [ ] Does it provide clear guidance for decision-making?


---

## Reference: templates.md

# Research Review Templates

Use these templates to provide a structured, high-signal report for each pass and the final verdict.

## Pass Output Template

Use this format for reporting results from any of the five passes.

```markdown
### PASS [N]: [Focus Area]

#### Issues Found:
[ID] [CRITICAL|HIGH|MEDIUM|LOW] - [Section/Paragraph]
**Description:** [What's inaccurate, incomplete, or ambiguous]
**Evidence:** [Why this is a problem - cite source or codebase]
**Recommendation:** [How to improve with specific research or fix]

[ID] ...
```

## Convergence Check Template

Use this format after each pass (starting with Pass 2).

```markdown
**Convergence Check After Pass [N]:**

1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]

**Status:** [CONVERGED | ITERATE | NEEDS_HUMAN]
```

## Final Report Template

After convergence or completing all 5 passes, provide this summary.

```markdown
# Research Review Final Report

**Research:** [path/to/research.md] | **Convergence:** Pass [N]

## Summary Table
| Severity | Count | Key Focus |
| :--- | :--- | :--- |
| **CRITICAL** | [count] | Factual Accuracy / Evidence |
| **HIGH** | [count] | Analysis Gaps / Conclusions |
| **MEDIUM** | [count] | Actionability / Clarity |
| **LOW** | [count] | Metadata / Flow |

## Research Quality Assessment
- **Accuracy**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Completeness**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Actionability**: [Excellent|Good|Fair|Poor] - [brief comment]
- **Clarity**: [Excellent|Good|Fair|Poor] - [brief comment]

## Top 3 Critical Findings
1. **[ID] [Description]** - [Section]
   *   **Impact:** [Why this leads to bad decisions or is factually wrong]
   *   **Fix:** [Specific actionable step]

2. **[ID] ...**

## Recommended Next Actions
1. [Action 1 - specific and actionable]
2. [Action 2 - specific and actionable]
3. [Action 3 - specific and actionable]

## Verdict: [READY | NEEDS_REVISION | NEEDS_MORE_RESEARCH]
**Rationale:** [1-2 sentences explaining the verdict based on evidence quality]
```


---