citeget 0.1.1__tar.gz

citeget-0.1.1/.claude/skills/acquire-references/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: acquire-references
+description: Acquire PDFs of academic references from a document. Parses reference sections, tries direct URLs and arxiv, falls back to libgen search with smart query strategies. Logs all attempts and produces references.md + missed_references.md.
+argument-hint: <path-to-document-with-references> [--work-dir <dir>]
+allowed-tools: Bash, Read, Write, Grep, Glob, Agent
+---
+
+# Acquire References
+
+Download PDFs for all references cited in an academic document. Uses a
+multi-strategy approach: direct URL → arxiv → libgen search (with
+progressively adjusted query specificity).
+
+## Working directory resolution
+
+The system needs a **work directory** where it puts downloads, logs, and
+output files. Resolution rules (in priority order):
+
+1. **User specifies a full path** → use it (create if needed; parent must exist).
+2. **User specifies a bare name** (no slashes) → use `~/Downloads/{name}`.
+3. **User provides a reference file but no work dir** → derive automatically:
+   `{reference_file_stem} -- acquired_references/` in the same directory as
+   the file.
+4. **Neither given** → ask the user.
+
+```python
+from citeget import resolve_work_dir
+
+work_dir = resolve_work_dir(reference_file="/path/to/paper.md")
+# -> /path/to/paper -- acquired_references/
+
+work_dir = resolve_work_dir(work_dir="~/projects/refs")
+# -> /Users/.../projects/refs/
+
+work_dir = resolve_work_dir(work_dir="my_refs")
+# -> ~/Downloads/my_refs/
+```
+
+Inside the work directory, PDFs go into a `references/` subdirectory.
+
+## Pre-flight: checking existing downloads
+
+Before acquiring, check what's already downloaded. Report skips to the user
+so they can rename/move files to force re-download.
+
+```python
+from citeget import check_existing_downloads
+
+to_acquire, already_have = check_existing_downloads(refs, download_dir)
+# already_have is [(Reference, filepath), ...]
+# to_acquire is [Reference, ...]
+```
+
+`acquire_all_references()` does this automatically and prints skip info.
+
+## Core workflow
+
+```python
+from citeget import (
+    parse_references_section,
+    resolve_work_dir,
+    acquire_all_references,
+    write_references_md,
+    write_missed_references_md,
+)
+from pathlib import Path
+from datetime import datetime
+
+# 1. Resolve work directory
+work_dir = resolve_work_dir(reference_file="paper.md")
+download_dir = work_dir / "references"
+
+# 2. Parse references
+refs = parse_references_section(refs_text)
+
+# 3. Acquire (auto-skips existing, auto-generates timestamped log)
+successes, failures, log_entries = acquire_all_references(
+    refs,
+    download_dir=download_dir,
+    work_dir=work_dir,   # enables auto log naming
+)
+# Log written to: {work_dir}/{datetime}__acquisition_log.txt
+
+# 4. Write output files
+write_references_md(successes, download_dir, work_dir / "references.md")
+ts = datetime.now().strftime("%Y-%m-%d_%H%M")
+write_missed_references_md(failures, work_dir / f"{ts}_missed_references.md")
+```
+
+## Log format
+
+The acquisition log (`{datetime}__acquisition_log.txt`) is TSV with columns:
+```
+timestamp  ref_number  ref_title  query  query_type  num_results  matched  best_score  best_title  error
+```
+Every attempt is logged — direct URL, libgen, arxiv, sci-hub — not just libgen.
+
+## File naming
+
+Downloaded files use APA 7 citation format:
+```
+{title} ({authors_apa7}, {year}).pdf
+```
+Where authors_apa7 is: 1 author → "Smith", 2 → "Smith & Jones", 3+ → "Smith et al."
+
+Example: `Retiming synchronous circuitry (Leiserson & Saxe, 1991).pdf`
+
+## Tips
+
+- **Skip non-papers**: Exclude web pages (Math Genealogy, Wikipedia),
+  unpublished preprints with no PDF, and similar non-acquirable items
+- **Rate limiting**: The default 2s delay between operations is respectful.
+  Don't decrease it.
+- **Re-downloading**: Already-downloaded files are reported and skipped. To
+  force re-download, the user must rename or move the existing file.
+- **Matching**: Results are scored on title word overlap (60%), author match
+  (25%), and year match (15%). Threshold is 0.4.
+- **Topics**: Try "articles" first (for papers), then "books" (for books/
+  proceedings). Conference papers often appear under "articles".

