research-copilot 0.2.2 → 0.2.4

package/lib/skills/builtin/paper-revision/references/framing-patterns.md

@@ -0,0 +1,119 @@
+# Framing Patterns for Paper Revision
+
+Common reframing strategies that turn borderline papers into defensible submissions. Each pattern includes the problem it solves, the reframe, and an example.
+
+---
+
+## Pattern 1: From "Pipeline of Components" to "Protocol / Contract"
+
+### When to use
+Paper has multiple components that each exist in prior work. Reviewers will say "this is just integration."
+
+### The reframe
+Define the contribution not as the components but as the **conditions under which they must operate together**. The novelty is the contract, not the parts.
+
+### Template
+> "Prior work addresses [A], [B], and [C] separately. But [the problem] requires all four conditions to hold simultaneously: [condition 1], [condition 2], [condition 3], [condition 4]. Our contribution is the protocol that enforces these conditions together."
+
+### Example (ParameterRec / MATRIX-IO)
+- Before: "We cluster traces, synthesize surrogates, and train a recommender."
+- After: "We define when historical traces may become reusable tuning evidence, by enforcing semantic partition, executable anchoring, validated transfer, and bounded serving together."
+
+---
+
+## Pattern 2: From "Benchmark Paper" to "Benchmark-Backed Measurement Study"
+
+### When to use
+Paper introduces a benchmark but the benchmark alone may not be seen as sufficient novelty.
+
+### The reframe
+Position the benchmark as an **evaluation substrate** that enables a measurement study. The paper's value is the measurement findings, not the benchmark artifact.
+
+### Template
+> "We use [benchmark name] not as an end in itself, but as the evaluation substrate for a controlled measurement study of [phenomenon]. Our central finding is [mechanism / finding]."
+
+### Example (COIDI)
+- Before: "We introduce CIODI-Bench for evaluating LLM agents on HPC telemetry."
+- After: "We use CIODI-Bench as an evaluation substrate to measure how reliability bottlenecks in LLM agents shift with task structure."
+
+---
+
+## Pattern 3: From "Parallel Observations" to "Unified Mechanism"
+
+### When to use
+Paper has 2-4 separate findings that are individually reasonable but collectively feel like "result dump."
+
+### The reframe
+Identify a single mechanism that explains all findings as special cases. The paper's thesis becomes the mechanism, not the individual observations.
+
+### Template
+> "Our central finding is that [mechanism] shifts with [variable]. Specifically, for [regime A], [bottleneck A] dominates; for [regime B], [bottleneck B] dominates; for [regime C], [bottleneck C] dominates."
+
+### Example (COIDI)
+- Before: "Context helps on extraction. Verification helps on analysis. Strong models help on hard tasks."
+- After: "The dominant reliability bottleneck shifts with task structure: semantic grounding on extraction, verification tractability on analysis, upstream hypothesis formation on hard tasks."
+
+---
+
+## Pattern 4: From "We Did X" to "Gap Chain"
+
+### When to use
+Paper solves a problem but the connection between the problem and the solution feels hand-wavy.
+
+### The reframe
+Identify the specific gaps that prevent the obvious/naive approach from working. Structure the contribution as closing those gaps.
+
+### Template
+> "[Resource] cannot directly become [goal] because of N gaps: [gap 1], [gap 2], ..., [gap N]. We close these gaps by [solution 1], [solution 2], ..., [solution N]."
+
+### Example (ParameterRec / MATRIX-IO)
+- Before: "We use production traces for I/O tuning."
+- After: "Production traces cannot directly become reusable tuning evidence because: (1) they don't define a semantically valid evidence space, (2) they're descriptive not executable, (3) trace-level resemblance doesn't imply transfer validity, (4) serving needs a stopping rule. We close each gap."
+
+---
+
+## Pattern 5: Three-Layer Claim Hierarchy
+
+### When to use
+Collaborators disagree about what the core contribution is (common when system builders care about practical impact and advisors care about intellectual novelty).
+
+### The reframe
+Separate value, problem, and mechanism into three explicit layers. All appear in the paper, but the mechanism is the defensible novelty.
+
+### Template
+> "[Value statement: what practical benefit this delivers.] This is possible because [problem statement: what problem this solves and using what resources]. The technical mechanism that makes it work is [mechanism statement: the specific novelty]."
+
+### Example (ParameterRec / MATRIX-IO)
+- Value: "Reduces hardware-backed tuning cost."
+- Problem: "Uses large production trace corpora for tuning."
+- Mechanism: "Execution-backed conservative evidence-reuse protocol."
+- Combined: "MATRIX-IO uses large production I/O trace corpora to reduce hardware-backed tuning cost, by turning trace history into execution-backed, conservatively reusable tuning evidence."
+
+---
+
+## Pattern 6: From "Method Paper" to "Design Principles Paper"
+
+### When to use
+Paper proposes a system or method, but the specific design may not generalize. The insights behind the design are more valuable than the design itself.
+
+### The reframe
+Position the paper as extracting design principles or deployment guidance, with the system as the vehicle for discovering and validating those principles.
+
+### Template
+> "Our system demonstrates that [design principle]. This yields practical guidance: [when to do X], [when to do Y], [when not to do Z]."
+
+---
+
+## Pattern 7: Lowering Secondary Contributions Without Removing Them
+
+### When to use
+A secondary result matters to some reviewers but shouldn't overshadow the primary claim.
+
+### The reframe
+Include the secondary contribution in the value layer but not the mechanism layer. Give it one clear bullet, positioned after primary contributions.
+
+### Rules
+- Never mention the secondary result before the primary claim in abstract/intro
+- In evaluation, show it as a consequence of the primary mechanism
+- In contribution bullets, use phrasing like "as a practical consequence" or "this additionally reduces"
+- Do not create a separate evaluation section for it; embed it in the primary evaluation flow

