superlab 0.1.0 → 0.1.2

package/package-assets/shared/skills/lab/references/paper-writing/paper-review.md

@@ -0,0 +1,86 @@
+# Paper Review (Paper Rview)
+
+## Goal
+
+Use an adversarial, reviewer-style checklist to detect reject risks early and revise the paper before submission.
+
+## Core Principle
+
+Pursue perfectionism in paper quality: assume reviewers will probe every weak point and proactively fix them.
+
+## Critical Rule (Do Not Violate)
+
+Every major claim, especially in Abstract and Introduction, must be:
+
+1. technically correct, and
+2. explicitly supported by experimental evidence.
+
+If a claim is not supported, either add evidence or weaken/remove the claim.
+
+## What Usually Gets a Paper Accepted
+
+1. Sufficient contribution (for example: novel task, novel pipeline, novel module, novel design choices, new experimental findings, or new insight).
+2. Better empirical performance than prior methods under fair comparisons.
+3. Sufficient comparison experiments and ablation studies.
+
+## Common Rejection Dimensions
+
+| Rejection Dimension          | Typical Failure Signals                                                                                                                                                                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1. Insufficient contribution | 1.1 Targeted failure cases are too common.<br /> 1.2 Proposed technique is already well explored; expected gains are predictable/well-known.                                                                                                                                               |
+| 2. Unclear writing           | 2.1 Missing technical details; work is not reproducible.<br />2.2 A method module lacks clear motivation.                                                                                                                                                                                  |
+| 3. Weak empirical effect     | 3.1 Improvement over prior methods is only marginal.<br /> 3.2 Even if better than previous methods, absolute performance is still not strong enough.                                                                                                                                      |
+| 4. Incomplete evaluation     | 4.1 Missing ablation studies.<br />4.2 Missing important baselines or important evaluation metrics.<br /> 4.3 Datasets are too simple to prove the method truly works.                                                                                                                    |
+| 5. Problematic method design | 5.1 Experimental setting is unrealistic.<br />5.2 Method has technical flaws and appears unreasonable.<br />5.3 Method is not robust and needs per-scenario hyperparameter tuning. <br /> 5.4 New design introduces stronger limitations than its benefits, leading to negative net value. |
+
+## End-of-Paper Self-Review Question List
+
+Add this checklist near the end of the draft while revising.
+Use each question to trigger concrete edits before submission.
+
+### 1. Contribution
+
+1. What new knowledge does this paper give to readers?
+2. Are we solving a truly meaningful failure case, not a trivial/common one?
+3. Is the technical idea genuinely non-obvious beyond well-explored practice?
+4. Is our gain surprising or insightful rather than a predictable improvement?
+5. Is there at least one clear novelty type (task/pipeline/module/design finding/insight)?
+
+### 2. Writing Clarity
+
+1. Can a knowledgeable reader reproduce the method from the paper?
+2. Did we provide enough technical detail for each key module?
+3. Is the motivation of every module explicit and logically connected to a challenge?
+4. Are terms and notation consistent across sections?
+5. Does each paragraph carry one clear message with smooth transitions?
+
+### 3. Experimental Strength
+
+1. Are improvements over strong baselines meaningful, not just statistically tiny?
+2. Is absolute performance competitive enough for the target venue?
+3. Are gains consistent across multiple datasets/settings/metrics?
+4. Do we report both strengths and failure cases honestly?
+
+### 4. Evaluation Completeness
+
+1. Do we include ablations for all key design choices?
+2. Are all strong/recent baselines included under fair settings?
+3. Are evaluation metrics standard and sufficient for this task?
+4. Are datasets/scenarios challenging enough to validate real effectiveness?
+5. Are comparison and ablation protocols clearly documented?
+
+### 5. Method Design Soundness
+
+1. Is the experimental setting realistic for practical use?
+2. Does the method have hidden technical defects or unreasonable assumptions?
+3. Is the method robust without heavy per-case hyperparameter retuning?
+4. Do benefits outweigh added complexity and new limitations?
+5. Could reviewers reasonably argue that the net benefit is negative?
+
+## Adversarial Writing Workflow
+
+1. Read the paper as a skeptical reviewer.
+2. Answer every question above with explicit evidence from the paper.
+3. Mark each item as `pass`, `needs revision`, or `needs new experiment`.
+4. Revise claims, writing, experiments, or method scope accordingly.
+5. Repeat until no major rejection risk remains.

package/package-assets/shared/skills/lab/references/paper-writing/related-work.md

