@su-record/vibe 2.9.20 → 2.9.22

package/skills/vibe-contract/SKILL.md

@@ -9,18 +9,18 @@ chain-next: []
 
 # vibe.contract — API Contract Drift Detection
 
-**Purpose**: SPEC에 적힌 외부 계약과 실제 구현이 어긋나면 즉시 잡는다. 테스트 통과 ≠ 계약 준수.
+**Purpose**: catch divergence between the SPEC's external contract and the actual implementation. Passing tests ≠ contract preserved.
 
 ## Why this exists
 
-바이브코딩의 숨은 약점: 구현이 자라면서 SPEC에 명시된 응답 shape에서 조용히 벗어난다. 시나리오 테스트는 통과해도 **외부 소비자는 깨진다**. 사람이 매번 SPEC을 비교하기엔 마찰이 크므로 기계화.
+Hidden vibe-coding weakness: as the implementation grows, response shapes drift away from what the SPEC documents. Scenario tests still pass — but **external consumers break**. Manual SPEC-vs-code review is high-friction, so mechanize it.
 
 ## Storage Contract
 
 ```
 .claude/vibe/contracts/
-  <feature>.md             # 계약 SSOT (SPEC에서 추출)
-  <feature>.snapshot.md    # 구현 스냅샷 (마지막 check 시점)
+  <feature>.md             # contract SSOT (extracted from SPEC)
+  <feature>.snapshot.md    # implementation snapshot (last check)
 ```
 
 ### Contract frontmatter schema
@@ -30,9 +30,9 @@ chain-next: []
 feature: string
 extracted-from: .claude/vibe/specs/<feature>.md
 extracted-at: ISO-8601
-source-spec-hash: sha256  # SPEC 변경 감지용
+source-spec-hash: sha256  # for change detection
 endpoints:
-  - id: unique-kebab-id         # 예: get-user-by-id
+  - id: unique-kebab-id         # e.g. get-user-by-id
     kind: http | graphql | event | function
     # http
     method: GET | POST | PUT | DELETE | PATCH
@@ -64,75 +64,75 @@ endpoints:
 
 ## Subcommands
 
-### 1. `extract <feature>` — SPEC에서 계약 추출
+### 1. `extract <feature>` — pull contract out of the SPEC
 
-**단계**:
-1. SPEC 파일 로드 (single file or split folder)
-2. 다음 섹션을 순서대로 탐색:
+**Steps**:
+1. Load SPEC file (single file or split folder)
+2. Search sections in this order:
    - `## API` / `## Endpoints` / `## Interface` / `## Contract`
