literature-review

name	literature-review
description	Coordinate comprehensive literature reviews on any research topic in philosophy. Manages 6-phase workflow including domain decomposition, literature search, and synthesis. Use proactively when user requests a literature review.
allowed-tools	Bash, Read, Write, Grep, Glob, Edit

Literature Review Workflow

Overview

This skill coordinates the production of a focused, insight-driven, rigorous, and accurate literature review for philosophy research proposals. The skill coordinates specialized subagents using the Task tool to execute a structured 6-phase workflow.

Critical: Task List Management

ALWAYS maintain a todo list and a task-progress.md file to enable resume across conversations.

Once the review directory reviews/[project-short-name]/ is established (Phase 1, step 7), create the tracker at reviews/[project-short-name]/task-progress.md. The first setup steps of Phase 1 (environment check, resume detection, mode choice) run untracked because the review directory does not exist yet. The tracker template:

# Literature Review Progress Tracker

**Research Topic**: [topic]
**Started**: [timestamp]
**Last Updated**: [timestamp]

## Progress Status

- [ ] Phase 1: Verify environment and determine execution mode
- [ ] Phase 2: Structure literature review domains
- [ ] Phase 3: Research [N] domains in parallel
- [ ] Phase 4: Outline synthesis review across domains
- [ ] Phase 5: Write review for each section in parallel
- [ ] Phase 6: Assemble final review files and move intermediate files

## Completed Tasks

[timestamp] Phase 1: Created `lit-review-plan.md` ([N] domains)

## Current Task

[Current phase and task]

## Next Steps

[Numbered list of next actions]

Update task-progress.md after EVERY completed phase in the workflow.

Workflow Architecture

Strictly follow this workflow consisting of six distinct phases:

1. Verify environment and determine execution mode
2. Structure literature review domains (Task tool: literature-review-planner agent)
3. Research domains in parallel (Task tool: domain-literature-researcher agents)
4. Outline synthesis review across domains (Task tool: synthesis-planner agent)
5. Write review for each section in parallel (Task tool: synthesis-writer agent)
6. Assemble final review files and move intermediate files

Advance only to a subsequent phase after completing the current phase.

Shared conventions: See conventions.md for BibTeX format, UTF-8 encoding, and citation style.

Task Tool Usage

Invoke subagents using the Task tool with these parameters:

• subagent_type: The agent name (e.g., "literature-review-planner")
• prompt: The instructions for the agent (include working directory and output filename)
• description: Short description (3-5 words)

Do NOT use run_in_background. Foreground execution streams status updates to the user. Parallel execution is achieved by including multiple Task calls in a single message.

Do NOT read agent definition files before invoking them. Agent definitions are for the system, not for you to read.

---

Phase 1: Verify Environment and Determine Execution Mode

This phase validates conditions for subsequent phases to function.

1. Check if file .claude/CLAUDE.local.md contains instructions about environment setup. Follow these instructions for environment verification and all phases in the literature review workflow.

2. Run the environment verification check:

   $PYTHON .claude/skills/philosophy-research/scripts/check_setup.py --json
   

3. Parse the JSON output and check the status field:

   • If status is "ok": Proceed to step 5
   • If status is "error": ABORT IMMEDIATELY with clear instructions

4. If environment check fails, inform the user:

   Environment verification failed. Cannot proceed with literature review.
   
   See GETTING_STARTED.md on how to set up the environment.
   

Why this matters: If the environment isn't configured, the philosophy-research skill scripts used by the domain researchers will fail, causing agents to fall back to unstructured web searches, undermining review quality.