@@ -0,0 +1,41 @@
+# Related Work Writing Guide
+
+## Goal
+
+Position your work against the most relevant lines of research, and make your novelty easy to verify.
+
+## Workflow
+
+1. List directly competing and recent baseline papers first.
+2. Group literature by technical topic (not by publication year alone).
+3. For each topic: summarize common paradigm, then key limitation relevant to your challenge.
+4. End each topic by clarifying your distinction.
+
+## Topic Design
+
+Use 2-4 focused topics, for example:
+
+1. Task-specific mainstream methods.
+2. Methods closest to your core idea.
+3. Auxiliary techniques your method builds on.
+
+## Paragraph Template
+
+1. Topic sentence: define scope of this topic.
+2. Representative methods: one compact summary.
+3. Limitation tied to your target technical challenge.
+4. Transition sentence that leads to your method.
+
+## Do and Don't
+
+1. Do compare mechanisms, assumptions, and failure modes.
+2. Do emphasize the exact gap your method fills.
+3. Do not make Related Work a citation dump.
+4. Do not hide strongest baselines.
+
+## Checklist
+
+1. Are all strongest/recent competitors covered?
+2. Is each topic connected to your problem setting?
+3. Is your difference explained in technical terms, not marketing terms?
+4. Is citation coverage complete for all core claims?

package/package-assets/shared/skills/lab/references/paper-writing-integration.md

@@ -1,39 +1,40 @@
 # Paper-Writing Integration
 
-`/lab:write` should directly reuse the upstream `research-paper-writing` section references instead of replacing them with a home-grown summary.
+`/lab:write` vendors the paper-writing references directly into `skills/lab/references/paper-writing/`.
+The goal is to keep the upstream writing discipline while removing brittle runtime dependence on a separately installed skill.
 
-Upstream source:
+## Role Split
 
-- `https://github.com/Master-cai/Research-Paper-Writing-Skills/tree/main/research-paper-writing/references`
-
-## Use paper-writing rules for
+- `lab` controls stage boundaries, evidence discipline, and durable artifacts.
+- the vendored paper-writing references control section structure, paragraph logic, and reviewer-facing polish.
+- `/lab:write` links evidence-backed research outputs to paper-ready text.
 
-- section structure
-- paragraph flow
-- claim-evidence alignment
-- conservative academic tone
-- reviewer-style self-checks
+## Required Shared Constraints
 
-## Do not use paper-writing rules to
+- one section or one bounded subsection per round
+- load only the active section guide, not every section guide
+- mini-outline before prose
+- explicit evidence links for major claims
+- motivation, design, and technical advantage when applicable
+- stable terminology across the whole paper
+- unsupported claims must be weakened or removed
+- section-level flow check and reviewer pass after each round
+- five-dimension self-review before a round is accepted
+- route back to `review` or `iterate` if the evidence is weak
 
-- invent unsupported results
-- hide failed runs or limitations
-- blur sourced evidence with generated interpretation
-- rewrite the whole paper in one unconstrained pass
+## Vendored References
 
-## Operating Model
+- `paper-writing/abstract.md`
+- `paper-writing/introduction.md`
+- `paper-writing/related-work.md`
+- `paper-writing/method.md`
+- `paper-writing/experiments.md`
+- `paper-writing/conclusion.md`
+- `paper-writing/paper-review.md`
+- `paper-writing/does-my-writing-flow-source.md`
 
-- `lab` controls stage boundaries and artifacts
-- `research-paper-writing` references control how each section is written and revised
-- evidence still comes from `report`, iteration reports, and normalized summaries
+## Attribution
 
-## Required Upstream Files
+These references are adapted from:
 
-- `abstract.md`
-- `introduction.md`
-- `related-work.md`
-- `method.md`
-- `experiments.md`
-- `conclusion.md`
-- `paper-review.md`
-- `does-my-writing-flow-source.md`
+- `https://github.com/Master-cai/Research-Paper-Writing-Skills/tree/main/research-paper-writing/references`

package/package-assets/shared/skills/lab/references/workflow.md

@@ -25,7 +25,7 @@ Escalate to a higher-level redesign instead of mutating the mission when the cur
 ## Required Artifacts
 
 - `docs/lab/idea.md`
-- OpenSpec `proposal`, `design`, `spec`, `tasks`
+- one lab change directory under `.superlab/changes/<change-id>/`
 - normalized JSON summary from `scripts/eval_report.py`
 - per-round report in `docs/lab/iterations/`
 - final report in `docs/lab/report.md`