-   - Markdown 테이블 (method/path/request/response 헤더)
-   - 코드 블록 안의 OpenAPI/JSON Schema 스니펫
-3. 추출 실패(해당 섹션 없음) → **에러 없이 `no-contract` 상태 기록 후 종료**. 모든 feature가 API를 갖진 않음.
-4. 추출 성공 → frontmatter 구조로 변환
-5. `source-spec-hash`: SPEC 파일 내용의 sha256 (다음 extract 시 변경 감지)
-6. `.claude/vibe/contracts/<feature>.md` 저장 (기존 파일이 있고 hash가 같으면 **no-op**)
-
-**주의**: 추출은 LLM 파싱. 신뢰도 낮은 필드는 `# unconfirmed` 주석 달아서 사용자가 검토 가능하게.
-
-### 2. `check <feature>` — 계약 vs 구현 비교
-
-**단계**:
-1. `.claude/vibe/contracts/<feature>.md` 로드. 없으면 **먼저 extract 제안**.
-2. 각 endpoint에 대해 구현 탐색:
-   - http: 프레임워크 감지 (Express, Fastify, Next.js API routes, Hono, ...)
-   - graphql: resolver 파일 찾기
-   - event: 프로듀서/컨슈머 코드
-   - function: 모듈 export
-3. 구현 시그니처/스키마를 추출 → 계약과 비교
-4. Drift 분류 (severity 표는 command file 참고)
-5. 스냅샷 저장: `.claude/vibe/contracts/<feature>.snapshot.md` (현재 구현 상태)
-
-### 3. `diff <feature>` — 이전 스냅샷 대비 변경만
-
-**단계**:
-1. `.snapshot.md`가 없으면 "첫 실행" 안내 후 종료
-2. 현재 구현 재추출 vs 기존 스냅샷 비교
-3. **변경된 필드만** 출력 (ASCII diff 형식):
+   - Markdown tables (method/path/request/response headers)
+   - OpenAPI/JSON Schema snippets inside code blocks
+3. Extraction failure (no such section) → **exit cleanly with `no-contract` state**. Not every feature has an API.
+4. Success → convert to the frontmatter structure
+5. `source-spec-hash`: sha256 of SPEC content (for next extract to detect change)
+6. Save to `.claude/vibe/contracts/<feature>.md` (no-op if file exists with the same hash)
+
+**Caveat**: extraction is LLM-driven. Mark low-confidence fields with `# unconfirmed` so the user can review.
+
+### 2. `check <feature>` — contract vs implementation
+
+**Steps**:
+1. Load `.claude/vibe/contracts/<feature>.md`. If missing → **suggest extract first**.
+2. For each endpoint, find implementation:
+   - http: detect framework (Express, Fastify, Next.js API routes, Hono, ...)
+   - graphql: locate resolver files
+   - event: producer/consumer code
+   - function: module export
+3. Extract implementation signature/schema → compare against contract
+4. Classify drift (severity table in command file)
+5. Persist snapshot at `.claude/vibe/contracts/<feature>.snapshot.md` (current implementation state)
+
+### 3. `diff <feature>` — changes since last snapshot
+
+**Steps**:
+1. If `.snapshot.md` does not exist → say "first run" and exit
+2. Re-extract current implementation; compare to existing snapshot
+3. Output **only changed fields** in ASCII diff form:
    ```
    endpoints/get-user-by-id/response/200:
      - email: string
-     + email: string | null   ← nullability 추가 (P1 breaking)
-     + phoneNumber: string    ← 신규 필드 (P3 safe)
+     + email: string | null   ← nullability added (P1 breaking)
+     + phoneNumber: string    ← new field (P3 safe)
    ```
-4. 드리프트 있으면 `/vibe.regress register --from-contract` 자동 호출
+4. On any drift, auto-call `/vibe.regress register --from-contract`
 
 ## Drift Severity Matrix
 
-(command file의 표와 동일 — 변경 시 양쪽 갱신)
+(matches command file — keep both in sync on edits)
 
 ## Integration Points
 
 ### From /vibe.spec
 
-SPEC 작성 완료 직후 자동 호출:
+Auto-invoke right after the SPEC is written:
 ```
 Load skill `vibe-contract` with: extract <feature>
 ```
-실패해도 `/vibe.spec`은 계속 진행 (계약 추출은 옵션). 단 성공 시 `/vibe.run`이 이 계약을 참조.
+Failure does not stop `/vibe.spec` (extraction is optional). On success, `/vibe.run` references this contract.
 
 ### From /vibe.verify
 
-모든 scenario pass 후 자동 체인:
+After all scenarios pass:
 ```
 Load skill `vibe-contract` with: check <feature>
 ```
-- drift 없음 → verify 통과 유지
-- P1 drift → verify 실패로 강등, regress 자동 등록
-- P2/P3 drift → 경고만, verify 통과 유지
+- no drift → verify still passes
+- P1 drift → demote verify to fail; auto-register
+- P2 / P3 drift → warning only; verify still passes
 
 ### To /vibe.regress
 