package/lib/skills/builtin/paper-revision/references/reviewer-attack-catalog.md

@@ -0,0 +1,171 @@
+# Reviewer Attack Catalog
+
+Common reviewer objections organized by category, with defense strategies and preemptive text templates. Use this to anticipate and address attacks before submission.
+
+---
+
+## Category 1: Novelty Attacks
+
+### Attack 1.1: "This is just integration"
+**When it comes:** Paper has multiple components that each exist in prior work.
+
+**Defense strategy:** Reframe as protocol/contract (see framing-patterns.md Pattern 1). Add a capability comparison table showing no prior work satisfies all conditions simultaneously.
+
+**Preemptive text template:**
+> "The contribution is not any individual component in isolation — [X], [Y], and [Z] each have precedents. Rather, it is the protocol that couples them: [goal] becomes possible only when [conditions] are enforced together. No prior system enforces all of these simultaneously (Table N)."
+
+---
+
+### Attack 1.2: "This is incremental over [specific prior work]"
+**When it comes:** A closely related system exists.
+
+**Defense strategy:** Identify the specific capability delta. If the delta is small, acknowledge it and reframe around the unique combination. If the delta is large, make it more visible.
+
+**Preemptive text template:**
+> "[Prior work] addresses [X] but assumes [limitation]. In our setting, [limitation does not hold] because [reason]. [Our approach] removes this assumption by [mechanism]."
+
+---
+
+### Attack 1.3: "The findings are obvious / expected"
+**When it comes:** Results align with intuition (e.g., "of course more context helps").
+
+**Defense strategy:** Emphasize that the contribution is not the direction of the effect but its quantification, boundary conditions, and mechanism. Add quantitative deltas and identify where the effect does NOT hold.
+
+**Preemptive text template:**
+> "While the direction of this effect may be intuitive, our study provides the first controlled quantification: [effect size]. Importantly, the effect reverses under [condition], demonstrating that [nuance]."
+
+---
+
+## Category 2: Scope and Generalization Attacks
+
+### Attack 2.1: "Single site / single dataset / narrow domain"
+**When it comes:** Experiments use data from one source.
+
+**Defense strategy:** Do NOT claim broad universality. Instead, claim "controlled realism" and position the single site as a high-fidelity first step.
+
+**Preemptive text template:**
+> "We scope the validated path to [site/dataset] because it provides [specific advantages: production data, complete metadata, etc.]. We do not claim that quantitative results transfer unchanged to all [domains]. Rather, we provide a controlled, realistic substrate for studying [phenomenon], and we expect the qualitative patterns to generalize to settings with similar [characteristics]."
+
+---
+
+### Attack 2.2: "Would this work on a different [system/domain/scale]?"
+**When it comes:** The approach seems tied to specific infrastructure.
+
+**Defense strategy:** Identify what the approach actually depends on (e.g., "feature availability" not "specific hardware") and state that dependency explicitly.
+
+**Preemptive text template:**
+> "Extension to other [systems/domains] requires [specific conditions], not merely more data. We discuss this requirement in Section N and leave multi-[site/domain] validation to future work."
+
+---
+
+### Attack 2.3: "N is too small" (tasks, samples, runs, etc.)
+**When it comes:** Dataset/benchmark size seems insufficient.
+
+**Defense strategy:** Do not compete on scale. Compete on quality, realism, and control. Explain why N is sufficient for the claims being made.
+
+**Preemptive text template:**
+> "We emphasize [quality/realism/expert curation/control] over scale. Each of the N [items] involves [complexity]. Our claims are at the [regime/family/category] level, not at the level of fine-grained ranking between near-tied methods, and the observed effects are consistent across [groupings]."
+
+---
+
+## Category 3: Methodology Attacks
+
+### Attack 3.1: "How were thresholds / hyperparameters chosen?"
+**When it comes:** Paper uses thresholds or design choices without clear justification.
+
+**Defense strategy:** State the thresholds explicitly. Explain the design rationale (conservative, validated on held-out data, or sensitivity-analyzed). If sensitivity analysis exists, reference it.
+
+**Preemptive text template:**
+> "We set [threshold] = [value] based on [rationale]. The system is intentionally [conservative/asymmetric]: [explanation of design choice]. We report sensitivity to this choice in [appendix/section]."
+
+---
+
+### Attack 3.2: "This relies on manual / hand-crafted rules"
+**When it comes:** Paper has expert-defined categories, rules, or heuristics.
+
+**Defense strategy:** Reframe rules as "operational constraints" or "semantic priors" rather than "heuristics." Emphasize that they define the scope of safe operation, not universal truth.
+
+**Preemptive text template:**
+> "[Rules/categories] encode operational constraints rather than universal taxonomy. They define the scope within which [reuse/transfer/recommendation] is safe. We prioritize [conservative correctness] over [full automation], and we expect these constraints to be refined as [domain knowledge / deployment experience] grows."
+
+---
+
+### Attack 3.3: "Baseline comparison is unfair"
+**When it comes:** Baselines are weak, adapted from different settings, or cherry-picked.
+
+**Defense strategy:** Explain why each baseline was chosen and what question it answers. If adaptation was necessary, explain what was preserved and what was changed.
+
+**Preemptive text template:**
+> "We compare against [baselines] not as straw men but as a progression: [baseline 1] tests whether [simple approach] suffices; [baseline 2] tests whether [moderate approach] closes the gap; [our method] tests whether the full [path/protocol] is necessary. This ladder structure isolates the contribution of each design element."
+
+---
+
+### Attack 3.4: "K / number of runs is too low for reliable conclusions"
+**When it comes:** Stochastic experiments with limited repetitions.
+
+**Defense strategy:** Acknowledge the budget constraint, explain what level of conclusion the data supports, and state what you do NOT claim.
+
+**Preemptive text template:**
+> "We run K=[value] trials per configuration, yielding [metric] as our primary reliability estimate. We do not claim fine-grained ranking between near-tied methods; rather, we focus on [regime-level / family-level] conclusions where the observed effects are consistent across [categories/tasks]. Larger K would sharpen uncertainty estimates but is unlikely to reverse the broader trends observed."
+
+---
+
+## Category 4: Presentation Attacks
+
+### Attack 4.1: "The paper is hard to follow"
+**When it comes:** Narrative is unclear, inconsistent terminology, or poor section transitions.
+
+**Defense strategy:** Apply Phase 3 (Narrative Unification) systematically. Ensure every section opening answers "what is this section's job?"
+
+---
+
+### Attack 4.2: "Claims in abstract/intro don't match evaluation"
+**When it comes:** Front matter was revised but evaluation wasn't updated (or vice versa).
+
+**Defense strategy:** Do a claim-echo audit: for each claim in the abstract, find the exact evaluation paragraph that supports it.
+
+---
+
+### Attack 4.3: "Figure/table doesn't support the claimed conclusion"
+**When it comes:** Captions are generic, or the text interprets the figure differently than what it shows.
+
+**Defense strategy:** Rewrite captions to include the key takeaway. Ensure text references to figures state what to observe and why it matters.
+
+---
+
+## Category 5: Significance Attacks
+
+### Attack 5.1: "So what? Why should [community] care?"
+**When it comes:** Paper is technically sound but doesn't connect to community values.
+
+**Defense strategy:** Add a "community significance" paragraph in the introduction that translates technical findings into operational/deployment/practical terms.
+
+**SC-specific template:**
+> "For the HPC [storage/computing] community, this means [practical implication]. The path to [goal] requires not [naive approach] but [principled approach that our work demonstrates]."
+
+---
+
+### Attack 5.2: "This is a nice dataset/tool but not a research contribution"
+**When it comes:** Paper's primary artifact is a benchmark, tool, or dataset.
+
+**Defense strategy:** Reframe as measurement study or design study (see framing-patterns.md Pattern 2). The artifact is the instrument; the findings are the contribution.
+
+---
+
+## Using This Catalog
+
+### Before submission
+1. Read through the catalog and identify 3-5 attacks most relevant to your paper
+2. For each, check whether the paper already addresses it
+3. If not, add preemptive defense using the templates above
+4. Prioritize attacks by likelihood and severity
+
+### During revision
+- When a collaborator or internal reviewer raises a concern, check if it maps to a catalog entry
+- If yes, apply the corresponding defense strategy
+- If no, consider adding a new entry for future reference
+
+### After reviews
+- Map each reviewer comment to a catalog entry
+- Use the defense strategy to draft rebuttal responses
+- Strengthen the paper text for resubmission