package/package-assets/shared/skills/lab/stages/idea.md

@@ -2,25 +2,61 @@
 
 ## Required Output
 
+- one-sentence problem statement
+- failure case
+- idea classification
+- contribution category
+- breakthrough level
+- existing methods summary
+- why the proposed idea is better than existing methods
+- three meaningful points
 - literature-backed framing
 - sourced datasets and metrics
 - credible baseline shortlist
+- 2-3 candidate approaches with trade-offs
 - generated innovation hypothesis
 - critique before convergence
 - minimum viable experiment
+- explicit approval gate before `/lab:spec`
 
 ## Evidence Discipline
 
 - Mark sourced facts clearly.
 - Mark generated hypotheses clearly.
 - Do not merge them into one undifferentiated summary.
+- Ask one clarifying question at a time when a missing assumption would materially change the proposal.
+- Before writing the full artifact, give the user a short summary with the one-sentence problem, why current methods fail, and the three meaningful points.
+
+## Context Read Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/open-questions.md`
+
+## Context Write Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/decisions.md`
+- `.superlab/context/open-questions.md`
 
 ## Recommended Structure
 
-1. Problem framing
-2. Related work and baseline conventions
-3. Dataset and metric candidates
-4. Proposed innovation
-5. Expert critique
-6. Revised proposal
-7. Minimum viable experiment
+1. One-sentence problem
+2. Failure of existing methods
+3. Idea classification, contribution category, and breakthrough level
+4. Existing methods and shared assumptions
+5. Why the proposed idea is better
+6. Three meaningful points
+7. Candidate approaches and recommendation
+8. Dataset and metric candidates
+9. Falsifiable hypothesis
+10. Expert critique
+11. Revised proposal
+12. Approval gate
+13. Minimum viable experiment
+
+## Writing Standard
+
+- Keep the problem statement short, concrete, and easy to scan.
+- State why the target problem matters before talking about the method.
+- Compare against existing methods explicitly, not by vague novelty language.
+- The three meaningful points should each fit in one direct sentence.

package/package-assets/shared/skills/lab/stages/iterate.md

@@ -9,8 +9,23 @@ Declare and keep fixed:
 - primary metric
 - success threshold
 - verification commands
+- completion_promise
 - maximum iteration count
 
+## Context Read Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/state.md`
+- `.superlab/context/decisions.md`
+- `.superlab/context/evidence-index.md`
+
+## Context Write Set
+
+- `.superlab/context/state.md`
+- `.superlab/context/decisions.md`
+- `.superlab/context/evidence-index.md`
+- `.superlab/context/open-questions.md`
+
 ## Per-Round Output
 
 - round hypothesis
@@ -18,9 +33,26 @@ Declare and keep fixed:
 - normalized evaluation summary
 - written iteration report
 - continue or stop decision
+- diagnostic mode trigger when risk increases for two consecutive rounds
 
 ## Stop Conditions
 
 - threshold reached
 - iteration cap reached
 - fatal methodological flaw discovered
+
+## Failure Exit Contract
+
+If the loop stops without success, record:
+
+- what succeeded
+- what failed
+- top 3 blockers
+- next best actions
+
+## Interaction Contract
+
+- Start each round with a concise summary of current status, the leading hypothesis, and the main round risk.
+- If the next move depends on an unresolved assumption, ask one clarifying question at a time.
+- If more than one next hypothesis is credible, present 2-3 approaches with trade-offs and recommend the next bounded experiment before changing the mission state.
+- Keep an approval gate when a proposed change would alter the frozen mission instead of only changing the implementation hypothesis.

package/package-assets/shared/skills/lab/stages/report.md

@@ -10,9 +10,28 @@
 - limitations
 - next steps
 
+## Context Read Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/state.md`
+- `.superlab/context/decisions.md`
+- `.superlab/context/evidence-index.md`
+
+## Context Write Set
+
+- `.superlab/context/state.md`
+- `.superlab/context/evidence-index.md`
+
 ## Evidence Rules
 
 - Do not hide failed iterations.
 - Tie every major claim to recorded summaries or iteration artifacts.
 - Prefer conservative interpretation over marketing language.
 - Leave a clear handoff path into `/lab:write` with evidence links that section drafts can cite.
