vibe-research

Category: Research & Analysis | Uploader: Zhangyanbo | Downloads: 0 | Version: v1.0（Latest）

Set up and maintain a Vibe Research project with bi-directional sync between experimental code, paper.md, and developer docs. Use when starting a research project, managing experimental code, maintaining research documentation, creating academic papers, writing research logs, updating project docs, migrating an existing project to Vibe Research structure, or when the user mentions vibe research, paper sync, research log, experiment tracking, project migration, partial migration, incremental migration, doc update, or bi-directional sync between code and paper.

Changelog: Source: GitHub https://github.com/Zhangyanbo/vibe-research-skill

Directory Structure

Current level: Root

📁 reference/
- 📄 doc-maintenance.md 5.0 KB
- 📄 formats.md 1.6 KB
- 📄 init.md 1.3 KB
- 📄 migrate.md 4.4 KB
- 📄 partial-migrate.md 5.4 KB
📁 resources/
- 📁 templates/
  - 📄 agents-rules.md 5.0 KB
  - 📄 paper.md 907 B
📁 scripts/
- 📄 init.sh 5.1 KB
📄 .gitignore 9 B
📄 LICENSE 1.0 KB
📄 README.md 2.8 KB
📄 SKILL.md 6.9 KB

SKILL.md

---
name: vibe-research
description: Set up and maintain a Vibe Research project with bi-directional sync between experimental code, paper.md, and developer docs. Use when starting a research project, managing experimental code, maintaining research documentation, creating academic papers, writing research logs, updating project docs, migrating an existing project to Vibe Research structure, or when the user mentions vibe research, paper sync, research log, experiment tracking, project migration, partial migration, incremental migration, doc update, or bi-directional sync between code and paper.
---

# Vibe Research

Vibe Research treats the AI agent as a "talented but untrustworthy remote research team." The human researcher sets direction and reviews results through a compressed documentation interface. The soul of the system is **bi-directional sync**: code, `paper.md`, and `doc/` are always mirrors of each other.

## Migrating an Existing Project

### Full migration (no existing VR structure)

1. **Understand the project** — if the user hasn't explained the experiment flow, goal, and result locations, ask before touching any files.
2. **Run the init script** (idempotent — safe on existing directories).
3. **Move source code → `src/`**, existing results → `results/`.
4. **Update all path references** in code to match the new layout.
5. **Smoke test** — run with minimal config; no data corruption; delete temp files; estimate runtime first (max 10 min).
6. **Populate `doc/`** from code reading (see [Document Maintenance](#document-maintenance) below).
7. **Populate `paper.md` and `README.md`** based on current state.

### Partial migration (some VR structure already exists)

When a project has **some** VR structure but is incomplete or drifted out of sync:

1. **Audit every component** — classify each as conforming / stale / non-conforming / missing. Present the audit table to the user.
2. **Generate a plan grouped by risk** (safe → moderate → caution). Get user approval.
3. **Execute incrementally** — create missing structure first, then move files, then refresh stale docs, then restructure non-conforming files. Verify after each step.
4. **Verify sync state** — confirm `paper.md`, `doc/`, `README.md`, and code are all in sync.

**Key safety rules**: never overwrite meaningful content without showing a diff; use `git mv`; back up before restructuring; merge rather than replace files that have project-specific customizations.

See [reference/migrate.md](reference/migrate.md) for full migration and [reference/partial-migrate.md](reference/partial-migrate.md) for partial migration.

---

## Project Initialization

When the user says "Init folder" or asks to initialize a Vibe Research project:

```bash
bash ~/.cursor/skills/vibe-research/scripts/init.sh
```

See [reference/init.md](reference/init.md) for full details: what files get created, post-init steps if code already exists, and localized paper setup.

## Core Rule: Bi-directional Sync

**This is the highest-priority rule. Never skip it.**

| Trigger | Required action |
|---------|-----------------|
| Code changes at methodological level | Update `paper.md` Method + Result |
| Code changes at implementation level | Update relevant files in `doc/` |
| Edit `paper.md` Method section | Sync the logic back to code |
| Edit a `doc/` design or API page | Sync the change back to code |
| Update `README.md` API/usage | Ensure code matches the documented interface |

**Methodological level** = algorithm design, loss functions, model architecture choices, data processing approaches. NOT variable renaming, formatting, minor refactors.

**Implementation level** = public APIs, key design decisions, architecture changes, new modules, new dependencies, bug fixes with non-obvious root causes.

## Document Maintenance

**Invoked at the end of every agent session.** The `doc/` folder is an agent-maintained developer knowledge base that evolves with the research — the engineering companion to `paper.md`. Bi-directional sync with code; `doc/README.md` (max 120 lines) is the entry point, with sub-pages for architecture, API, decisions, pitfalls, snippets, and resources.

See [reference/doc-maintenance.md](reference/doc-maintenance.md) for the full specification: directory structure, sub-page templates, sync rules, and session-end checklist.

## Principal

`principal.md` records user-stated principles and preferences that the agent should universally follow across sessions. The agent dynamically updates this file when the user expresses a generalizable preference or working principle. Read it at the start of every session; append to it when new principles emerge.

## File Formats and Templates

See [reference/formats.md](reference/formats.md) for exact templates.

Key constraints:
- `paper.md`: four sections only — Abstract, Introduction, Method, Result. Academic style, no code references.
- Research log: `research_log/YYYYMMDD_HH-MM.md`, created after every session.
- `doc/`: bi-directional sync with code; see [Document Maintenance](#document-maintenance) above.

## Directory Size Limit (7-item rule)

Every directory under `src/` and `results/` must contain **no more than 7 items** (files + subdirectories combined). When a directory would exceed 7 items, create semantically named subdirectories and distribute files into them. Apply this rule recursively — if a subdirectory itself would exceed 7 items, split it further.

**For documentation directories** (`doc/`, `research_log/`, etc.): the same 7-item limit applies. Whenever a document is placed inside a subdirectory, its parent directory must contain a document (typically a `README.md` or an index page) that references the subdirectory and lists what's inside, so nothing gets lost. This ensures a reader can always navigate top-down without guessing.

**Why this matters**: 7 ± 2 is the classic working-memory capacity (Miller, 1956). Capping directories at 7 items keeps each level scannable in a single glance — for both humans and AI agents.

## Coding Style

Research code prioritizes readability over abstraction:

- **KISS + YAGNI**: Write the most direct implementation; no generic utilities or future-proofing
- **LoB (Locality of Behavior)**: Keep related logic together. A 60-line function that clearly mirrors a formula's steps is better than 10-file inheritance chains
- **Fail-fast**: Assert dimensions, check for NaN, crash immediately on bad data — crashing is useful debugging information
- **All code comments in English**
- **500-line file limit**: Keep individual code files under 500 lines. If a file grows beyond this, split it into logically cohesive modules. The only exception is when a single class genuinely requires more than 500 lines due to inherent complexity (e.g., a model class with many tightly coupled methods) — in that case, document why the file is long in a comment at the top. This limit keeps files reviewable in one sitting and makes diffs easier to read.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

vibe-research

Directory Structure

SKILL.md

Report

Notice