package/lib/skills/builtin/paper-revision/references/venue-strategies.md

@@ -0,0 +1,114 @@
+# Venue-Specific Revision Strategies
+
+Guidance for adapting revision strategy to the values, expectations, and reviewer culture of specific conference types.
+
+---
+
+## SC / HPDC (HPC Systems)
+
+### What reviewers value most
+- Real systems on real hardware with real workloads
+- Operational relevance to HPC facilities
+- Reproducibility and artifact descriptions
+- Conservative, well-bounded claims
+- Performance at scale
+
+### What gets papers rejected
+- "Demo paper" feel without clear intellectual contribution
+- Overclaimed generalization from limited evaluation
+- Missing limitations section or dishonest scope
+- Ignoring prior HPC-specific work
+- Benchmarks without explaining why the benchmark design matters
+
+### Revision priorities for SC
+1. **Operational framing:** Connect findings to what HPC facility operators / administrators would actually do differently
+2. **Scope honesty:** Be explicit about single-site vs. multi-site, production vs. testbed, application-specific vs. general
+3. **Reproducibility signals:** Mention artifact availability, exact configurations, hardware specs
+4. **Performance context:** Always explain whether speedups are over reasonable baselines (not just defaults)
+5. **Community significance paragraph:** Translate technical findings into HPC deployment implications
+
+### Style notes
+- Direct, technical prose; avoid promotional language
+- Prefer concrete mechanisms over abstract frameworks
+- Include compute/cost/resource details
+- Limitations section is expected and respected
+
+---
+
+## OSDI / SOSP / NSDI (Systems)
+
+### What reviewers value most
+- Clean problem formulation with clear design invariants
+- Systems that address a real deployment pain point
+- Strong evaluation methodology (not just "it's faster")
+- Safety boundaries and failure modes
+- Design lessons that generalize beyond the specific system
+
+### What gets papers rejected
+- "Engineering effort" without clear intellectual contribution
+- Evaluation that only shows the happy path
+- Missing discussion of failure modes / edge cases
+- Claims that don't match the evaluated scope
+- Poor writing quality (OSDI/SOSP have very high presentation bar)
+
+### Revision priorities for OSDI/SOSP
+1. **Design invariants:** State what your system always guarantees, not just what it usually achieves
+2. **Necessity evidence:** Prove that simpler approaches don't work (ablation, controlled comparisons)
+3. **Failure mode analysis:** Show what happens when assumptions are violated
+4. **Scalability and cost:** Include deployment overhead, not just throughput
+5. **Design lessons section:** Extract 2-3 takeaways that other system builders can use
+
+### Style notes
+- Very strong problem formulation expected in first 2 pages
+- "Rapid review" culture: reviewers decide quickly based on intro quality
+- Design section should explain *why*, not just *what*
+- Evaluation should answer specific research questions, not demonstrate features
+
+---
+
+## NeurIPS / ICML / ICLR (ML/AI)
+
+### What reviewers value most
+- Clear, novel contribution (method, theory, or empirical finding)
+- Rigorous ablation studies
+- Reproducible experimental setup
+- Positioning relative to a well-defined problem
+- Statistical rigor (error bars, significance tests, multiple seeds)
+
+### What gets papers rejected
+- "Bag of tricks" without clear insight
+- Evaluation on only one dataset/setting
+- Missing ablations for key design choices
+- Overclaimed novelty that is actually incremental
+- Poor related work coverage
+
+### Revision priorities for NeurIPS/ICML
+1. **One clear contribution:** Can you state it in one sentence? If not, the paper isn't ready
+2. **Ablation rigor:** Every non-obvious design choice needs an ablation or justification
+3. **Statistical reporting:** Error bars, number of seeds, significance tests where appropriate
+4. **Related work density:** Cite generously; reviewers may have authored related papers
+5. **Abstract formula:** Use the 5-sentence structure (what/why hard/how/evidence/best number)
+
+### Style notes
+- More theoretical framing expected than systems venues
+- "Broader Impact" or similar statement may be required
+- Appendix can be extensive but reviewers aren't required to read it
+- Checklist compliance is mandatory at most venues
+
+---
+
+## Cross-Venue Patterns
+
+### Universal high-ROI actions
+1. Ensure title accurately signals the paper type
+2. Ensure abstract contains at least 2 concrete numbers
+3. Ensure introduction has clear contribution bullets
+4. Ensure evaluation opening states what questions are being answered
+5. Ensure limitations section exists and is honest
+
+### Universal revision traps
+1. Revising front matter but not evaluation (or vice versa)
+2. Adding more results instead of fixing the narrative
+3. Over-defending minor points while leaving major gaps unaddressed
+4. Changing terminology mid-revision without propagating everywhere
+5. Cutting limitations to save space (this always backfires)