+
+## Interaction Contract
+
+- Start with a concise summary of the campaign outcome, strongest supported claim, and biggest reporting risk.
+- If a missing assumption would change report interpretation, ask one clarifying question at a time.
+- If there are multiple defensible report framings, present 2-3 approaches with trade-offs and recommend the most evidence-faithful framing before writing.
+- Keep an approval gate when the reporting frame would materially affect what the paper later claims.

package/package-assets/shared/skills/lab/stages/review.md

@@ -1,5 +1,25 @@
 # `/lab:review` Stage Guide
 
+## Required Flow
+
+1. Give a concise summary of the artifact or result under review.
+2. State the top review question or risk focus.
+3. Audit in reviewer mode.
+4. Output fatal flaws first when present.
+5. Rank the fix priority.
+6. End with residual risks and a clear next action.
+
+## Context Read Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/decisions.md`
+- `.superlab/context/evidence-index.md`
+
+## Context Write Set
+
+- `.superlab/context/state.md`
+- `.superlab/context/open-questions.md`
+
 ## Reviewer Priorities
 
 - unfair or weak baselines
@@ -11,6 +31,16 @@
 
 ## Output Style
 
+- concise summary first
 - findings first
+- fatal flaws called out explicitly
+- fix priority stated clearly
 - evidence-linked critique
 - explicit residual risks
+
+## Interaction Contract
+
+- Start with a concise summary of the review target and the main reviewer question.
+- Ask one clarifying question at a time only if review scope ambiguity would change findings or severity.
+- If there are multiple legitimate review framings, present 2-3 approaches with trade-offs and recommend the strictest useful framing.
+- Do not use brainstorming to soften critique; once scope is clear, stay in reviewer mode and deliver findings directly.

package/package-assets/shared/skills/lab/stages/run.md

@@ -7,6 +7,16 @@
 - normalized evaluation summary
 - validation result for the normalized summary
 
+## Context Read Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/state.md`
+
+## Context Write Set
+
+- `.superlab/context/state.md`
+- `.superlab/context/evidence-index.md`
+
 ## Constraints
 
 - Prefer the smallest experiment that exercises the full pipeline.
@@ -20,3 +30,10 @@
 3. Execute the smallest useful experiment
 4. Normalize raw metrics
 5. Validate the normalized summary
+
+## Interaction Contract
+
+- Start with a concise summary of the run goal, smallest candidate experiment, and primary execution risk.
+- If the next run depends on an unresolved assumption, ask one clarifying question at a time.
+- If there are multiple defensible tiny-run options, present 2-3 approaches with trade-offs and recommend the cheapest informative run.
+- Only ask for approval when choosing a run path would materially spend more time or compute than the default smallest experiment.

package/package-assets/shared/skills/lab/stages/spec.md

@@ -2,10 +2,33 @@
 
 ## Required Output
 
-- OpenSpec `proposal`
-- OpenSpec `design`
-- OpenSpec `spec`
-- OpenSpec `tasks`
+- a lab change id
+- `.superlab/changes/<change-id>/proposal.md`
+- `.superlab/changes/<change-id>/design.md`
+- `.superlab/changes/<change-id>/spec.md`
+- `.superlab/changes/<change-id>/tasks.md`
+
+## Config Read Set
+
+- `.superlab/config/workflow.json`
+
+## Context Read Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/decisions.md`
+- `.superlab/context/state.md`
+
+## Context Write Set
+
+- `.superlab/context/state.md`
+- `.superlab/context/decisions.md`
+
+## Required Change Layout
+
+1. Identify or create a lab change id.
+2. Create `.superlab/changes/<change-id>/`.
+3. Draft `proposal.md`, `design.md`, `spec.md`, and `tasks.md` inside that directory.
+4. Keep the change self-contained so downstream stages can read one directory and its linked context.
 
 ## Conversion Rules
 
@@ -13,9 +36,18 @@
 - Preserve evaluation boundaries from the idea stage.
 - Translate risks into concrete tasks when possible.
 - Make task granularity small enough that `/lab:run` and `/lab:iterate` can execute predictably.
+- Use one lab-native change directory per approved idea instead of scattering spec artifacts.
+
+## Interaction Contract
+
+- Start with a concise summary of the approved idea, target change, and the main spec risk.
+- If change decomposition or validation strategy is materially ambiguous, ask one clarifying question at a time.
+- If there are multiple viable ways to structure the lab change directory, present 2-3 approaches with trade-offs and a recommendation before freezing the change.
+- Keep an approval gate before locking a change structure that will drive `/lab:run` and `/lab:iterate`.
 
 ## Minimum Task Coverage
 