5. Check for an active review pointer and determine resume point:

   Check reviews/.active-review to find the review directory:

   • If reviews/.active-review exists → read the path from it (e.g., reviews/epistemic-autonomy-ai), use that as the working directory, and check file state below
   • If reviews/.active-review does NOT exist → this is a fresh review, proceed to step 6 (If you suspect an orphaned review from a previous interruption, scan reviews/*/task-progress.md to locate it.)

   Resume logic (check files in the review directory, in order):

   1. If literature-review-[project-name].md exists -> Workflow complete, inform user
   
   2. If synthesis-section-*.md files exist:
      - Count existing section files
      - Check synthesis-outline.md for total sections expected
      - If all sections exist -> Resume at Phase 6 (assembly)
      - If some sections missing -> Resume Phase 5 for missing sections only
   
   3. If synthesis-outline.md exists -> Resume at Phase 5
   
   4. If literature-domain-*.bib files exist:
      - Count existing domain files
      - Check lit-review-plan.md for total domains expected
      - If all domains exist -> Resume at Phase 4
      - If some domains missing -> Resume Phase 3 for missing domains only
   
   5. If lit-review-plan.md exists -> Resume at Phase 3
   
   6. If task-progress.md exists but no other files -> Resume at Phase 2
   
   7. Otherwise -> Treat as fresh review (proceed to step 6)
   

   Output: "Resuming from Phase [N]: [phase name]..."

   CRITICAL: When resuming Phase 3 or Phase 5 with partial completion, only invoke agents for MISSING files. Do not re-run completed work.

6. Offer user choice of execution mode:

   • Full Autopilot: Execute all phases automatically without pausing for feedback between phases. Bash permissions are pre-configured in settings.json so no approval prompts should appear.
   • Human-in-the-Loop: Phase-by-phase with feedback

7. Create working directory and write the active-review pointer:

   mkdir -p reviews/[project-short-name]
   echo "reviews/[project-short-name]" > reviews/.active-review
   

   Use a short, descriptive name (e.g., epistemic-autonomy-ai, mechanistic-interp).

   Then create the progress tracker inside the review directory (see the template in "Critical: Task List Management" above): reviews/[project-short-name]/task-progress.md

   Guard — name collision: If reviews/[project-short-name]/literature-review-[project-short-name].md already exists, warn the user that a completed review occupies that path. Ask whether to overwrite or choose a different name (e.g., append -2).

   Guard — concurrent review: If reviews/.active-review already exists and points to a different directory, warn the user that another review appears to be in progress. Ask whether to abandon the previous review or resume it instead.

   CRITICAL: All subsequent file operations happen in reviews/[project-short-name]/. Pass this path to ALL subagents.

---

Phase 2: Structure Literature Review Domains

1. Receive and review research idea from user. If you require further information, clarification or direction, ask the user.
2. Use Task tool to invoke literature-review-planner agent with research idea:
   • subagent_type: "literature-review-planner"
   • prompt: Include full research idea, requirements, AND working directory path
   • Example prompt: "Research idea: [idea]. Working directory: reviews/[project-name]/. Write output to reviews/[project-name]/lit-review-plan.md"
3. Wait for literature-review-planner agent to structure the literature review into domains
4. Read reviews/[project-name]/lit-review-plan.md (generated by agent)
5. Get user feedback on plan, iterate if needed using Task tool to invoke literature-review-planner agent again
6. Update task-progress.md

Never advance to a next step in this phase before completing the current step.

---

Phase 3: Research Literature in Domains

1. Identify and enumerate N domains (typically 3-8) listed in reviews/[project-name]/lit-review-plan.md
2. Launch all N domain researchers in parallel using a single message with multiple Task tool calls:
   • subagent_type: "domain-literature-researcher"
   • prompt: Include domain focus, key questions, research idea, working directory, AND output filename
   • Example prompt for domain 1: "Domain: [name]. Focus: [focus]. Key questions: [questions]. Research idea: [idea]. Working directory: reviews/[project-name]/. Write output to: reviews/[project-name]/literature-domain-1.bib"
   • description: "Domain [N]: [domain name]"
   • CRITICAL: Include ALL Task tool calls in a single message to enable parallel execution
3. Wait for all N agents to finish using TaskOutput (block until complete). Expected outputs: reviews/[project-name]/literature-domain-1.bib through literature-domain-N.bib. Update task-progress.md after all domains complete
4. Collect source issues: Note any "Source issues:" reported by domain researchers for the final summary

Never advance to Phase 4 before all domain researchers have completed.

---

Phase 4: Outline Synthesis Review Across Domains

1. Use Task tool to invoke synthesis-planner agent:
   • subagent_type: "synthesis-planner"
   • prompt: Include research idea, working directory, list of BibTeX files, and original plan path
   • Example prompt: "Research idea: [idea]. Working directory: reviews/[project-name]/. BibTeX files: literature-domain-1.bib through literature-domain-N.bib. Plan: lit-review-plan.md. Write output to: reviews/[project-name]/synthesis-outline.md"
   • description: "Plan synthesis structure"
2. Planner reads BibTeX files and creates tight outline
3. Wait for agent to finish using TaskOutput. Expected output: reviews/[project-name]/synthesis-outline.md (800-1500 words outline for a 3000-4000 word review)
4. Update task-progress.md

Never advance to a next step in this phase before completing the current step.

---

Phase 5: Write Review Sections in Parallel

1. Read synthesis outline reviews/[project-name]/synthesis-outline.md to identify sections
2. For each section: identify relevant BibTeX .bib files from the outline
3. Launch all N synthesis writers in parallel using a single message with multiple Task tool calls:
   • subagent_type: "synthesis-writer"
   • prompt: Include working directory, section heading (exactly as it appears in the outline), outline path, and relevant BibTeX files
   • CRITICAL: Use the outline's own section headings verbatim (e.g., "## Introduction", "## Section 1: The Charge"). Do NOT renumber sections linearly (1, 2, 3...) if the outline uses different numbering. Writers follow the outline's numbering, so mismatches cause them to write the wrong section or produce inconsistent headings. Output filenames should be numbered sequentially (synthesis-section-1.md through synthesis-section-N.md) for correct assembly order.
   • Example prompt: "Working directory: reviews/[project-name]/. Write the section headed '## Introduction' from the outline. Outline: synthesis-outline.md. Relevant BibTeX files: literature-domain-1.bib, literature-domain-3.bib. Write output to: reviews/[project-name]/synthesis-section-1.md"
   • description: "Write section [N]: [section name]"
   • CRITICAL: Include ALL Task tool calls in a single message to enable parallel execution
4. Wait for all N agents to finish using TaskOutput (block until complete). Expected outputs: reviews/[project-name]/synthesis-section-1.md through synthesis-section-N.md. Update task-progress.md after all sections complete

Never advance to Phase 6 before all synthesis writers have completed.

---

Phase 6: Assemble Final Review Files and Move Intermediate Files

Working directory: reviews/[project-name]/

Expected outputs of this phase (final):

• literature-review-[project-name].md — complete review with YAML frontmatter
• literature-review-[project-name].docx — DOCX version (if pandoc is installed)
• literature-[project-name].bib — aggregated bibliography

1. Assemble final review with YAML frontmatter:

   $PYTHON .claude/skills/literature-review/scripts/assemble_review.py \
     "reviews/[project-name]/literature-review-[project-name].md" \
     --title "[Research Topic]" \
     reviews/[project-name]/synthesis-section-*.md
   

   Then use Read to verify section ordering and transitions.

2. Normalize section headings:

   $PYTHON .claude/skills/literature-review/scripts/normalize_headings.py \
     "reviews/[project-name]/literature-review-[project-name].md"
   

   The script enforces consistent numbering: ## Section N: Title for body sections, ### N.M Title for subsections. Introduction and Conclusion remain unnumbered. If the script reports errors, investigate before proceeding. Then use Read to verify the heading structure looks correct.

3. Aggregate and deduplicate all domain BibTeX files:

   Use Glob to find all literature-domain-*.bib files. Run the deduplication script to create literature-[project-name].bib:

   $PYTHON .claude/skills/literature-review/scripts/dedupe_bib.py \
     "reviews/[project-name]/literature-[project-name].bib" \
     reviews/[project-name]/literature-domain-*.bib
   

   The script will:

   • Keep the first occurrence of each citation key
   • Prefer entries with abstracts over entries without (abstract-aware merging)
   • Upgrade importance level if a later domain assigned higher importance
   • Remove INCOMPLETE flags when merged entry has an abstract
   • Deduplicate by DOI (catches same paper with different keys)
   • Log which duplicates were removed to console

4. Generate bibliography and append to final review:

   $PYTHON .claude/skills/literature-review/scripts/generate_bibliography.py \
     "reviews/[project-name]/literature-review-[project-name].md" \
     "reviews/[project-name]/literature-[project-name].bib"
   

   The script will:

   • Match cited works by surname+year proximity in the review text
   • Format references in Chicago Author-Date style from BibTeX metadata only
   • Deduplicate entries with the same DOI
   • Append (or replace) a ## References section at the end of the review

5. Lint the final markdown file:

   $PYTHON .claude/skills/literature-review/scripts/lint_md.py \
     "reviews/[project-name]/literature-review-[project-name].md"
   

   Fix any reported issues before proceeding. The References section is now in scope for linting — verify no false positives from italicized journal names, DOI URLs, or other bibliography formatting.

6. Clean up intermediate files (use absolute paths to avoid cwd issues):

   Move JSON API response files to intermediate_files/json/ for archival (allows debugging while keeping review directory clean):

   mkdir -p "reviews/[project-name]/intermediate_files/json"
   mv "reviews/[project-name]"/*.json "reviews/[project-name]/intermediate_files/json/" 2>/dev/null || true
   

   Move stray API-result files from project root (agents sometimes omit the $REVIEW_DIR/ prefix). Use targeted prefixes — never bare *.json, which could swallow unrelated files:

   find . -maxdepth 1 \( -name "philpapers_*.json" -o -name "pp_*.json" -o -name "s2_*.json" -o -name "openalex_*.json" -o -name "stage3_*.json" -o -name "arxiv_*.json" \) -exec mv {} "reviews/[project-name]/intermediate_files/json/" \;
   find . -maxdepth 1 -name "*.bib" -exec mv {} "reviews/[project-name]/intermediate_files/" \;
   

   Move remaining intermediate files and remove the active-review pointer:

   mv "reviews/[project-name]/task-progress.md" "reviews/[project-name]/lit-review-plan.md" "reviews/[project-name]/synthesis-outline.md" "reviews/[project-name]/intermediate_files/"
   mv "reviews/[project-name]/synthesis-section-"*.md "reviews/[project-name]/literature-domain-"*.bib "reviews/[project-name]/intermediate_files/"
   rm -f reviews/.active-review
   

   Safety net — move any remaining non-final files to intermediate_files/:

   for f in "reviews/[project-name]"/*; do
     case "$(basename "$f")" in
       literature-review-*.md|literature-review-*.docx|literature-*.bib|intermediate_files) ;;
       *) mv "$f" "reviews/[project-name]/intermediate_files/" 2>/dev/null || true ;;
     esac
   done
   

   Stray directories — agents sometimes create directories at the project root by mistake. Remove any empty directories that match the review topic:

   find . -maxdepth 1 -type d -empty -not -name '.*' -not -name 'reviews' -not -name 'tests' -not -name 'docs' -exec rmdir {} \;
   

   Note: Do NOT use cd to change directories. Always use paths relative to the repo root or absolute paths to prevent working directory mismatches in subsequent commands.

After cleanup (final state):

reviews/[project-name]/
├── literature-review-[project-name].md    # Final review (markdown)
├── literature-review-[project-name].docx  # Final review (if pandoc available)
├── literature-[project-name].bib          # Aggregated bibliography
└── intermediate_files/           # Workflow artifacts
    ├── json/                     # JSON files archived here
    │   ├── s2_results.json
    │   ├── openalex_results.json
    │   └── stage3_*.json
    ├── task-progress.md
    ├── lit-review-plan.md
    ├── synthesis-outline.md
    ├── synthesis-section-1.md
    ├── synthesis-section-N.md
    ├── literature-domain-1.bib
    ├── literature-domain-N.bib
    └── [other intermediate files, if they exist]

7. Report source issues: If any domain researchers reported source issues (API errors, partial results), output a summary:

   ⚠️ Source issues during literature search:
   - Domain [name]: [source]: [issue]
   

   If no issues: omit this message.

8. Optional: Convert to DOCX (if pandoc is installed):

   if command -v pandoc &> /dev/null; then
     pandoc "reviews/[project-name]/literature-review-[project-name].md" \
       --from markdown \
       --to docx \
       --output "reviews/[project-name]/literature-review-[project-name].docx" \
       --citeproc \
       --bibliography="reviews/[project-name]/literature-[project-name].bib" \
       && echo "Converted to DOCX: literature-review-[project-name].docx"
   else
     echo "Pandoc not installed, skipping DOCX conversion"
   fi
   

   Important: Use paths relative to repo root (not bare filenames). Do NOT use &&/|| chaining for this check, as Pandoc errors would trigger the wrong fallback message.

---

Error Handling

Too few papers (<5 per domain): Re-invoke domain-literature-researcher agents with broader terms

Synthesis thin: Request expansion from synthesis-planner agent, or loop back to planning literature-review-planner agent

API failures: Domain researchers report "Source issues:" in their completion message. Collect these for the final summary. Re-run domains with critical failures if needed.

---

Quality Standards

• Academic rigor: proper citations, balanced coverage
• Relevance: clear connection to research proposal
• Comprehensiveness: no major positions missed
• Citation integrity: ONLY real papers found via skill scripts (structured API searches)
• Citation format: (Author Year) in-text, Chicago-style bibliography

---

Status Updates

Output status updates directly as text (visible to user in real-time):

Event	Status Format
Workflow start	Starting literature review: [topic]
Environment check	Phase 1/6: Verifying environment and determining execution mode...
Environment OK	Environment OK. Proceeding...
Environment FAIL	Environment verification failed. [details]
Phase transition	Phase 2/6: Structuring literature review into domains
Phase transition	Phase 3/6: Researching literature in [N] domains (parallel)
Phase transition	Phase 4/6: Outlining synthesis review across domains
Phase transition	Phase 5/6: Writing [N] review sections (parallel)
Agent launch (parallel)	Launching [N] domain researchers in parallel...
Agent completion	Domain [N] complete: literature-domain-[N].bib ([number of sources included] sources)
Phase completion	Phase [N] complete: [summary]
Assembly	Assembling final review with YAML frontmatter...
BibTeX aggregation	Aggregating BibTeX files -> literature-[project-name].bib
Cleanup	Moving intermediate files -> intermediate_files/
DOCX conversion	Converted to DOCX: literature-review-[project-name].docx
Workflow complete	Literature review complete: literature-review-[project-name].md ([wordcount])
Source issues (if any)	⚠️ Source issues: [aggregated list from domain researchers]

---

Success Metrics

• Focused, rigorous, insight-driven review (3000-8000 words)
• Resumable (task-progress.md enables continuity)
• Valid BibTeX files