package/lib/skills/builtin/paper-writing/SKILL.md

@@ -26,6 +26,7 @@ This skill covers the full lifecycle of conference paper writing: from assemblin
 - Research is still in progress — finish experiments and analysis first.
 - You need a literature survey — use the `literature-search` tool.
 - You need to brainstorm research directions — use `brainstorming-research-ideas` or `creative-thinking-for-research`.
+- You already have a draft and want to **strategically revise** it (reframe the contribution, strengthen evidence, prepare reviewer defense, unify the narrative) — use `paper-revision` instead. That skill covers framing diagnosis, claim crystallization, and reviewer-adversarial revision, which are fundamentally different from first-draft writing.
 - You are writing a **journal article** (Nature, Science, NEJM, etc.), **technical report**, or **research summary** — use `scientific-writing` instead, which covers IMRAD structure, journal-specific citation styles (APA/AMA/Vancouver), and reporting guidelines (CONSORT/STROBE/PRISMA).
 
 ### paper-writing vs scientific-writing: Which to Use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "research-copilot",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "AI-powered research assistant for scientists — literature search, data analysis, academic writing, and project management",
   "type": "module",
   "bin": {
@@ -47,9 +47,9 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@mariozechner/pi-agent-core": "^0.61.1",
-    "@mariozechner/pi-ai": "^0.61.1",
-    "@mariozechner/pi-coding-agent": "^0.61.1",
+    "@mariozechner/pi-agent-core": "^0.66.1",
+    "@mariozechner/pi-ai": "^0.66.1",
+    "@mariozechner/pi-coding-agent": "^0.66.1",
     "@sinclair/typebox": "^0.34.48",
     "adm-zip": "^0.5.16",
     "ajv": "^8.18.0",