---
name: ralph-wiggum-cucu
description: >
  Tích hợp kỹ thuật Ralph Wiggum vào dự án CuCu Note để cho phép agent chạy tự động nhiều vòng (loop),
  lưu trạng thái bằng file + git thay vì context, và build/tinh chỉnh codebase theo checklist trong RALPH_TASK.md.
---

# Ralph Wiggum cho CuCu Note

Bạn đang làm việc trong codebase **CuCu Note**. Skill này giúp bạn **hiểu và sử dụng** bộ script Ralph Wiggum
(`ralph-wiggum-cursor` của agrimsingh) cùng với Cursor Agent để:

- Chạy agent nhiều vòng (loop) một cách **tự động**.
- Lưu “trí nhớ” vào **file + git** thay vì nhét hết vào context.
- Dùng checklist trong `RALPH_TASK.md` để từ từ build / refactor codebase CuCu.

> Lưu ý: **Skill này không tự copy script Ralph vào repo.**
> Bạn (người dùng) sẽ cài script từ GitHub ở môi trường mà bạn muốn chạy (local/CI).

---

## 1. Khi nào dùng skill này?

- Khi muốn **tự động hoá** một chuỗi việc dài (A → Z) cho CuCu Note, ví dụ:
  - Clean / refactor backend FastAPI theo rules `cucu-python-backend` + `backend-python`.
  - Chuẩn hoá API `memos` + `chatbot` theo `cucu-api-design`.
  - Build thêm module/feature mới nhiều bước, cần chạy nhiều vòng agent.
- Khi bạn muốn:
  - Tách **“trạng thái công việc”** khỏi context của Cursor,
  - Tận dụng **git + file** làm nguồn truth,
  - Và có thể chạy agent **lặp lại / song song** ở một nơi khác (local, server, CI).

---

## 2. Chuẩn bị: Cài Ralph ở môi trường chạy (local/CI)

> Thao tác này bạn làm **ở máy chạy script**, không nhất thiết bên trong repo CuCu.

1. Đảm bảo repo đã `git init` và có commit bình thường.
2. Chạy installer của Ralph (theo README của `agrimsingh/ralph-wiggum-cursor`), ví dụ:

```bash
cd /duong-dan-toi-repo-cua-ban
curl -fsSL https://raw.githubusercontent.com/agrimsingh/ralph-wiggum-cursor/main/install.sh | bash
```

Sau khi chạy xong, trong repo sẽ có:

- `.cursor/ralph-scripts/` – chứa các script:
  - `ralph-setup.sh`, `ralph-loop.sh`, `ralph-once.sh`, `ralph-parallel.sh`, v.v.
- `.ralph/` – thư mục state (progress, guardrails, logs).
- `RALPH_TASK.md` – file định nghĩa task (bạn chỉnh lại cho phù hợp CuCu).

> Skill này giả định các script Ralph đã nằm ở: `.cursor/ralph-scripts/`.

---

## 3. Thiết kế `RALPH_TASK.md` cho CuCu Note

Khi làm việc với CuCu, hãy thiết kế task theo kiểu **checklist rõ ràng, testable**.
Ví dụ skeleton:

```md
---
task: Harden CuCu Note backend & agent
test_command: "cd backend && pytest || echo 'no tests yet'"
---

# Task: Harden CuCu backend & agent

Mục tiêu:
- Làm sạch backend Python/FastAPI của CuCu.
- Tối ưu agent (LangGraph + tools) theo skill `cucu-python-backend` và `cucu-api-design`.

## Success Criteria

1. [ ] Backend Python tuân thủ rule `backend-python` (singleton, ruff + black, cấu trúc api/).
2. [ ] Agent (graph + tools) không còn import/logic StarRocks, chỉ dùng MongoDB.
3. [ ] `memo_retrieval_tool` dùng async embedding, xử lý ID vector search an toàn (không trả kết quả sai).
4. [ ] Chatbot API (`/api/agent/chat`, `/api/history/...`) dùng `conversation_manager` singleton chuẩn.
5. [ ] Tất cả file backend mới sửa đã qua `ruff check . --fix && black .`.

## Context / Gợi ý cho Agent

- Luôn đọc các skill:
  - `.cursor/skills/cucu-python-backend/SKILL.md`
  - `.cursor/skills/cucu-api-design/SKILL.md`
  - `.cursor/skills/cucu-testing/SKILL.md`
  - `.cursor/rules/backend-python.md`
- Không tự ý thay đổi triết lý UX của CuCu (sổ nháp số, đơn giản).
- Ưu tiên:
  - Dùng singleton cho những thành phần dài hạn (MongoDBClient, CANIFAGraph, ConversationManager).
  - Tối ưu N+1 query / vector search nhưng **không phá API contract** với frontend.
```

Bạn có thể tạo nhiều nhóm task khác nhau (backend, frontend, e2e, docs) và chạy Ralph từng đợt.

---

## 4. Cách chạy Ralph với CuCu

### 4.1. Chạy tuần tự (sequential)

Ở thư mục project (đã có `.cursor/ralph-scripts/` + `RALPH_TASK.md`):

```bash
./.cursor/ralph-scripts/ralph-setup.sh
```

Chọn model, số vòng lặp, options (branch, PR, v.v.).

Hoặc CI/script:

```bash
./.cursor/ralph-scripts/ralph-loop.sh -n 20 -m gpt-5.2-high
```

### 4.2. Chạy song song (parallel) cho nhiều task CuCu

Ví dụ: muốn 3 agent làm nhiều tiêu chí trong `RALPH_TASK.md` cùng lúc:

```bash
./.cursor/ralph-scripts/ralph-loop.sh --parallel --max-parallel 3
```

Hoặc tích hợp với branch/PR:

```bash
./.cursor/ralph-scripts/ralph-loop.sh --parallel --max-parallel 3 --branch feature/cucu-hardening --pr -y
```

---

## 5. Hướng dẫn cho Agent (khi skill này được load)

Khi skill `ralph-wiggum-cucu` có trong context, hãy:

1. **Không cố gắng tự viết lại logic Ralph** – chỉ:
   - Đọc/hiểu cấu trúc `.ralph/`, `RALPH_TASK.md`.
   - Gợi ý cho người dùng cách chỉnh `RALPH_TASK.md` / cấu hình script.
2. Khi người dùng hỏi “dùng Ralph để chạy A→Z cho CuCu”, hãy:
   - Giải thích rõ giới hạn:
     - Ralph + Cursor có thể build/refactor **gần như full** dựa trên task,
     - Nhưng chất lượng phụ thuộc vào `RALPH_TASK.md` và review thủ công.
   - Đề xuất ví dụ checklist cụ thể cho case đó (backend, frontend, test…).
3. Tuyệt đối **không tự thêm script shell** vào repo CuCu nếu người dùng không yêu cầu rõ.
   - Chỉ thêm/chỉnh **file cấu hình** (SKILL.md, hướng dẫn) khi được yêu cầu.

---

## 6. Best practices dùng Ralph với CuCu

- **Luôn chạy Ralph trên branch riêng**, sau đó mở PR và review diff bằng mắt.
- **Nhỏ hoá task**:
  - Thay vì “Refactor toàn bộ CuCu”, hãy chia thành:
    - Backend core,
    - Agent & tools,
    - Frontend filters & AboutCuCu,
    - E2E/Playwright, v.v.
- Dùng `guardrails.md` để ghi lại:
  - Những lỗi agent hay mắc với CuCu (ví dụ: sửa nhầm file cấu hình, động vào auth…),
  - Các “Sign” để vòng sau tránh lặp lại.

Skill này chỉ là **bridge mô tả** giữa CuCu Note và bộ công cụ Ralph Wiggum – toàn bộ thực thi thật sự diễn ra
ở môi trường mà người dùng cài `ralph-wiggum-cursor`.


