# PlanAndPatchForGPUHandoff (GUI / No-GPU Cursor Skill)

## Goal
In **Cursor GUI (no GPU)**: turn a user request into a **reviewable plan**, make **CPU-safe code changes**, then produce a **handoff package** that a second `cursor-agent` running on a **GPU Slurm node** can execute without asking more questions.

This skill is designed for workflows like:
- add a benchmark to an eval framework (e.g., VLMEvalKit)
- add an A/B toggle for decoding/inference
- generate reproducible Slurm commands and expected outputs

---

## When to use
- You are chatting in Cursor GUI and **cannot run CUDA / multi-GPU** workloads.
- The work requires **two phases**:
  - **Phase 1 (GUI)**: plan + patch + static checks + handoff
  - **Phase 2 (GPU)**: execute + collect results + report back

---

## Inputs (collect in chat)
Keep questions minimal; ask only what changes the plan materially.

- **Repo root path** on GPU node (or confirm it matches GUI path).
- **Target checkpoint(s)** (exact directory path(s)).
- **Benchmarks/tasks** to run (canonical names).
- **A/B toggle definition**:
  - what is A?
  - what is B?
  - how is it toggled (env var, config key)?
- **Judge requirements** (e.g., OpenAI/Azure key or proxy) if the benchmark needs LLM judging.

If user says “don’t ask me where datasets are”, do not ask dataset paths; instead:
- locate canonical dataset names in code
- document defaults (e.g. VLMEvalKit LMUData root)
- include in GPU checklist “dataset auto-download or LMUData root override”

---

## Hard constraints (must follow)
- **Do not run GPU tasks in GUI**. Only static checks allowed.
- Prefer **official evaluation code** (vendor or import), do not re-implement metrics unless explicitly allowed.
- Handoff must be **copy/paste runnable** on GPU node.
- Handoff must include **what changed / what remains / exact commands / expected outputs**.

---

## Protocol

### Step 1: Create/Update a Plan (in Cursor Plan mode)
Write a short plan with:
- **Deliverables** (files + behaviors)
- **Non-goals** (e.g. “won’t run GPU eval in GUI”)
- **Risks** (judge keys, system deps like LaTeX/Chrome, dataset download)
- **Definition of Done**

### Step 2: Locate official code + canonical task IDs
Use repo search (and web search if needed) to find:
- canonical dataset names in the eval framework registry
- dataset implementation file(s)
- official benchmark repo or vendor location

Record canonical names explicitly in the plan and the handoff.

### Step 3: Implement “CPU-safe” code changes
Typical changes you *can* do in GUI:
- **Dataset wrapper + registration** (no runtime GPU)
- **Config plumbing** (env var → config json)
- **Model toggle plumbing** (config key → model arg → select method)
- **Shell scripts** (export env vars, set output dirs, add usage docs)
- **Docs/Scratchpad** updates

Run only safe checks:
- `python -m py_compile ...` (if environment supports)
- lint/typecheck (CPU-only)
- import smoke tests (CPU-only)
- do not run `torchrun`/`sbatch` in GUI

### Step 4: Produce the Handoff Package (the key deliverable)
The handoff package is **one message** that the GPU-side agent can execute end-to-end.

It contains:
- **Context** (goal, constraints)
- **Repo + commit** (so GPU side runs the right code)
- **What changed** (file list + key toggles)
- **What remains** (TODOs)
- **Exact commands** for A and B
- **Expected outputs** (where results/logs should appear)
- **Debug playbook** (common failures and where to look)

Use the template below.

---

## Handoff Summary Template (copy/paste)

```text
## Context
- Goal:
- Repo_root_on_gpu:
- Commit (git rev-parse HEAD):
- Constraints:

## What changed (already merged in repo)
- Files_modified:
  - ...
- New_files:
  - ...
- New_or_changed_env_vars:
  - ...
- Canonical_benchmark_names:
  - ...
- Notes:
  - (e.g., “GUI can’t run GPU; execute on Slurm node”)

## What remains (still to do)
- [ ] ...

## GPU Execution Checklist
### 0) Environment
- Conda_env:
- Python/torch versions (expected):
- CUDA requirement:
- Judge settings (if required):
- Dataset root (if relevant):

### 1) Sanity checks (fast)
- cd <repo_root>
- python -c "import ..."
- ls <checkpoint_dir>

### 2) Main run (A/B)
- A (baseline) command:
  <paste command>
- B (treatment) command:
  <paste command>

### 3) Expected outputs
- Work_dir/output_dir:
- Logs:
- Results (CSV/JSON):

## Failure modes & debugging
- If judge key missing:
  - symptom:
  - fix:
- If dataset missing:
  - symptom:
  - fix:
- If import fails:
  - symptom:
  - fix:
```

---

## “GPU Execution Block” Template (copy/paste)
This is the block you paste into the GPU-node `cursor-agent` CLI session.

```bash
set -euo pipefail

# 0) repo + env
cd "<REPO_ROOT_ON_GPU>"
source ~/.bashrc
conda activate "<CONDA_ENV>"

python --version
nvidia-smi || true

# 1) run A
export USE_SPECULATIVE=0
export MODEL_PATH="<CHECKPOINT_DIR>"
export USE_MDM=1
export TASKS="<TASKS_SPACE_SEPARATED>"
bash chengyue_script/dvlm/evaluation/vlmeval/run_all_benchmarks.sh

# 2) run B
export USE_SPECULATIVE=1
bash chengyue_script/dvlm/evaluation/vlmeval/run_all_benchmarks.sh
```

---

## “GPU Report-back” Template (what GPU agent returns)

```text
## GPU Run Report
- Repo_root:
- Commit:
- Node/job_id:
- Conda_env:

## Commands executed
- A:
- B:

## Outputs
- A_output_dir:
- B_output_dir:
- Key result files:
  - ...

## Metrics snapshot
- A scores:
- B scores:
- Speed/latency notes:

## Issues (if any)
- Root cause:
- Logs:
- Proposed next fix:
```


