Use SQA for literature-report skill

plugins/asta-preview/skills/literature-report/SKILL.md

@@ -2,14 +2,15 @@
 name: Asta Literature Reports
 description: Create or update literature reviews/reports. Use whenever you need to research, summarize, or synthesize the literature.
 allowed-tools:
+  - Bash(asta literature find *)
+  - Bash(asta literature report *)
   - Read(.asta/literature/*)
   - TaskOutput
-  - Bash(jq *)
 ---
 
 # Literature Reports
 
-Create or update literature reviews/reports as markdown documents with citations.
+Generate comprehensive literature reports by finding relevant papers and synthesizing them into a structured written report with citations.
 
 ## Finding Papers
 
@@ -23,6 +24,35 @@ Create or update literature reviews/reports as markdown documents with citations
 - **When updating an existing report**, read it first to understand the current structure and content.
 - **When using Find Literature results**, go through ALL highly relevant papers — extract relevance criteria, snippets, and citation contexts from each.
 
+**If the user provides an existing paper-finder results file:**
+- Skip to step 3, using that file as `-i`
+
+**If no existing results file:**
+- Proceed to step 2
+
+### 2. Find Papers
+
+```bash
+asta literature find 'query' --timeout 300 -o .asta/literature/find/YYYY-MM-DD-topic-slug.json
+```
+
+Note the output path from the command.
+
+### 3. Generate the Report
+
+```bash
+asta literature report \
+  -i .asta/literature/find/YYYY-MM-DD-topic-slug.json \
+  -o .asta/literature/report/YYYY-MM-DD-topic-slug.md
+```
+
+The command prints progress to stderr and the report path when done.
+
+### 4. Confirm and Share
+
+- Read the saved report file and share the key findings with the user
+- Tell the user the file path so they can open it
+
 ## Citation Conventions
 
 **YAML frontmatter** — required for citation resolution:
@@ -46,3 +76,9 @@ Generate a BibTeX entry from the result. Conventions:
 - **Append** to the `.bib` — never rewrite existing entries.
 
 **Verification**: Use the **Preview** skill to render and verify all citations resolve.
+
+## Error Handling
+
+- **Authentication error**: Run `asta auth login` and retry
+- **Timeout**: Pass a larger `--timeout` value (default is 360s)
+- **No papers found**: Suggest refining the query and re-running `asta literature find`

skills/literature-report/SKILL.md

@@ -2,47 +2,58 @@
 name: Asta Literature Reports
 description: Create or update literature reviews/reports. Use whenever you need to research, summarize, or synthesize the literature.
 allowed-tools:
+  - Bash(asta literature find *)
+  - Bash(asta literature report *)
+  - Bash(asta papers get *)
+  - Bash(jq *)
+  - Bash(mkdir *)
   - Read(.asta/literature/*)
+  - Read(*)
   - TaskOutput
-  - Bash(jq *)
 ---
 
-# Literature Reports
-
-Create or update literature reviews/reports as markdown documents with citations.
+<objective>
+Generate comprehensive literature reports by finding relevant papers and synthesizing them into structured written reports with citations. Route to the correct workflow based on what the user already has.
+</objective>
 
-## Finding Papers
+<principles>
+- **Check before searching.** Always check `.asta/literature/find/` for existing search results before running new searches.
+- **Reports are user-facing.** New reports go in user-visible locations (e.g., `docs/`, project root), never inside `.asta/`.
+- **Read before updating.** When updating an existing report, read it first to understand structure and content.
+- **Exhaust the evidence.** When using find-literature results, go through ALL highly relevant papers — extract relevance criteria, snippets, and citation contexts from each.
+- **Delegate search to the right tool.** Use the **Find Literature** skill for comprehensive searches. Use the **Semantic Scholar Lookup** skill for targeted queries (specific papers, citations, author searches).
+</principles>
 
-- Check `.asta/literature/find/` for existing search results before running new searches.
-- Use the **Find Literature** skill for comprehensive searches and for the result schema and jq access patterns.
-- Use the **Semantic Scholar Lookup** skill for targeted queries: specific papers, citations, and author searches.
+<routing>
+Determine which workflow to follow based on what the user has:
 
-## Workflow Guidance
+**Route A — No papers yet** → The user wants a literature report but hasn't searched yet.
+Read `workflows/find-and-report.md`.
 
-- **Identify or create the report file first**. Check if there's an existing report to update. New reports go in user-visible locations (e.g., `docs/`), not inside `.asta/`.
-- **When updating an existing report**, read it first to understand the current structure and content.
-- **When using Find Literature results**, go through ALL highly relevant papers — extract relevance criteria, snippets, and citation contexts from each.
+**Route B — Has a find-literature result** → The user provides or references an existing `.json` results file from `asta literature find`.
+Read `workflows/generate-report.md`.
 
-## Citation Conventions
-
-**YAML frontmatter** — required for citation resolution:
-```yaml
----
-bibliography: ../references.bib
----
-```
+**Route C — Has papers in another form** → The user has a collection of papers as a list of titles, DOIs, arXiv IDs, URLs, a BibTeX file, or any non-find-literature format.
+Read `workflows/convert-and-report.md`.
 
-**Citations**: Use `[@key]` format. Every key must exist in the `.bib` file — unresolved keys won't render.
+**Route D — Merge into existing report** → The user has an existing report and wants to incorporate new papers or findings into it.
+Read `workflows/merge-report.md`.
 
-**Adding papers to `.bib`**: As you cite a paper, fetch its metadata and append a BibTeX entry:
+When the user's intent maps to multiple routes (e.g., "find papers on X and add them to my existing report"), chain the relevant workflows in sequence.
+</routing>
 
-```bash
-asta papers get CorpusId:<id> --fields title,authors,year,venue,externalIds,journal,publicationDate
-```
+<file_conventions>
+**Search results:** `.asta/literature/find/YYYY-MM-DD-topic-slug.json`
+**Generated reports:** `.asta/literature/report/YYYY-MM-DD-topic-slug.md`
+**User-facing reports:** User-specified path or `docs/` directory
+</file_conventions>
 
-Generate a BibTeX entry from the result. Conventions:
-- **Key**: `{firstAuthorSurname}{year}` lowercased, ASCII only (e.g., `wei2022`). Append a letter for conflicts (`wei2022a`).
-- **`corpus_id`**: Include `corpus_id = {<id>}` for stable identification (survives key renames).
-- **Append** to the `.bib` — never rewrite existing entries.
+<citations>
+Read `references/citation-conventions.md` when the report requires formal citations with a `.bib` file and `[@key]` references.
+</citations>
 
-**Verification**: Use the **Preview** skill to render and verify all citations resolve.
+<errors>
+- **Authentication error** → Run `asta auth login` and retry.
+- **Timeout** → Pass a larger `--timeout` value (default is 360s).
+- **No papers found** → Suggest refining the query and re-running `asta literature find`.
+</errors>

skills/literature-report/references/citation-conventions.md

@@ -0,0 +1,37 @@
+# Citation Conventions
+
+Follow these conventions when a report requires formal citations with a `.bib` file and `[@key]` Pandoc-style references.
+
+## YAML Frontmatter
+
+Every report with citations must include:
+
+```yaml
+---
+bibliography: ../references.bib
+---
+```
+
+Adjust the relative path to point to the `.bib` file from the report's location.
+
+## Citation Format
+
+Use `[@key]` inline. Every key must exist in the `.bib` file — unresolved keys won't render.
+
+## Adding Papers to the `.bib` File
+
+As you cite a paper, fetch its metadata and append a BibTeX entry:
+
+```bash
+asta papers get CorpusId:<id> --fields title,authors,year,venue,externalIds,journal,publicationDate
+```
+
+Generate a BibTeX entry from the result. Conventions:
+
+- **Key format**: `{firstAuthorSurname}{year}` lowercased, ASCII only (e.g., `wei2022`). Append a letter for conflicts (`wei2022a`, `wei2022b`).
+- **`corpus_id` field**: Always include `corpus_id = {<id>}` for stable identification (survives key renames).
+- **Append only**: Add new entries to the end of the `.bib` file. Never rewrite or remove existing entries.
+
+## Verification
+
+Use the **Preview** skill to render the report and verify all citations resolve. Unresolved `[@key]` references appear as literal text in the output — scan for any that didn't render as proper citations.

skills/literature-report/workflows/convert-and-report.md

@@ -0,0 +1,81 @@
+# Convert External Papers to Find-Literature Format
+
+Use when the user has papers in a non-standard form — titles, DOIs, arXiv IDs, URLs, a BibTeX file, CSV, or any other format — and wants a literature report from them.
+
+<process>
+
+## Step 1: Identify the papers
+
+Determine what the user has provided. Common forms:
+- A list of paper titles
+- DOIs or arXiv IDs
+- Semantic Scholar corpus IDs or URLs
+- A `.bib` file
+- A CSV or spreadsheet
+- Inline references in a document
+
+## Step 2: Resolve each paper via Semantic Scholar
+
+For each paper, look it up to get full metadata:
+
+```bash
+# By arXiv ID
+asta papers get ARXIV:2005.14165 --fields title,abstract,year,authors,venue,citationCount,corpusId
+
+# By DOI
+asta papers get DOI:10.1234/example --fields title,abstract,year,authors,venue,citationCount,corpusId
+
+# By corpus ID
+asta papers get CorpusId:12345 --fields title,abstract,year,authors,venue,citationCount,corpusId
+
+# By title search (when only title is available)
+asta papers search "exact paper title" --limit 5 --fields title,abstract,year,authors,venue,citationCount,corpusId
+```
+
+For title searches, verify the match is correct by checking authors and year.
+
+## Step 3: Build the results JSON
+
+Construct a `LiteratureSearchResult` JSON file matching the find-literature schema:
+
+```json
+{
+  "query": "<user's research topic or description>",
+  "results": [
+    {
+      "corpus_id": 12345,
+      "title": "Paper Title",
+      "abstract": "...",
+      "year": 2023,
+      "authors": [{"name": "Author Name", "authorId": "123"}],
+      "venue": "Conference Name",
+      "citation_count": 50,
+      "relevance_score": 0.9,
+      "relevance_judgement": {
+        "relevance": 9,
+        "relevanceSummary": "Brief explanation of why this paper is relevant",
+        "relevanceCriteriaJudgements": []
+      },
+      "snippets": [],
+      "citation_contexts": []
+    }
+  ]
+}
+```
+
+Key points:
+- Set `relevance_score` between 0 and 1 based on your judgement of relevance to the user's topic. If no clear ranking, use 0.8 for all.
+- The `query` field should describe the research topic, not just repeat the user's input.
+- `snippets` and `citation_contexts` will be empty since we don't have full-text access — this is fine, the report will rely on abstracts.
+
+Save to: `.asta/literature/find/YYYY-MM-DD-topic-slug.json`
+
+## Step 4: Generate the report
+
+Now follow `workflows/generate-report.md` using the converted results file.
+
+</process>
+
+<note>
+If the user has a large collection (20+ papers), consider whether `asta literature find` with a well-crafted query would produce better results than manual conversion — it provides relevance scores, snippets, and citation contexts that improve report quality.
+</note>

skills/literature-report/workflows/find-and-report.md

@@ -0,0 +1,50 @@
+# Find Papers and Generate Report
+
+Use when the user wants a literature report but has no papers yet.
+
+<process>
+
+## Step 1: Clarify the query
+
+Ask the user to describe their research topic if the request is vague. The search query can be long and complex — a well-scoped query produces better results.
+
+## Step 2: Check for existing searches
+
+```bash
+asta documents --root .asta/literature/find search --summary '<detailed query>' 2>/dev/null
+```
+If relevant results already exist, confirm with the user whether to reuse them or run a fresh search.
+
+## Step 3: Run the search
+
+Generate a slug from the topic (e.g., `transformer-efficiency`).
+
+```bash
+asta literature find '<detailed query>' --timeout 300 -o .asta/literature/find/YYYY-MM-DD-topic-slug.json
+```
+
+Run this in the background — it takes 30–60 seconds. When done, add it to the Asta document index
+```bash
+asta documents --root .asta/literature/find \
+  add .asta/literature/find/YYYY-MM-DD-topic-slug.json
+  --name="Literature Report: <concise query>" \
+  --summary="<detailed query>" \
+  --tags="find-literature,..." \
+  --mime-type="application/json"
+```
+
+## Step 4: Review results
+
+After the search completes, inspect the top results:
+
+```bash
+jq '[.results | sort_by(-.relevanceScore) | .[0:10][] | {title, year, venue, corpusId, score: .relevanceScore, summary: .relevanceJudgement.relevanceSummary}]' .asta/literature/find/YYYY-MM-DD-topic-slug.json
+```
+
+Share a brief summary of what was found (paper count, top themes) with the user before generating the report. If the results look thin or off-topic, suggest refining the query.
+
+## Step 5: Generate the report
+
+Now follow `workflows/generate-report.md` using the results file from step 3.
+
+</process>

skills/literature-report/workflows/generate-report.md

@@ -0,0 +1,39 @@
+# Generate Report from Find-Literature Results
+
+Use when the user already has a `.json` results file from `asta literature find`.
+
+<process>
+
+## Step 1: Identify the input file
+
+The user provides or references a results file. If it was created by an Asta skill, 
+it will be in .asta/literature/find. Confirm the file exists.
+
+## Step 2: Generate the report
+
+```bash
+asta literature report \
+  -i .asta/literature/find/YYYY-MM-DD-topic-slug.json \
+  -o .asta/literature/report/YYYY-MM-DD-topic-slug.md
+```
+
+Options:
+- `--query "custom framing"` — override the query used as the report title/framing
+- `--max-papers 30` — include more papers (default: 20, highest-relevance first)
+
+The command prints progress to stderr and the report path when done.
+
+## Step 3: Review and deliver
+
+Read the saved report file. Share the key findings with the user, including:
+- The main themes and conclusions
+- Number of papers synthesized
+- The file path so they can open it
+
+If the user wants the report in a specific location (e.g., `docs/literature-review.md`), copy or move it there.
+
+## Step 4: Citations (if needed)
+
+If the report needs formal citations with a `.bib` file, follow `references/citation-conventions.md`.
+
+</process>