-P1 drift 발견 시:
+On P1 drift:
 ```
 Load skill `vibe-regress` with:
   subcommand: register --from-contract
@@ -143,15 +143,15 @@ Load skill `vibe-regress` with:
 
 ## Framework Detection Rules
 
-HTTP framework 감지 순서:
-1. `package.json` dependencies에서: `next` → Next.js API routes
+HTTP framework detection order:
+1. `package.json` dependencies: `next` → Next.js API routes
 2. `fastify` → Fastify
 3. `express` → Express
 4. `hono` → Hono
 5. `@nestjs/core` → NestJS
-6. 감지 실패 → user에게 질문 후 manual mapping
+6. None detected → ask user for manual mapping
 
-감지 후 각 프레임워크의 **라우트 정의 패턴**을 Grep으로 찾아 endpoint 매핑:
+After detection, grep for each framework's **route definition pattern** to map endpoints:
 - Next.js: `pages/api/**` or `app/api/**/route.ts`
 - Express: `app.get|post|put|delete|patch\(`
 - Fastify: `fastify.get|post|...` or route configuration
@@ -159,8 +159,8 @@ HTTP framework 감지 순서:
 
 ## Done Criteria
 
-- [ ] `extract`가 API 섹션 없는 SPEC에서 에러 내지 않음
-- [ ] `source-spec-hash` 기반 re-extract 스킵
-- [ ] `check`는 각 drift에 severity + 위치(file:line) 명시
-- [ ] P1 drift는 100% `/vibe.regress` 자동 등록
-- [ ] 프레임워크 감지 실패 시 silently skip 금지 — 반드시 user 질문
+- [ ] `extract` does not error on SPEC without an API section
+- [ ] `source-spec-hash`-based re-extract is a no-op when unchanged
+- [ ] `check` reports each drift with severity + location (file:line)
+- [ ] P1 drift always invokes `/vibe.regress`
+- [ ] On framework detection failure, ask the user — do not silently skip

package/skills/vibe-regress/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vibe-regress
 tier: core
-description: "Regression test auto-evolution. Registers bugs (auto from /vibe.verify failures or manual), generates preventive vitest/jest files from bug records, clusters repeated patterns (3+ same root-cause-tag) into shared tests, and imports historical `fix:` commits from git log. Storage: .claude/vibe/regressions/<slug>.md. Must use this skill when user runs /vibe.regress, when /vibe.verify produces a failure, or when the user says 'don't let this happen again' / '이 버그 다시는' / 'regression test' / '회귀 테스트'."
+description: "Regression test auto-evolution. Registers bugs (auto from /vibe.verify failures or manual), generates preventive vitest/jest files from bug records, clusters repeated patterns (3+ same root-cause-tag) into shared tests, and imports historical `fix:` commits from git log. Storage: .claude/vibe/regressions/<slug>.md. Must use this skill when user runs /vibe.regress, when /vibe.verify produces a failure, or when the user says 'don't let this happen again' / 'regression test' / '회귀 테스트'."
 triggers: [regress, regression, "회귀", "다시는", "반복 버그", "fix commit"]
 priority: 70
 chain-next: []
@@ -9,92 +9,92 @@ chain-next: []
 
 # vibe.regress — Regression Auto-Evolution
 
-**Purpose**: 같은 버그를 두 번 잡지 않는다. 버그를 잡을 때마다 예방 테스트가 자라난다.
+**Purpose**: never fix the same bug twice. Each fix grows a preventive test.
 
 ## Why this exists
 
-바이브코딩의 고전적 약점: LLM이 같은 클래스의 버그를 매번 새로 만든다. 회귀 테스트는 이를 기계적으로 막는 유일한 장치. 단, 사람이 매번 회귀 테스트를 쓰면 건너뛰게 됨 — 그래서 자동화.
+A classic vibe-coding weakness: LLMs reintroduce bugs of the same class. Regression tests are the only mechanical defense. But if the human has to write the test every time, it gets skipped — so automate.
 
 ## Storage Contract
 
 ```
 .claude/vibe/regressions/
-  <bug-slug>.md       # 하나의 버그 = 하나의 파일
-  _cluster-<tag>.md   # cluster 서브커맨드가 생성한 공통 테스트 설계
+  <bug-slug>.md       # one file per bug
+  _cluster-<tag>.md   # shared-test design produced by `cluster`
 ```
 
-### Frontmatter schema (엄격)
+### Frontmatter schema (strict)
 
 ```yaml
-slug: string            # kebab-case, 글로벌 유일
-symptom: string         # 1줄, 사용자 관점
-root-cause-tag: enum    # 아래 허용 태그만
-fix-commit: string      # git hash (없으면 "pending")
-test-path: string       # 생성된 테스트 파일 경로 (없으면 "pending")
+slug: string            # kebab-case, globally unique
+symptom: string         # one line, user-facing
+root-cause-tag: enum    # only the allowed tags below
+fix-commit: string      # git hash (or "pending")
+test-path: string       # generated test file path (or "pending")
 status: open | test-generated | resolved
 registered: YYYY-MM-DD
-feature: string         # 연관 feature 이름 (SPEC과 매칭)
+feature: string         # related feature name (matches SPEC)
 ```
 
 ### Allowed `root-cause-tag` values
 
-클러스터링의 기반이므로 **미리 정의된 집합만** 사용:
+Clustering depends on this, so use **only the predefined set**:
 
-- `timezone` — 시간대/DST/off-by-one
-- `nullability` — null/undefined/empty 처리
-- `concurrency` — race condition, 동시성
-- `boundary` — off-by-one, edge value
-- `encoding` — charset, URL encoding, escape
-- `validation` — 입력 검증 누락
-- `auth` — 인증/권한 로직
-- `state-sync` — 클라이언트/서버 상태 불일치
-- `integration` — 외부 API 호출 실패
-- `type-narrow` — TypeScript 타입 좁히기 실수
-- `other` — 위에 안 맞을 때 (나중에 새 태그 추가)
+- `timezone` — timezone / DST / off-by-one in time
+- `nullability` — null / undefined / empty handling
+- `concurrency` — race conditions
+- `boundary` — off-by-one, edge values
+- `encoding` — charset, URL encoding, escaping
+- `validation` — missing input validation
+- `auth` — authn/authz logic
+- `state-sync` — client/server state mismatch
+- `integration` — external API call failure
+- `type-narrow` — TypeScript type narrowing mistake
+- `other` — when nothing fits (add new tags later)
 
-**규칙**: 새 태그가 필요하면 기존 태그에 억지로 맞추지 말고 `other`로 등록한 뒤, `other`가 3개 이상 쌓이면 사용자에게 태그 추가를 제안.
+**Rule**: if a new tag is needed, do not force-fit into an existing one — register as `other`. Once `other` reaches 3 entries, propose adding a new tag.
 
 ## Subcommands
 
-### 1. `register "<symptom>"` — 수동 등록
+### 1. `register "<symptom>"` — manual registration
 
-대부분은 자동 호출되므로 수동 사용은 드뭅니다 (verify 실패 밖에서 발견된 버그, 또는 프로덕션 이슈용).
+Most calls are automatic; manual use is rare (bugs found outside `/vibe.verify`, or production incidents).
 
-**단계**:
-1. `getCurrentTime`으로 오늘 날짜 확보
-2. `git log -1 --format=%H`으로 현재 커밋 해시 (fix-commit 후보)
-3. Claude가 대화로 다음을 뽑아냄:
+**Steps**:
+1. `getCurrentTime` for today's date
+2. `git log -1 --format=%H` for current commit hash (fix-commit candidate)
+3. Conversation extracts:
    - Reproduction steps (Given/When/Then)
-   - Root cause 1문단
-   - Fix 설명
-4. `root-cause-tag`는 허용 집합에서 **자동 추론 후 사용자에게 확인**. 애매하면 `other`.
-5. slug 생성: symptom에서 핵심어 → kebab-case, 충돌 시 `-2` 접미사
-6. `.claude/vibe/regressions/<slug>.md` 작성 (status: `open`)
-
-### 2. `generate <slug>` — 예방 테스트 생성
-
-**단계**:
-1. bug 파일 읽기
-2. 테스트 스택 감지:
-   - `package.json`의 `devDependencies`에서 `vitest` > `jest` 순
-   - 둘 다 없으면 **user에게 질문 후 중단**
-3. 테스트 위치 결정:
-   - feature의 구현 파일 옆 `__tests__/` 또는
-   - 프로젝트의 기존 test dir (vitest config.test.include 확인)
-4. 파일명: `<original-file>.regression.test.ts`
-5. 내용: `templates/test-vitest.md` 또는 `templates/test-jest.md` 템플릿에서 치환
-6. bug 파일 frontmatter 업데이트: `test-path`, `status: test-generated`
-7. **생성 후 즉시 테스트 실행** — 실패해야 정상 (아직 수정 안 됨이면) 또는 통과 (수정 완료됨이면). 결과를 frontmatter에 기록.
-
-### 3. `list` — 미해결 목록
+   - Root-cause paragraph
+   - Fix description
+4. `root-cause-tag` is **inferred from the allowed set, then confirmed with the user**. If unclear → `other`.
+5. Generate slug: kebab-case keywords from the symptom; on collision append `-2`
+6. Write `.claude/vibe/regressions/<slug>.md` (status: `open`)
+
+### 2. `generate <slug>` — generate preventive test
+
+**Steps**:
+1. Read bug file
+2. Detect test stack:
+   - From `package.json` `devDependencies`: prefer `vitest` over `jest`
+   - If neither → **ask user, then stop**
+3. Decide test location:
+   - Sibling `__tests__/` next to the implementation file, OR
+   - The project's existing test dir (vitest config `test.include`)
+4. File name: `<original-file>.regression.test.ts`
+5. Body: render `templates/test-vitest.md` or `templates/test-jest.md`
+6. Update bug frontmatter: `test-path`, `status: test-generated`
+7. **Run the test immediately** — should fail (if not yet fixed) or pass (if fixed). Record outcome in frontmatter.
+
+### 3. `list` — open items
 
 ```
-/vibe.regress list                 # status != resolved 전부
-/vibe.regress list --feature login # feature별
-/vibe.regress list --tag timezone  # tag별
+/vibe.regress list                 # status != resolved
+/vibe.regress list --feature login # filter by feature
+/vibe.regress list --tag timezone  # filter by tag
 ```
 
-터미널 표:
+Terminal table:
 
 ```
 SLUG                              FEATURE   TAG         STATUS           AGE
@@ -102,36 +102,36 @@ login-jwt-expiry-off-by-one       login     timezone    test-generated   3d
 cart-stock-race-double-deduct     cart      concurrency open             1d
 ```
 
-### 4. `import` — git log 역추적
+### 4. `import` — backfill from git log
 
-**단계**:
+**Steps**:
 1. `git log --grep='^fix:' --format='%H|%s|%ci' --since=<last-import-date>`
-   - `last-import-date`는 `.claude/vibe/regressions/.import-cursor` 파일에서 읽음 (없으면 90일 전)
-2. 각 커밋에 대해:
-   - 이미 같은 `fix-commit`을 가진 bug 파일이 있으면 **스킵**
-   - 없으면 커밋 메시지/diff에서 symptom + root-cause-tag 추론 (LLM 호출)
-   - 신규 bug.md 작성 (status: `resolved` — 이미 고쳐졌으므로)
-3. 완료 후 `.import-cursor` 갱신
-4. 새로 import된 항목에 대해 사용자에게 `generate` 제안
+   - `last-import-date` lives in `.claude/vibe/regressions/.import-cursor` (defaults to 90 days ago)
+2. For each commit:
+   - If a bug file with the same `fix-commit` already exists → **skip**
+   - Otherwise infer symptom + root-cause-tag from message/diff (LLM call)
+   - Write a new bug file (status: `resolved` — already fixed)
+3. Update `.import-cursor`
+4. Suggest `generate` for newly imported entries
 
-**주의**: `fix:` 커밋이 아닌 일반 커밋은 **무시**. Conventional Commits 규약을 사용하지 않는 프로젝트는 `--grep-pattern` 옵션으로 오버라이드.
+**Note**: only `fix:` commits are considered. Projects not using Conventional Commits can override with `--grep-pattern`.
 
-### 5. `cluster` — 반복 패턴 승격
+### 5. `cluster` — promote recurring patterns
 
-**단계**:
-1. 모든 bug 파일의 `root-cause-tag` 집계
-2. **같은 태그가 3개 이상**이면 cluster 후보
-3. 각 후보에 대해:
-   - 3개 bug의 reproduction을 LLM에게 주고 "공통 원인과 공통 테스트 케이스"를 추출
-   - `_cluster-<tag>.md` 파일 생성 (기존 bug 파일들의 slug를 링크)
-   - 공통 테스트 skeleton을 `<project-test-dir>/_cluster-<tag>.regression.test.ts`로 제안 (사용자 승인 후 생성)
-4. 클러스터 생성 시 원본 bug 파일은 **삭제하지 않음** — 이력 보존
+**Steps**:
+1. Aggregate `root-cause-tag` across all bug files
+2. **A tag with ≥3 entries** becomes a cluster candidate
+3. For each candidate:
+   - Feed the 3 reproductions to an LLM to extract the common cause and shared test cases
+   - Write `_cluster-<tag>.md` (links to the original bug slugs)
+   - Propose a shared test skeleton at `<project-test-dir>/_cluster-<tag>.regression.test.ts` (create only with user approval)
+4. Original bug files are **not deleted** — history preserved
 
-**중요**: cluster는 자동 실행 안 됨. 사용자가 명시적으로 호출해야 함 (과도한 추상화 방지).
+**Important**: `cluster` is never automatic. Users invoke it explicitly to avoid premature abstraction.
 
 ## Integration with /vibe.verify
 
-`/vibe.verify` 실패 시 verify가 다음을 호출:
+When `/vibe.verify` fails it calls:
 
 ```
 Load skill `vibe-regress` with: register --from-verify
@@ -141,34 +141,34 @@ Load skill `vibe-regress` with: register --from-verify
   <location>: {file:line}
 ```
 
-`--from-verify` 플래그 동작:
+`--from-verify` behavior:
 - symptom = scenario name + error summary
-- feature = 전달된 feature name
-- root-cause-tag = error pattern에서 자동 추론 (애매하면 `other`)
+- feature = forwarded feature name
+- root-cause-tag = inferred from error pattern (default `other` if unclear)
 - status = `open`
-- **사용자 확인 없이 등록** (verify 실패 상황은 이미 주의 집중 중이라 마찰 최소화가 중요)
+- **Skip user confirmation** — the user is already attentive in a verify-failure context, and friction must be minimized
 
 ## Integration with /vibe.run
 
-`/vibe.run "<feature>"` 시작 시:
+At the start of `/vibe.run "<feature>"`:
 
-1. `ls .claude/vibe/regressions/*.md`에서 `feature: <feature-name>` + `status != resolved` 필터
-2. 미해결 있으면 경고:
+1. Filter `.claude/vibe/regressions/*.md` for `feature: <feature-name>` + `status != resolved`
+2. If any open items:
    ```
    ⚠️  Open regressions for this feature:
      - login-jwt-expiry-off-by-one (timezone, 3d old)
      - login-session-leak (auth, 1w old)
-   
+
    Fix these before adding new behavior? [y/N]
    ```
-3. `y` → `/vibe.regress generate`로 체인 (미생성 항목)
-4. `N` → 계속 진행 (ultrawork 모드는 자동 `N` + TODO 기록)
+3. `y` → chain to `/vibe.regress generate` for items not yet test-generated
+4. `N` → continue (ultrawork mode auto-`N`, records TODO)
 
 ## Done Criteria
 
-- [ ] 서브커맨드가 지정 없이 호출되면 usage 표시
-- [ ] frontmatter 스키마 엄격 준수 (누락 필드 있으면 거부)
-- [ ] `root-cause-tag`가 허용 집합 외 값이면 경고 + `other`로 강제
-- [ ] `generate` 후 테스트를 **실제로 실행**하여 결과 검증
-- [ ] `import`는 중복 스킵 (fix-commit 해시 기준)
-- [ ] `cluster`는 3개 미만이면 아무것도 안 함 (false positive 방지)
+- [ ] Subcommand-less invocation prints usage
+- [ ] Frontmatter schema strictly enforced (missing fields rejected)
+- [ ] `root-cause-tag` outside the allowed set → warn + force `other`
+- [ ] After `generate`, the test is **actually run** to verify
+- [ ] `import` deduplicates by `fix-commit` hash
+- [ ] `cluster` does nothing under 3 entries (false-positive guard)

package/skills/vibe-spec/SKILL.md

@@ -400,21 +400,21 @@ Read ~/.claude/vibe/languages/typescript-react.md
 Before spawning any research agents, check for a prior persisted dataset:
 
 ```bash
-# Slug = kebab-case of feature/topic, max 50 chars
+# Slug = kebab-case of the feature/topic, max 50 chars
 ls .claude/vibe/research/<slug>/paper.md 2>/dev/null
 ```
 
 **If `paper.md` exists:**
 1. Read `.claude/vibe/research/<slug>/paper.md`
 2. Read `.claude/vibe/research/<slug>/awesome-list.md` (if present)
-3. Inject the **Findings**, **Recommendation**, and **Security considerations** sections into SPEC Context verbatim, prefixed with `> Source: .claude/vibe/research/<slug>/paper.md (cached {{FILE_MTIME}})`
+3. Inject the **Findings**, **Recommendation**, and **Security considerations** sections verbatim into SPEC Context, prefixed with `> Source: .claude/vibe/research/<slug>/paper.md (cached {{FILE_MTIME}})`
 4. **Skip step 3** (parallel research) entirely — do not re-run GPT/Gemini/Claude agents
-5. Show message: `✅ Research cache hit: <slug> (saved ~30s of LLM calls)`
+5. Print: `✅ Research cache hit: <slug> (saved ~30s of LLM calls)`
 
 **Cache invalidation:**
-- User passes `--refresh-research` → delete dir, run step 3 fresh
-- `paper.md` mtime older than 30 days → warn user, ask to refresh or reuse
-- Stack in `paper.md` header differs from current stack → auto-refresh
+- User passes `--refresh-research` → delete dir, rerun step 3 from scratch
+- `paper.md` mtime older than 30 days → warn the user, ask to refresh or reuse
+- `stack` in `paper.md` frontmatter differs from current stack → auto-refresh
 
 **If `paper.md` does NOT exist:**
 Proceed to step 3. After step 3 completes, the synthesizer **must** write the 3 artifacts (see `parallel-research/orchestrator.md` Phase 5) so the next `/vibe.spec` run on this topic hits the cache.
@@ -565,19 +565,19 @@ Task(subagent_type="ui-layout-architect",
 
 ### 3.9 Persist Research Cache (AFTER research completes, BEFORE SPEC write)
 
-> The "no Write during research" rule (step 3) does **not** apply here — research is done, artifacts are safe to persist.
+> The "no Write during research" rule from step 3 does **not** apply here — research is done; artifacts are safe to persist.
 
-After parallel research + UI/UX intelligence complete and before writing the SPEC, save the merged research into `.claude/vibe/research/<slug>/`:
+After parallel research + UI/UX intelligence complete, before writing the SPEC, save the merged research to `.claude/vibe/research/<slug>/`:
 
 1. Compute slug: kebab-case of feature name, max 50 chars
 2. Write **three files** using templates from `parallel-research/templates/`:
    - `.claude/vibe/research/<slug>/synthesis.md` — raw merged findings (all agent outputs)
-   - `.claude/vibe/research/<slug>/awesome-list.md` — curated links/repos/patterns (each entry needs a one-line "why"; drop entries without it)
+   - `.claude/vibe/research/<slug>/awesome-list.md` — curated links/repos/patterns (every entry needs a one-line "why"; drop entries without one)
    - `.claude/vibe/research/<slug>/paper.md` — structured survey (Abstract → Background → Method → Findings → Recommendation → Security → References)
-3. Include a frontmatter header in `paper.md` with `stack:` field so step 2.9 can detect stack drift
-4. If the directory already exists (user ran `--refresh-research`), overwrite
+3. Include a frontmatter header in `paper.md` with a `stack:` field so step 2.9 can detect stack drift
+4. If the directory already exists (user passed `--refresh-research`), overwrite
 
-This makes the next `/vibe.spec` or `/vibe.research` invocation on the same topic hit the cache at step 2.9.
+This makes the next `/vibe.spec` (or future `/vibe.research`) invocation on the same topic hit the cache at step 2.9.
 
 ### 4. Write SPEC Document (PTCF Structure)