lit-ops

# LitR-skills-and-rules -- Literature Review Pipeline

This repository contains a suite of specialized agent skills and subagents designed to conduct rigorous, systematic literature reviews based on the framework from *The Literature Review: Six Steps to Success* (Machi & McEvoy).

## Core Philosophy

A literature review is a written document that presents a logically argued case founded on a comprehensive understanding of the current state of knowledge about a topic of study. It is not a simple summary of past work. 

**Rules of Engagement:**
1. **Argumentation over Summarization**: Never simply summarize texts. Always extract claims, evidence, and warrants to build an argument.
2. **Methodological Rigor**: Follow the 6-step process sequentially. Do not jump to searching literature before the topic is clearly defined.
3. **Reflective Oversight**: Frequently pause to ask: What did I do? How did it work? What do I do next?
4. **Avoid Fallacies**: Guard against jumping to conclusions, emotional reasoning, misplaced causality, and other logical fallacies.
5. **Eliminate Academic Slop**: When generating text, evaluating claims, or reviewing drafts, strictly adhere to the `academic-slop` guidelines. Remove predictable AI writing patterns, padding, vague significance statements, and methodology theater. Ensure all claims are precise, verifiable, and written with authority.

## The 6-Step Pipeline

The process is divided into six specialized skills/subagents:
1. `lit-topic-formulator` (Step 1: Select and Define a Topic)
2. `lit-argument-developer` (Step 2: Develop the Tools of Argumentation)
3. `lit-discovery-strategist` (Step 3: Search the Literature)
4. `lit-survey-synthesizer` (Step 4: Survey the Literature)
5. `lit-critique-auditor` (Step 5: Critique the Literature)
6. `lit-review-writer` (Step 6: Write the Review)

There is also a `lit-review-coordinator` to manage the overall pipeline and handoffs between these subagents.

## Data Artifacts

- **Topic Statement**: The current formulation of the research query.
- **Literature Survey Spreadsheet**: A catalog of evidence, claims, and warrants.
- **Subject Memoranda**: Notes synthesizing understanding of specific concepts.
- **Argument Maps**: Visual or outlined mappings of simple and complex arguments.

## Academic Slop — Mandatory Writing Standard

**Every subagent in this pipeline MUST enforce the `academic-slop` standards when generating, evaluating, or revising any text.** This is not optional. The guidelines target:
- Vague significance, hedging abuse, throat-clearing, metaphor abuse, methodology theater, filler transitions, novelty overstatement, and redundant pairs.
- Structural anti-patterns (gap-contribution template, laundry-list objectives, builds-on stacks, weak contrasts, recursive abstracts, over-qualified claims, methodological overdescription, significance paragraph template, citation padding, to-the-best-of-our-knowledge hedge).

### Enforcement Points
Academic slop checks apply at these stages:
1. **Step 2 (Argument Developer)**: When the user formulates claims, check that each claim is precise — no vague significance, no hedging abuse.
2. **Step 4 (Survey Synthesizer)**: When synthesizing data into claims and the Discovery Argument, check every claim against the banned phrases list.
3. **Step 5 (Critique Auditor)**: When building the Advocacy Argument and thesis statement, run the full Quick Checks and score against the 5-dimension rubric.
4. **Step 6 (Review Writer)**: Before delivering any draft, run the full academic-slop audit: Quick Checks, scoring rubric (reject below 35/50), structural anti-pattern scan, and phrase replacement.

### Scoring Rubric (from academic-slop)
Rate every draft 1-10 on each dimension:

| Dimension | Question |
|-----------|----------|
| Precision | Are claims specific, or vague? |
| Economy | Does every sentence earn its space? |
| Authority | Does the evidence speak, or does hedging speak? |
| Originality | Are novelty claims verifiable? |
| Density | Can any sentence be cut without loss? |

**Below 35/50: revise before delivering to the user.**

### Academic Mode Adjustments
These standard academic-slop rules are **relaxed** in scholarly writing:
- **Passive voice in Methods**: Allowed where the agent is irrelevant ("The solution was heated to 90°C").
- **Wh- sentence starters**: Allowed as section motivators ("Why does this matter?").
- **Em-dashes**: Allowed for parenthetical technical clarifications.
- **Meta-joiners**: Allowed sparingly for document navigation ("Section 4 describes the methodology").
- **"This study" / "This research"**: Allowed as subjects when they are the actual actor.

## Agent Behavior — Medium Autonomy

**All subagents operate under medium autonomy:**
- Work autonomously within a task (e.g., extract all claims from a paper without asking).
- At every major decision point, STOP and present options to the user. Ask the user to choose.
- Examples of decision points: "I found 3 possible interpretations of this paper's main claim — which one fits our argument?", "These two papers contradict each other on X — how should we handle this?", "The data supports two possible thesis directions — which do you prefer?"
- **NEVER proceed past a decision point without the user's explicit approval.**
- When the agent cannot determine the answer to a question, it MUST ask the user rather than guessing.

## Input Formats

The pipeline accepts references in any of these formats:
- **PDF files** in a designated folder (e.g., `references/`)
- **URLs** to papers (PubMed, arXiv, DOIs, journal sites)
- **Pasted text** (abstracts, excerpts, full papers)
- **Bibliography files** (if supported by your tools)

The `lit-discovery-strategist` can also actively search databases (PubMed, arXiv, EuropePMC, OpenAlex) to find additional references.

## Output Format

All outputs are **markdown**. The pipeline is **format-agnostic** — it produces literature reviews suitable for:
- Thesis/dissertation chapters
- Journal manuscript literature review sections
- Standalone review articles / survey papers
- Academic book chapters

The user specifies the target format at the start, and the `lit-review-writer` adapts structure and length accordingly.