+- change setup
 - artifact creation
 - validation run
 - evaluation normalization

package/package-assets/shared/skills/lab/stages/write.md

@@ -6,40 +6,72 @@
 - iteration reports
 - normalized summaries
 - reviewer notes when available
-- companion `research-paper-writing` references for the active section
+- vendored paper-writing references under `skills/lab/references/paper-writing/`
 
-## Companion References
+## Config Read Set
 
-Load the exact companion file that matches the current target:
+- `.superlab/config/workflow.json`
 
-- abstract -> `research-paper-writing/references/abstract.md`
-- introduction -> `research-paper-writing/references/introduction.md`
-- related work -> `research-paper-writing/references/related-work.md`
-- method -> `research-paper-writing/references/method.md`
-- experiments -> `research-paper-writing/references/experiments.md`
-- conclusion -> `research-paper-writing/references/conclusion.md`
+## Context Read Set
+
+- `.superlab/context/mission.md`
+- `.superlab/context/decisions.md`
+- `.superlab/context/evidence-index.md`
+
+## Context Write Set
+
+- `.superlab/context/state.md`
+- `.superlab/context/evidence-index.md`
+
+## Required References
+
+Load the exact vendored file that matches the current target:
+
+- abstract -> `skills/lab/references/paper-writing/abstract.md`
+- introduction -> `skills/lab/references/paper-writing/introduction.md`
+- related work -> `skills/lab/references/paper-writing/related-work.md`
+- method -> `skills/lab/references/paper-writing/method.md`
+- experiments -> `skills/lab/references/paper-writing/experiments.md`
+- conclusion -> `skills/lab/references/paper-writing/conclusion.md`
 
 Run these on every round:
 
-- section flow check -> `research-paper-writing/references/does-my-writing-flow-source.md`
-- reviewer pass -> `research-paper-writing/references/paper-review.md`
+- section flow check -> `skills/lab/references/paper-writing/does-my-writing-flow-source.md`
+- reviewer pass -> `skills/lab/references/paper-writing/paper-review.md`
 
 ## Small-Step Writing Rules
 
 - Change one section or one clearly bounded subsection per round.
+- LaTeX is the required manuscript output format.
+- Load only the current section guide. Do not load every section guide at once.
+- Build a compact mini-outline before prose.
+- For each subsection, explicitly include motivation, design, and technical advantage when applicable.
+- Avoid a writing style that reads like incremental patching of a naive baseline.
+- Keep terminology stable across the full paper.
 - Tie every new or revised claim to explicit evidence.
+- If a claim cannot be supported by results, weaken or remove it.
 - Record what changed and why in a write-iteration artifact.
+- Return paragraph-level roles for the revised prose when drafting.
+- Run the five-dimension self-review checklist before accepting a round.
 - Run reviewer-style checks after every round.
-- Stop instead of free-writing if the companion references are missing.
+- Stop instead of free-writing if the required references are missing.
 
 ## Required Artifacts
 
-- `docs/lab/paper/plan.md`
-- `docs/lab/paper/sections/<section>.md`
-- `docs/lab/paper/write-iterations/<n>.md`
+- `.superlab/write/plan.md`
+- `.superlab/write/iterations/<n>.md`
+- `docs/paper/paper.tex`
+- `docs/paper/sections/<section>.tex`
 
 ## Stop Conditions
 
 - the target section is accepted for this round
 - evidence is missing and the workflow must return to `review` or `iterate`
 - the writing loop reaches its declared round limit
+
+## Interaction Contract
+
+- Start with a concise summary of the target section, evidence base, and main writing risk for this round.
+- If a missing assumption would change the section structure or claim strength, ask one clarifying question at a time.
+- If there are multiple defensible narrative structures for the current section, present 2-3 approaches with trade-offs and recommend one before drafting.
+- Keep an approval gate when the chosen narrative structure would materially affect downstream sections or paper-level framing.

package/package-assets/shared/templates/design.md

@@ -1,5 +1,10 @@
 # Design
 
+## Lab Change
+
+- Change id:
+- Target path: `.superlab/changes/<change-id>/design.md`
+
 ## Research Approach
 
 Describe the method and why it is plausible.
@@ -21,3 +26,8 @@ Describe the method and why it is plausible.
 - Run registry path:
 - Normalized summary path:
 - Iteration report path:
+
+## Change Links
+
+- Spec path: `.superlab/changes/<change-id>/spec.md`
+- Tasks path: `.superlab/changes/<change-id>/tasks.md`