citeget-0.1.1/.claude/skills/check-submission-fit/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: check-submission-fit
+description: Assess how well a draft article fits a set of target journals and recommend the best venue. Compares the article's scope, tone, length, audience, and contribution type against journal profiles. Use when deciding where to submit an article.
+argument-hint: <article_file_or_dir> [journal1,journal2,...]
+allowed-tools: Read, Write, Glob, Grep, WebSearch
+---
+
+# Check Article–Journal Fit
+
+Evaluate how well a draft article matches the requirements and culture of one or more journals, and recommend the best submission venue.
+
+## Arguments
+
+- `$0` — Path to the article file or directory (required)
+- `$1` — Comma-separated list of journal keys to evaluate (optional; if omitted, evaluates all known journals)
+  - `ieee_software` — IEEE Software
+  - `cacm_practice` — CACM Practice
+  - `cacm_research` — CACM Research and Advances
+  - `cacm_viewpoints` — CACM Viewpoints/Opinion
+  - `ieee_tse` — IEEE Transactions on Software Engineering
+  - `acm_queue` — ACM Queue
+
+## Workflow
+
+### Phase 1: Extract Article Profile
+
+Read the full article and extract:
+
+| Dimension | Value |
+|-----------|-------|
+| Word count | (count) |
+| Abstract word count | (count) |
+| Number of references | (count) |
+| Number of figures/tables | (count) |
+| Primary audience | researchers / practitioners / both / general CS |
+| Contribution type | empirical study / tool / experience report / opinion / survey / vision |
+| Has methodology section? | yes / no |
+| Has evaluation/data? | yes / no |
+| Tone | formal/academic / semi-formal / conversational |
+| Main domain | SE / systems / PL / AI / security / distributed / general CS |
+| Is novel research? | yes / no |
+| Industry relevance | high / medium / low |
+
+### Phase 2: Load Journal Profiles
+
+Read `data/journal_profiles.json` from the project directory. For each journal in the evaluation list, extract its profile.
+
+### Phase 3: Score Each Journal
+
+For each journal, score the article-journal fit on 6 dimensions (1=poor, 3=good, 5=excellent):
+
+#### Dimension Scoring Rubric
+
+**1. Scope Match**
+- Does the article's subject fall within what this journal covers?
+- 5: Core topic of this venue; 3: Adjacent; 1: Out of scope
+
+**2. Contribution Type Match**
+- Does the article's type (empirical, opinion, tool, etc.) match what the journal publishes?
+- 5: Exact match; 3: Acceptable variant; 1: Mismatch
+
+**3. Audience Match**
+- Does the article's assumed audience match the journal's readership?
+- 5: Perfect fit; 3: Requires reframing; 1: Wrong audience
+
+**4. Tone Match**
+- Is the writing style appropriate for this journal?
+- 5: No adjustment needed; 3: Minor tuning; 1: Major rewrite needed
+
+**5. Length/Format Feasibility**
+- Can the article be adapted to fit this journal's format requirements with reasonable effort?
+- 5: Already fits; 3: Moderate cuts/additions needed; 1: Fundamental restructuring required
+
+**6. Novelty vs. Accessibility Balance**
+- Is the article's novelty/depth appropriate for this venue?
+- 5: Perfect balance; 3: Slightly off; 1: Too academic for a magazine or too shallow for a journal
+
+#### Adjustment Factors
+
+Apply these as ±1 adjustments to the total:
+- `+1` — Article has strong practitioner takeaways (favors IEEE Software, ACM Queue)
+- `+1` — Article has rigorous methodology + evaluation (favors IEEE TSE)
+- `+1` — Article is broadly accessible to non-SE CS readers (favors CACM)
+- `-1` — Article is too long to fit this journal even with cuts
+- `-1` — Article is invitation-only and user has no invite (ACM Queue)
+- `-1` — Article is primarily about a narrow tool without generalizable lessons (penalizes CACM Research)
+
+### Phase 4: Produce Fit Report
+
+Write a fit report to `output/<article_slug>_fit_report.md`:
+
+```markdown
+# Journal Fit Report: <Title>
+
+**Assessed:** <date>
+**Article type:** <contribution type>
+**Current word count:** <count>
+
+---
+
+## Fit Scores
+
+| Journal | Scope | Type | Audience | Tone | Length | Novelty | Adjustments | **Total** |
+|---------|-------|------|----------|------|--------|---------|-------------|-----------|
+| IEEE Software | X | X | X | X | X | X | +/-X | **X/30** |
+| CACM Practice | X | X | X | X | X | X | +/-X | **X/30** |
+| CACM Research | X | X | X | X | X | X | +/-X | **X/30** |
+| CACM Viewpoints | X | X | X | X | X | X | +/-X | **X/30** |
+| IEEE TSE | X | X | X | X | X | X | +/-X | **X/30** |
+| ACM Queue | X | X | X | X | X | X | +/-X | **X/30** |
+
+---
+
+## Recommendation
+
+**Primary recommendation:** <Journal Name> (score: X/30)
+
+<2-3 sentences explaining why this is the best fit>
+
+**Backup recommendation:** <Journal Name> (score: X/30)
+
+<1-2 sentences>
+
+**Not recommended:** <Journal Name> — <reason in one sentence>
+
+---
+
+## What It Would Take
+
+### To submit to <Primary Recommendation>:
+- [ ] <specific change 1>
+- [ ] <specific change 2>
+- [ ] ...
+
+### To submit to <Backup>:
+- [ ] <specific change 1>
+- [ ] ...
+
+---
+
+## Red Flags
+
+(Anything that would likely trigger a desk rejection or poor peer review at the recommended venue)
+
+- <flag 1>
+- <flag 2>
+
+---
+
+## Notes on Specific Journals
+
+<Any other observations about specific journals not captured in scores>
+```
+
+## Output
+
+- `output/<article_slug>_fit_report.md` — Journal fit assessment and recommendations
+
+## Decision Guide
+
+Use these heuristics when scores are close:
+
+| Article type | Best primary target | Best backup |
+|-------------|---------------------|------------|
+| Empirical study with novel findings | IEEE TSE | CACM Research |
+| Tool/method with practitioner validation | IEEE Software | CACM Practice |
+| Experience report / case study | IEEE Software | CACM Practice |
+| Broad vision / position paper | CACM Research | CACM Viewpoints |
+| Opinion / argument | CACM Viewpoints | IEEE Software |
+| Deep technical practitioner story | ACM Queue (if invited) | IEEE Software |
+| Theoretical contribution | IEEE TSE | CACM Research |
+
+## Notes
+
+- Desk rejection is the biggest risk — always prioritize scope and contribution type match
+- IEEE Software and CACM Practice are both practitioner-focused but differ: IEEE Software is SE-specific; CACM Practice targets all of CS
+- CACM's editorial bar is high even for well-written work — the "why does this matter to all of CS?" test is real
+- IEEE TSE reviewers expect rigorous methodology; if there is no evaluation or formal proof, TSE is probably wrong
+- ACM Queue is only worth pursuing if the user has an invitation or a very compelling pitch; flag this clearly

