version: "1.0.1" 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.

Objectives (priority order)

1. Accurate — Only cite verified papers; never fabricate references
2. Comprehensive — Cover all major positions and key debates
3. Rigorous and concise — Analytical depth, tight prose; balanced presentation of positions
4. Reproducible — Structured workflow, standard BibTeX output, Chicago author-date citations

Quality over speed; use full context as needed (do not optimize for token savings).

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 $PHILLIT_ROOT/docs/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 with the plugin prefix (e.g., "phillit:literature-review-planner")
• prompt: The instructions for the agent (include working directory and output filename)
• description: Short description (3-5 words)
• run_in_background: Always false (see below)

Pass `run_in_background: false` explicitly on every subagent dispatch. Foreground execution streams status updates to the user.

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

Do NOT use `cd` in any Bash call across all phases. Always use paths relative to the repo root or absolute paths — a cd changes the working directory for later commands too, which is how stray directories and misplaced files happen.

Phase 1: Verify Environment and Determine Execution Mode

This phase validates conditions for subsequent phases to function.

Setup check: If the current directory has no .phillit/ marker, PhilLit has not been set up here — offer to run /phillit:setup (a quick one-time step) before continuing.

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

1. Run the environment verification check:

``bash bash "$PHILLIT_ROOT/bin/phillit-run" skills/philosophy-research/scripts/check_setup.py --json ``

1. 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

1. If environment check fails, inform the user:

``` Environment verification failed. Cannot proceed with literature review.

Run /phillit:setup in this directory, then make sure uv and jq are installed and your API keys are set (in .env or your 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.

1. 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

1. 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

1. If synthesis-outline.md exists -> Resume at Phase 5

1. 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

1. If lit-review-plan.md exists -> Resume at Phase 3

1. If task-progress.md exists but no other files -> Resume at Phase 2

1. 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.

1. Offer user choice of execution mode:

• Full Autopilot: Execute all phases automatically without pausing for feedback between phases. With /phillit:setup having merged PhilLit's permission rules into this directory's .claude/settings.json, no approval prompts should appear.
• Human-in-the-Loop: Phase-by-phase with feedback

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

``bash 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: "phillit: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"

1. Wait for literature-review-planner agent to structure the literature review into domains
2. Read reviews/[project-name]/lit-review-plan.md (generated by agent)
3. Get user feedback on plan, iterate if needed using Task tool to invoke literature-review-planner agent again
4. 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: "phillit: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
• CRITICAL — foreground, never background: Set run_in_background: false (or omit it) on EVERY call.

1. With foreground dispatch (run_in_background: false), all N calls in the single message block until every agent finishes and their results return inline — there is no separate wait step. Expected outputs: reviews/[project-name]/literature-domain-1.bib through literature-domain-N.bib. Update task-progress.md after all domains complete
2. Collect source issues: Note any "Source issues:" reported by domain researchers for the final summary
3. Evidence barrier (REQUIRED, after all researchers complete): run

``bash bash "$PHILLIT_ROOT/bin/phillit-run" skills/literature-review/scripts/evidence_barrier.py "reviews/[project-name]" --domains N ``

CRITICAL — foreground, never background: run this command in the foreground (never set run_in_background) with the maximum Bash timeout (600000 ms) — rate-limited encyclopedia fetches can take 10+ minutes on a cold cache. A backgrounded barrier can be orphaned when the session ends, leaving every entry unstamped (all EVIDENCE-NONE). If the tool still moves the command to the background at its timeout ceiling, WAIT for its completion notification — do not start Phase 4 until intermediate_files/json/evidence_report.json exists with status complete or degraded.

The barrier validates every domain's outputs, mechanically acquires SEP/IEP citation context for entries lacking attested content evidence, writes intermediate_files/json/evidence_report.json, and stamps every entry with an EVIDENCE-* citability tier. If it exits nonzero, do NOT proceed to Phase 4 — report the failure to the user and stop. If the summary reports "status": "degraded", continue but include the degraded domains in the final summary.

The summary's venue_vetting key reports the venue check: it flags entries whose journal is barely indexed. "status": "skipped" means no OPENALEX_API_KEY was set — mention it once in the final summary so the user knows the check did not run; it is optional and free to obtain. Any other non-complete status means the check ran but did not finish, or could not run at all — surface that once too, reading why from intermediate_files/json/evidence_report.json's venue_vetting object (the printed summary carries the status but not the explanation): for partial/budget_exhausted/skipped it is the reason string; for error it is the error string instead (no reason key on that path); not-run means the object is absent from the report entirely, which only happens alongside a barrier failure already caught by the nonzero-exit rule above.

Never advance to Phase 4 before all domain researchers have completed AND the evidence barrier has exited zero.

Phase 4: Outline Synthesis Review Across Domains

1. Use Task tool to invoke synthesis-planner agent:

• subagent_type: "phillit: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"

1. Planner reads BibTeX files and creates tight outline
2. With foreground dispatch (run_in_background: false), the call blocks until the agent finishes and its result returns inline. Expected output: reviews/[project-name]/synthesis-outline.md (800-1500 words outline for a 3000-4000 word review)
3. 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: "phillit: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
• CRITICAL — foreground, never background: Set run_in_background: false (or omit it) on EVERY call.

1. With foreground dispatch (run_in_background: false), all N calls in the single message block until every agent finishes and their results return inline — there is no separate wait step. 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:

``bash bash "$PHILLIT_ROOT/bin/phillit-run" 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.

1. Normalize section headings:

``bash bash "$PHILLIT_ROOT/bin/phillit-run" 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.

1. 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:

``bash bash "$PHILLIT_ROOT/bin/phillit-run" skills/literature-review/scripts/dedupe_bib.py \ "reviews/[project-name]/literature-[project-name].bib" \ --evidence-report "reviews/[project-name]/intermediate_files/json/evidence_report.json" \ 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
• Re-stamp each merged entry's EVIDENCE-* tier attestation-aware from the evidence report
• Deduplicate by DOI (catches same paper with different keys)
• Log which duplicates were removed to console

1. Generate bibliography and append to final review:

``bash bash "$PHILLIT_ROOT/bin/phillit-run" 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

1. Lint the final markdown file:

``bash bash "$PHILLIT_ROOT/bin/phillit-run" 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.

The linter also verifies every in-text author-year citation resolves to a References entry (ERROR + nonzero exit otherwise). An unresolved citation means the References generator dropped a cited work — fix the body/bib author spelling divergence (or the bib entry) and re-run step 4; never delete the citation to silence the check. This applies to primary and legal sources too (statutes, regulations, treaties, reports): they are cited like any other work, so they need a bib entry — the sanctioned remedy for an unresolved "(GDPR 2016)" is adding the @misc entry, not removing the citation. The check only runs when the file has an exact ## References heading — confirm the lint output does NOT say "citation-check: ... skipped" on a finished review; that message means the check never ran, not that it passed.

1. Evidence checker (telemetry): run

``bash bash "$PHILLIT_ROOT/bin/phillit-run" skills/literature-review/scripts/check_evidence.py "reviews/[project-name]/literature-review-[project-name].md" "reviews/[project-name]/literature-[project-name].bib" ``

Include every CHECK line verbatim in the final summary (they are telemetry, not blockers) — never summarize, count, or gloss them: a live run's summary once reported four findings as "two minor notes", which hid a do-not-cite violation from the user.

1. Sanitize the delivered bibliography (engine-internal tier tokens must not ship):

``bash bash "$PHILLIT_ROOT/bin/phillit-run" skills/literature-review/scripts/sanitize_bib.py "reviews/[project-name]/literature-[project-name].bib" ``

1. 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): ``bash 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: ``bash 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 clear the active-review pointer. Archive the pointer with mv (not rm) — moving it into the completed review's intermediate_files/ clears it from reviews/ without triggering the rm permission prompt: ``bash 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/" mv reviews/.active-review "reviews/[project-name]/intermediate_files/.completed-review" 2>/dev/null || true ``

Safety net — move any remaining non-final files to intermediate_files/: ``bash 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: ``bash find . -maxdepth 1 -type d -empty -not -name '.*' -not -name 'reviews' -not -name 'tests' -not -name 'docs' -exec rmdir {} \; ``

Note: Never cd here either — see the rule under Task Tool Usage above.

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_<domain>_results.json
    │   ├── openalex_<domain>_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]

1. 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.

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

``bash 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):

Success Metrics

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