citeget-0.1.1/.claude/skills/format-for-journal/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: format-for-journal
+description: Reformat and adapt a draft article to meet the specific requirements of a target journal (IEEE Software, CACM, IEEE TSE, etc.). Adjusts structure, word count, abstract, references, and required elements. Use when you have a polished draft and need to produce a journal-ready version.
+argument-hint: <article_file_or_dir> <target_journal>
+allowed-tools: Read, Write, Edit, Glob, Grep, WebSearch, Bash(python *)
+---
+
+# Format Article for Journal Submission
+
+Transform a draft article into a version that meets the specific structural and formatting requirements of a target journal.
+
+## Arguments
+
+- `$0` — Path to the article file (`.md`, `.txt`, `.tex`, or a directory) (required)
+- `$1` — Target journal key (required). One of:
+  - `ieee_software` — IEEE Software magazine
+  - `cacm_practice` — CACM Practice section
+  - `cacm_research` — CACM Research and Advances section
+  - `cacm_viewpoints` — CACM Viewpoints/Opinion section
+  - `ieee_tse` — IEEE Transactions on Software Engineering
+  - `acm_queue` — ACM Queue (note: invitation-only, see notes)
+
+## Workflow
+
+### Phase 1: Load Journal Profile
+
+Read `data/journal_profiles.json` from the project directory to get the exact requirements for the target journal. Key dimensions:
+
+- Word/page limit
+- Abstract word limit
+- Reference limit
+- Required sections
+- Required elements (takeaways, author bios, etc.)
+- Tone (research vs. practitioner vs. broad audience)
+- Citation style
+
+### Phase 2: Inventory the Draft
+
+Read the full draft and build an inventory:
+
+- Current word count (use `scripts/count_words.py` or count manually from content)
+- Section structure
+- Abstract word count
+- Number of references
+- Figures and tables (each counts as ~250 words for IEEE Software)
+- Any journal-specific required elements present or absent
+
+Report the inventory as a table showing current vs. required for each dimension.
+
+### Phase 3: Apply Journal-Specific Transformations
+
+Work through each requirement and transform the article. Create a new file rather than modifying the original.
+
+#### For `ieee_software`:
+
+1. **Word limit (4,200 words + figures @250 each)**
+   - Count figures, compute effective budget: `4200 - (num_figures * 250)`
+   - If over budget: identify sections to cut; prioritize cutting related work and methodological details that practitioners don't need
+   - If well under budget: consider adding a concrete example or figure
+
+2. **Abstract (max 150 words)**
+   - Rewrite to be exactly ≤150 words
+   - Must describe the overall focus and main takeaway
+   - Should not contain abbreviations or citations
+
+3. **References (max 15)**
+   - If over 15: identify which references can be merged, cut, or replaced with a more authoritative single source
+   - Prioritize: seminal works > recent influential works > online resources
+   - Format: IEEE numbered style `[1]`, `[2]`, ...
+
+4. **Practitioner Takeaways (required)**
+   - Add a "Practitioner Takeaways" sidebar/section with exactly 3 bullet points
+   - Each must be a concrete, actionable insight — not a restatement of the abstract
+   - Format:
+     ```
+     ## Practitioner Takeaways
+     - <Specific insight a practitioner can act on>
+     - <Specific insight a practitioner can act on>
+     - <Specific insight a practitioner can act on>
+     ```
+
+5. **Author bio(s) (required)**
+   - Add a brief bio (2-3 sentences) for each author
+   - Include: current role, research/practice area, contact/email or affiliation
+
+6. **Tone adjustment**
+   - Soften heavy academic hedging; practitioners prefer direct statements
+   - Replace "it can be argued that" → "this shows that"
+   - Ensure code examples or figures are concrete and immediately useful
+
+#### For `cacm_practice` or `cacm_research`:
+
+1. **Page limit (10 pages single-column single-spaced, ~6,000–7,000 words)**
+   - Use ACM `acmsmall` template mentally; single-column, generous margins
+   - If over budget: tighten related work, shorten examples
+
+2. **References (max 40, alphabetical order)**
+   - Format: ACM style — `[AuthorYear]` or numbered alphabetically by first author last name
+   - Ensure all references are complete (no "et al." in reference list itself)
+
+3. **Broad audience requirement**
+   - CACM's key editorial test: could a computer scientist outside this subfield follow this article?
+   - Add a "What problem are we solving?" paragraph early
+   - Define all acronyms and jargon
+   - Add context that a non-specialist would need
+
+4. **Author statement of relevance** (required at submission)
+   - Draft a 1-paragraph statement: "Why does this matter to the computing field? Why is it valuable to CACM readers?"
+   - Save this as a separate file: `output/<slug>_cacm_relevance_statement.md`
+
+#### For `cacm_viewpoints`:
+
+1. **Page limit (5 pages, ~3,000 words)**
+   - More opinion-forward; less methodology detail needed
+   - Strong thesis statement required in first 2 paragraphs
+
+2. **References (max 10)**
+   - Be ruthless; only the most essential citations
+
+3. **Point-counterpoint framing** (optional but valued by CACM)
+   - If the article takes a position, acknowledge the strongest opposing view and address it
+
+#### For `ieee_tse`:
+
+1. **Page limit (12 formatted pages in IEEE 2-column format)**
+   - IEEE 2-column format is denser than single-column; roughly 8,000–10,000 words equivalent
+   - Structured abstract preferred: Objective, Methods, Results, Conclusion
+
+2. **References (unlimited, IEEE numbered style)**
+   - Ensure all references include venue, volume, issue, pages
+   - Self-citations: list and review for appropriateness
+
+3. **Replication package note** (strongly recommended)
+   - Add a Data Availability statement if the work has associated data, code, or artifacts
+
+4. **Rigor markers**
+   - Ensure threats to validity section exists (for empirical work)
+   - Ensure limitations are explicitly stated
+
+#### For `acm_queue`:
+
+Note: ACM Queue is invitation-only. The formatted version here is for reference or after receiving an invitation.
+
+1. **Word limit (~3,500 words)**
+   - Conversational, problem-focused narrative
+   - Cut all hedging language; Queue readers are senior engineers who want directness
+
+2. **No rigid section structure**
+   - Problem → Challenge → Insight arc, not Introduction/Related Work/Methodology/Conclusion
+
+3. **Tone**
+   - Write as if explaining to a colleague at a whiteboard
+   - Include real war stories, production numbers, failure modes
+
+### Phase 4: Generate the Formatted Output
+
+Write the transformed article to:
+`output/<article_slug>_<journal_key>.md`
+
+Also generate a **change summary** documenting what was modified:
+`output/<article_slug>_<journal_key>_changes.md`
+
+Change summary format:
+```markdown
+# Formatting Changes: <Title> → <Journal>
+
+**Original word count:** X
+**Formatted word count:** X (target: X)
+
+## Changes Made
+
+### Structural Changes
+- <what was added/removed/moved>
+
+### Abstract
+- <original word count> → <new word count>
+- <key changes>
+
+### References
+- <original count> → <new count>
+- <references removed: list titles>
+
+### Added Required Elements
+- <list any newly added required sections>
+
+### Tone Adjustments
+- <key phrasing changes>
+
+## What Still Needs Human Review
+
+- <list any decisions that require author judgment>
+- <any sections where cuts were made that author should verify>
+```
+
+## Output Files
+
+1. `output/<article_slug>_<journal_key>.md` — Reformatted article
+2. `output/<article_slug>_<journal_key>_changes.md` — Change summary
+3. `output/<article_slug>_cacm_relevance_statement.md` — (CACM only) Relevance statement
+
+## Notes
+
+- Never delete content from the original; create a new file
+- When cutting for word count, preserve the core argument — cut supporting material, not the thesis
+- If cuts are ambiguous, leave a `<!-- AUTHOR: consider cutting this section -->` comment
+- The formatted output is a starting point — always review with the author before submission
+- LaTeX formatting is outside the scope of this skill; this produces clean markdown that can be pasted into a LaTeX template
+- Use `scripts/count_words.py` to get accurate word counts