@su-record/vibe 3.0.0 → 3.2.0

package/skills/vibe.figma/references/step-algorithms.md

@@ -0,0 +1,204 @@
+# Branch 3 (WRITE) Step Algorithms — Full Reference
+
+> Loaded by vibe.figma SKILL.md Branch 3 (`--create*`) Step A/B/C/D/D↔E gate/E/F bodies for the full incremental/idempotent algorithms, message templates, and checklists.
+
+## createMode별 실행 매트릭스
+
+| Step | full | storyboard | design |
+|---|---|---|---|
+| A. plan.md 파싱 | ✅ | ✅ | ✅ |
+| B. target file + state 로드 | ✅ | ✅ | ✅ |
+| C. 디자인 시스템 발견 | ✅ | ⛔ SKIP (와이어는 컴포넌트 불필요) | ✅ |
+| D. 와이어프레임 생성 | ✅ | ✅ | ⛔ SKIP |
+| 🚪 Step D ↔ E 검토 게이트 | ✅ | ⛔ (Step E 없음) | ⛔ (Step D 없음) |
+| E. 본 디자인 적용 | ✅ | ⛔ SKIP | ✅ (분기 동작, 아래 참조) |
+| F. 시각 검증 | ✅ (full) | ✅ (wire 대상, 구조 체크만) | ✅ (design 대상) |
+
+## createMode Matrix — `design` mode Step E branching (summary)
+
+**`createMode == design`의 Step E 동작 (결함 없는 실행을 위한 분기)**:
+
+- state.sections 가 **완전히 비어있음** (hasNewState 또는 첫 실행)
+  → 각 섹션별로 새 frame 생성 후 **곧바로** 컴포넌트 배치 (와이어 placeholder 단계 통째로 생략)
+  → 이 경로에서는 wireNodeId == designNodeId 가 됨 (같은 노드, 한 번에 완성)
+- state.sections 에 **일부 섹션의 wireNodeId 가 존재**
+  → 존재하는 섹션: 기존 wireNodeId 위에 덮어쓰기 (full 모드의 E와 동일)
+  → 없는 섹션: ❌ reject "이 섹션({섹션명})은 와이어가 없습니다.
+                      `--create-storyboard` 로 먼저 와이어를 만들거나, `--create` (full)로 호출하세요.
+                      빈 state에서 처음부터 design 모드로 그리려면 `--new-state` 를 추가하세요."
+
+## Step A — plan.md 파싱 (Read {mdArg} 필수 추출 섹션)
+
+```
+1. Read {mdArg}
+   필수 추출 섹션:
+     - "## 1. 개요" → 페이지 이름/목적
+     - "## 7. Look & Feel" → 분위기, 컬러, 타이포, 레퍼런스, 인터랙션
+     - "## 8. 레이아웃/섹션 구성" → 섹션 순서, 목적, 핵심 콘텐츠
+     - "## 9. 반응형 전략" → 디바이스 우선순위, 브레이크포인트
+
+   ⛔ 위 섹션 중 7/8 누락 시: 사용자에게 "plan.md에 UI 섹션이 비어있습니다.
+      /vibe.spec를 먼저 돌려 기획서를 보강할까요?" 라고 묻고 중단.
+
+   ✅ 피처명 결정: mdArg 파일명에서 .md 제거한 값을 {feature}로 사용
+
+2. Design context 로드 (non-interactive 기본)
+   - hasReadDesignMd == true (프로젝트 루트에 DESIGN.md 존재):
+     · §1 Visual Theme / §2 Color Palette / §3 Typography 를 톤·팔레트의
+       **1 차 입력**으로 사용 (`design-context.json` · plan.md 보다 우선)
+   - Read .vibe/design-context.json
+     · 존재 → 톤/팔레트 보강용으로 binding (DESIGN.md 가 있으면 보조)
+     · 없음 → plan.md의 "## 7. Look & Feel" 값으로 임시 컨텍스트 구성
+```
+
+## Step B — Figma 타겟 파일 확보 + State 파일 위치
+
+```
+1. AskUserQuestion (자유 텍스트):
+   "디자인을 생성할 target Figma 파일 URL을 입력해주세요.
+    (figma.com/design/{fileKey}/...)"
+
+2. URL → fileKey 추출
+
+3. State 파일 로드 (idempotency, 재실행 시 중복 생성 방지)
+   경로: /tmp/{feature}/figma-create-state.json
+```
+
+## Step C — 디자인 시스템 발견 세부
+
+```
+   2a. 컴포넌트: search_design_system 또는 기존 스크린 instance walk
+   2b. 변수(토큰): get_variable_defs로 색/간격/radius 수집
+   2c. 텍스트/이펙트 스타일: 발견된 토큰을 plan.md Look & Feel과 매칭
+       매칭 안 되면 "이 plan.md는 기존 디자인 시스템에 없는 토큰을 요구합니다.
+       새로 만들까요? (figma:figma-generate-library 권장) 또는 가까운 토큰으로 진행할까요?"
+```
+
+## Step D — 와이어프레임 생성 알고리즘 (incremental + idempotent)
+
+```
+   plan.md "## 8. 레이아웃/섹션 구성" 표를 순회:
+     for each 섹션 in plan.md:
+       1. 섹션 row 직렬화 → wireHash 계산 (8번 row만 해시)
+       2. state.sections에서 같은 name 매칭:
+          ├─ 매칭 없음 (신규):
+          │    a. use_figma 호출로 wire 프레임 생성 (Auto Layout만)
+          │       - 배경: #F5F5F5 (회색)
+          │       - 자식: 핵심 콘텐츠 컬럼의 항목마다 회색 박스 + 텍스트 라벨
+          │       - 컴포넌트 instance 배치 금지 (Step E에서 채움)
+          │       - 변수 바인딩 금지 (Step E에서 채움)
+          │    b. 반환된 wireNodeId를 state.sections에 entry append
+          │       (designNodeId = null 로 초기화)
+          ├─ 매칭 + wireHash 동일 (구조 변화 없음):
+          │    SKIP, "✓ {섹션명} wire (cached)" 출력
+          └─ 매칭 + wireHash 다름 (구조 변경됨):
+               a. use_figma로 기존 wireNodeId 내부 정리 (children 삭제)
+               b. 신규 케이스 a 재실행 (wireNodeId 재사용)
+               c. state entry의 wireHash + updatedAt 갱신
+               d. designNodeId가 있으면 → null로 리셋 (구조 바뀌었으니 본 디자인도 다시 그려야 함)
+
+   ⛔ 한 번의 use_figma 호출에 모든 섹션을 몰아넣지 말 것.
+      섹션 단위로 incremental 호출 → 검증 → 다음 섹션.
+
+   반응형 처리:
+     plan.md "## 9. 반응형 전략"의 브레이크포인트별로 별도 wire 프레임 생성
+     state.sections에는 bp 필드로 mo/pc 구분하여 각각 entry 저장
+
+   Step D 종료 직전:
+     state.updatedAt = now
+     Write /tmp/{feature}/figma-create-state.json
+```
+
+## Step D ↔ Step E 사용자 검토 게이트 — 메시지 템플릿
+
+```
+2. 사용자에게 제시:
+   "📐 와이어프레임이 생성되었습니다.
+    figma URL: https://figma.com/design/{fileKey}/...?node-id={firstWireNodeId}
+    섹션 요약: 신규 N / 갱신 M / 캐시 K
+
+    구조가 plan.md와 일치합니까?
+      yes  → Step E (본 디자인) 진행
+      <자유 텍스트> → 수정 요청 (해당 섹션의 wireHash 강제 무효화 후 Step D 재실행)
+      abort → 워크플로 중단"
+
+3. ralph/ultrawork 모드:
+   사용자 질문 SKIP, 자동 yes로 Step E 진행
+   (단, 섹션이 0개면 abort)
+```
+
+## Step E — 본 디자인 적용 알고리즘 (incremental + idempotent)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+분기 A) createMode == "full":
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   state.sections를 순회 (Step D에서 채워진 상태):
+     for each section in state.sections:
+       1. 섹션 row 직렬화 → designHash 계산 (7번+8번+9번 row 해시)
+       2. designNodeId == null 이거나 designHash 변경됨:
+          a. use_figma로 wireNodeId 내부의 자식 정리 (placeholder 삭제)
+             ⚠ wireNodeId 자체는 삭제 금지 (Auto Layout 골격 보존)
+          b. 같은 wireNodeId 안에 컴포넌트 instance 배치 + 변수 바인딩
+          c. 텍스트는 plan.md "핵심 콘텐츠" 컬럼의 실제 값 사용
+          d. designNodeId = wireNodeId 로 set (같은 노드가 2단계로 진화)
+          e. state entry의 designHash + updatedAt 갱신
+       3. designHash 동일: SKIP, "✓ {섹션명} design (cached)" 출력
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+분기 B) createMode == "design":
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   plan.md "## 8. 레이아웃/섹션 구성" 표를 순회 (state가 없을 수 있음):
+     for each 섹션 in plan.md:
+       1. 섹션 row 직렬화 → designHash 계산
+       2. state.sections에서 같은 name 매칭:
+          ├─ 매칭 있음 + wireNodeId 존재 → 분기 A의 update 경로 실행 (wireNodeId 재사용)
+          ├─ 매칭 있음 + wireNodeId null → ❌ "이 섹션({섹션명})은 이전에 design 모드로 그려졌지만
+          │                                   state가 깨졌습니다. --new-state 로 리셋하세요."
+          └─ 매칭 없음:
+              ⚠ state.sections 가 완전히 비어있음 (첫 실행 또는 hasNewState)이면 허용:
+                a. use_figma 호출로 frame 생성 (Auto Layout + 컴포넌트 + 텍스트 한 번에)
+                b. wireNodeId = designNodeId = 반환된 frameNodeId
+                c. state.sections에 entry append (wireHash/designHash 둘 다 계산)
+              ⛔ state.sections 가 일부 비어있지 않으면 reject:
+                "이 섹션({섹션명})은 와이어가 없습니다. --create-storyboard 로 먼저 만들거나
+                 --create (full)로 호출하세요."
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+공통 규칙:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ⛔ 한 번의 use_figma 호출에 모든 섹션을 몰아넣지 말 것.
+   ⛔ 분기 A에서 wireNodeId를 삭제하고 새 노드를 만들지 말 것 (state 무효화됨).
+
+   Step E 종료 직전:
+     state.planHash = sha256(plan.md 전체)
+     state.updatedAt = now
+     Write /tmp/{feature}/figma-create-state.json
+```
+
+## Step F — LLM 셀프 체크 + 최종 사용자 확인 템플릿
+
+```
+2. LLM 셀프 체크 (createMode에 따라 항목 narrow):
+
+   createMode == "storyboard" (구조 체크만 — 컬러 판단 불가):
+     - 섹션 순서가 plan.md 표와 일치하는가?
+     - 핵심 CTA 위치가 plan.md와 일치하는가?
+     ⛔ 컬러/분위기 체크 SKIP (와이어는 회색)
+
+   createMode == "design" 또는 "full":
+     - 섹션 순서가 plan.md 표와 일치하는가?
+     - 분위기/컬러 키워드가 시각적으로 반영됐는가?
+     - 핵심 CTA가 Hero에 존재하는가?
+
+3. 사용자에게 다음을 제시:
+   - createMode 표시 ("mode: full" / "mode: storyboard only" / "mode: design only")
+   - figma URL (fileKey + 첫 nodeId 딥링크)
+   - 섹션별 결과 요약:
+     · full:       wire 신규 N / 갱신 M / 캐시 K + design 신규 N / 갱신 M / 캐시 K
+     · storyboard: wire 신규 N / 갱신 M / 캐시 K
+     · design:     design 신규 N / 갱신 M / 캐시 K
+   - state 파일 경로
+   - (storyboard 모드) "다음 단계: 같은 plan.md로 `--create-design` 또는 `--create` 를 호출하면
+     이 와이어 위에 본 디자인이 입혀집니다."
+```

package/skills/vibe.image/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: vibe.image
+description: Generate images (icons, banners, mockups) using the Antigravity image backend.
+argument-hint: '"description" [--pro] [--icon "AppName"] [--size WxH]'
+user-invocable: true
+---
+
+# /vibe.image
+
+Generate images using the Antigravity image backend.
+
+- **Default**: Antigravity fast image - 빠르고 가벼운 이미지 생성
+- **--pro**: Antigravity pro image - 고품질 이미지 생성
+
+## Usage
+
+```
+/vibe.image "description"          # Generate image with Antigravity (icon, banner, etc.)
+/vibe.image --pro "description"    # High-quality generation
+/vibe.image --icon "AppName"       # Generate app icon/favicon
+```
+
+## MANDATORY Tool Invocation
+
+**CRITICAL: You MUST use the following command to generate images. Do NOT search for scripts, do NOT use gcloud, do NOT use any other method.**
+
+**Step 0: Script path:**
+- `[LLM_SCRIPT]` = `{{VIBE_PATH}}/hooks/scripts/llm-orchestrate.js`
+
+**General image generation (Antigravity fast image):**
+```bash
+node "[LLM_SCRIPT]" antigravity image "IMAGE_DESCRIPTION" --output "OUTPUT_PATH"
+```
+
+**Pro quality (Antigravity pro image):**
+```bash
+node "[LLM_SCRIPT]" antigravity image "IMAGE_DESCRIPTION" --pro --output "OUTPUT_PATH"
+```
+
+**With size option:**
+```bash
+node "[LLM_SCRIPT]" antigravity image "IMAGE_DESCRIPTION" --size "1920x1080" --output "OUTPUT_PATH"
+```
+
+## How to Parse User Request
+
+1. Extract the **image description** from the user's message (what to generate)
+2. Extract the **output path** from the user's message (where to save)
+   - If user specifies a path, use that path
+   - Default: `--output "./generated-image.png"`
+3. Extract **size** if specified, otherwise default 1024x1024
+4. If user requests **high quality / pro / 고품질**, add `--pro` flag
+
+> Read `references/image-generation-examples.md` for full worked examples, the JSON output format, and the --icon prompt template + example commands.
+
+## Prerequisites
+
+- Antigravity API key configured (`vibe antigravity key <key>`)
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/skills/vibe.image/references/image-generation-examples.md

@@ -0,0 +1,39 @@
+# vibe.image — Image Generation: Examples, Output Format, Icon Generation
+
+> Loaded by vibe.image SKILL.md — full worked examples, the JSON output format (success/error), and the --icon prompt template + example commands.
+
+### Examples
+
+```bash
+node "[LLM_SCRIPT]" antigravity image "A friendly AI character mascot, colorful, approachable" --output "./ai-character.png"
+
+node "[LLM_SCRIPT]" antigravity image "Professional website banner, modern design" --pro --size "1920x400" --output "./banner.png"
+
+node "[LLM_SCRIPT]" antigravity image "Modern minimal logo design" --output "./public/logo.png"
+```
+
+### Output Format
+
+The command outputs JSON to stdout:
+```json
+{ "success": true, "path": "/absolute/path/to/image.png", "size": 123456, "sizeKB": "120.5 KB" }
+```
+
+On error:
+```json
+{ "success": false, "error": "Error message" }
+```
+
+### Icon Generation (--icon)
+
+Use the same command with a pre-built icon prompt template:
+
+**Prompt template:** `"App icon for {APP_NAME}, primary color {COLOR}, square format 1:1, simple recognizable design, works well at small sizes, no text or letters, solid or gradient background, modern minimalist"`
+
+```bash
+# --icon "MyApp"
+node "[LLM_SCRIPT]" antigravity image "App icon for MyApp, square format 1:1, simple recognizable design, works well at small sizes, no text or letters, solid or gradient background, modern minimalist" --output "./public/app-icon.png"
+
+# --icon "MyApp" --color "#2F6BFF"
+node "[LLM_SCRIPT]" antigravity image "App icon for MyApp, primary color #2F6BFF, square format 1:1, simple recognizable design, works well at small sizes, no text or letters, solid or gradient background, modern minimalist" --output "./public/app-icon.png"
+```

package/skills/vibe.reason/SKILL.md

@@ -73,101 +73,9 @@ Apply 9-step reasoning framework to complex problems.
 - Document reasoning process for complex decisions
 - Ensure safety through step-by-step execution
 
-## Output Format
+> Read `references/output-format-template.md` for the full markdown report template.
 
-```markdown
-# Reasoning Framework Analysis
-
-**Problem**: [problem description]
-**Context**: [relevant information]
-**Steps Applied**: 9/9
-**⏱️ Started**: {start_time}
-**⏱️ Completed**: {getCurrentTime 결과}
-
----
-
-## 1. Logical Dependencies and Constraints
-
-**Constraint Analysis**:
-[analysis content]
-
----
-
-## 2. Risk Assessment
-
-**Risk Assessment**:
-- Task type: [risk level]
-- Rollback possibility: [assessment]
-- Compatibility/Security/Performance risks
-
----
-
-## 3. Inductive Reasoning and Hypothesis Exploration
-
-**Hypothesis Generation**:
-1. **Hypothesis 1**: [description] (Likelihood: High/Medium/Low)
-   - Evidence: [supporting evidence]
-   - Verification: [how to verify]
-
-2. **Hypothesis 2**: ...
-
----
-
-[Steps 4-9...]
-
----
-
-## Summary
-
-[Overall reasoning results summary and recommendations]
-
-**Recommended Actions**:
-1. Immediate: [low risk action]
-2. Short-term: [medium priority]
-3. Medium-term: [long-term fix]
-```
-
-## Example
-
-```
-User: /vibe.reason "After user login, profile page intermittently returns 500 error"
-
-AI: Analyzing with 9-step reasoning framework...
-
-# Reasoning Framework Analysis
-
-**Problem**: Intermittent 500 error on profile page after login
-**Context**: Intermittent occurrence, happens after successful login
-
-## 1. Logical Dependencies and Constraints
-
-**Constraint Analysis**:
-- Policy/Rules: Need to check auth/authz system policies
-- Task Order: Verify login -> session creation -> profile fetch order
-- Prerequisites: Need to identify error reproduction conditions
-
-## 3. Inductive Reasoning and Hypothesis Exploration
-
-**Hypothesis Generation**:
-1. **Hypothesis 1: Incomplete session data** (Likelihood: High)
-   - Evidence: Intermittent = timing issue or data consistency problem
-   - Verification: Add logging to session save logic
-
-2. **Hypothesis 2: Async processing order issue** (Likelihood: Medium)
-   - Evidence: undefined = accessing data before load
-   - Verification: Check Promise chain, missing await
-
-## Summary
-
-**Key Findings**:
-- Most likely cause: Incomplete session data
-- Verification priority: 1) Session logging -> 2) Async review -> 3) DB check
-
-**Recommended Actions**:
-1. Immediate: Add detailed logging to session save/fetch
-2. Short-term: Code review async processing
-3. Medium-term: Strengthen session store monitoring
-```
+> Read `references/worked-example.md` for a full worked example applying the 9-step framework to a debugging scenario.
 
 ## Best Practices
 
@@ -226,21 +134,7 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 
 ## Quality Gate (Mandatory)
 
-### Reasoning Quality Checklist
-
-Before completing reasoning analysis, ALL steps must be verified:
-
-| Step | Check Item | Weight |
-|------|------------|--------|
-| **Step 1** | Logical dependencies and constraints identified | 10% |
-| **Step 2** | Risk assessment completed with rollback plan | 10% |
-| **Step 3** | At least 3 hypotheses generated with likelihood | 15% |
-| **Step 4** | Verification method defined for each hypothesis | 10% |
-| **Step 5** | All available tools and resources listed | 10% |
-| **Step 6** | Evidence cited with exact sources | 15% |
-| **Step 7** | All alternatives explored | 10% |
-| **Step 8** | Error handling strategy defined | 10% |
-| **Step 9** | Action plan documented before execution | 10% |
+> Read `references/quality-rubrics.md` for the full reasoning quality checklist, hypothesis quality standards, minimum hypothesis count, evidence standards, risk assessment matrix, forbidden reasoning patterns, and reasoning output requirements.
 
 ### Reasoning Score Calculation
 
@@ -254,80 +148,6 @@ Grades:
 - <5/9 (<56%): ❌ INSUFFICIENT - Start over
 ```
 
-### Hypothesis Quality Standards
-
-Each hypothesis MUST include:
-
-| Component | Requirement | Example |
-|-----------|-------------|---------|
-| **Description** | Clear, testable statement | "Session data is incomplete due to race condition" |
-| **Likelihood** | High/Medium/Low with justification | "High - intermittent = timing issue" |
-| **Evidence** | Supporting observations | "Error only on concurrent logins" |
-| **Verification** | Specific test method | "Add logging to session.save()" |
-| **Disproof criteria** | What would rule it out | "Logs show complete data every time" |
-
-### Minimum Hypothesis Count
-
-| Problem Complexity | Minimum Hypotheses |
-|--------------------|-------------------|
-| Simple (single component) | 2 |
-| Medium (cross-component) | 3 |
-| Complex (system-wide) | 5 |
-
-### Evidence Standards
-
-All claims MUST include:
-
-| Evidence Type | Required Format |
-|---------------|-----------------|
-| Code reference | `filename.ts:L42` |
-| Log/metric | Exact value with timestamp |
-| Documentation | Document name + section |
-| Prior knowledge | Memory key or conversation reference |
-
-### Risk Assessment Matrix
-
-| Risk Level | Rollback Required | Approval Required |
-|------------|-------------------|-------------------|
-| **Low** | Optional | No |
-| **Medium** | Yes, automated | No |
-| **High** | Yes, tested | User confirmation |
-| **Critical** | Yes, verified | User + backup plan |
-
-### Forbidden Reasoning Patterns
-
-| Pattern | Issue | Required Fix |
-|---------|-------|--------------|
-| "Probably X" without evidence | Unsubstantiated claim | Add supporting evidence |
-| Single hypothesis | Tunnel vision | Generate alternatives |
-| Skipping risk assessment | Dangerous changes | Always assess risk |
-| "I think" without verification | Assumption | Verify before claiming |
-| Acting before reasoning complete | Premature action | Complete all 9 steps |
-
-### Reasoning Output Requirements
-
-Every reasoning analysis MUST include:
-
-1. **Problem Statement**
-   - Clear description
-   - Context and constraints
-   - Steps applied count (X/9)
-
-2. **Hypothesis Table**
-   - Ranked by likelihood
-   - All 5 components per hypothesis
-   - Verification status
-
-3. **Risk Assessment**
-   - Risk level classification
-   - Rollback possibility
-   - Approval requirements
-
-4. **Recommended Actions**
-   - Immediate (low risk, high confidence)
-   - Short-term (medium priority)
-   - Long-term (systemic fix)
-
 ---
 
 ARGUMENTS: $ARGUMENTS

package/skills/vibe.reason/references/output-format-template.md

@@ -0,0 +1,57 @@
+# vibe.reason — Output Format Template
+
+> Loaded by vibe.reason SKILL.md Output Format — full markdown report template for the 9-step reasoning framework analysis.
+
+## Output Format
+
+```markdown
+# Reasoning Framework Analysis
+
+**Problem**: [problem description]
+**Context**: [relevant information]
+**Steps Applied**: 9/9
+**⏱️ Started**: {start_time}
+**⏱️ Completed**: {getCurrentTime 결과}
+
+---
+
+## 1. Logical Dependencies and Constraints
+
+**Constraint Analysis**:
+[analysis content]
+
+---
+
+## 2. Risk Assessment
+
+**Risk Assessment**:
+- Task type: [risk level]
+- Rollback possibility: [assessment]
+- Compatibility/Security/Performance risks
+
+---
+
+## 3. Inductive Reasoning and Hypothesis Exploration
+
+**Hypothesis Generation**:
+1. **Hypothesis 1**: [description] (Likelihood: High/Medium/Low)
+   - Evidence: [supporting evidence]
+   - Verification: [how to verify]
+
+2. **Hypothesis 2**: ...
+
+---
+
+[Steps 4-9...]
+
+---
+
+## Summary
+
+[Overall reasoning results summary and recommendations]
+
+**Recommended Actions**:
+1. Immediate: [low risk action]
+2. Short-term: [medium priority]
+3. Medium-term: [long-term fix]
+```

package/skills/vibe.reason/references/quality-rubrics.md

@@ -0,0 +1,94 @@
+# vibe.reason — Quality Rubrics
+
+> Loaded by vibe.reason SKILL.md Quality Gate (Mandatory) — full reasoning quality checklist, hypothesis quality standards, minimum hypothesis count, evidence standards, risk assessment matrix, forbidden reasoning patterns, and reasoning output requirements. Reasoning Score Calculation (the deterministic gate threshold) stays in SKILL.md.
+
+### Reasoning Quality Checklist
+
+Before completing reasoning analysis, ALL steps must be verified:
+
+| Step | Check Item | Weight |
+|------|------------|--------|
+| **Step 1** | Logical dependencies and constraints identified | 10% |
+| **Step 2** | Risk assessment completed with rollback plan | 10% |
+| **Step 3** | At least 3 hypotheses generated with likelihood | 15% |
+| **Step 4** | Verification method defined for each hypothesis | 10% |
+| **Step 5** | All available tools and resources listed | 10% |
+| **Step 6** | Evidence cited with exact sources | 15% |
+| **Step 7** | All alternatives explored | 10% |
+| **Step 8** | Error handling strategy defined | 10% |
+| **Step 9** | Action plan documented before execution | 10% |
+
+
+### Hypothesis Quality Standards
+
+Each hypothesis MUST include:
+
+| Component | Requirement | Example |
+|-----------|-------------|---------|
+| **Description** | Clear, testable statement | "Session data is incomplete due to race condition" |
+| **Likelihood** | High/Medium/Low with justification | "High - intermittent = timing issue" |
+| **Evidence** | Supporting observations | "Error only on concurrent logins" |
+| **Verification** | Specific test method | "Add logging to session.save()" |
+| **Disproof criteria** | What would rule it out | "Logs show complete data every time" |
+
+### Minimum Hypothesis Count
+
+| Problem Complexity | Minimum Hypotheses |
+|--------------------|-------------------|
+| Simple (single component) | 2 |
+| Medium (cross-component) | 3 |
+| Complex (system-wide) | 5 |
+
+### Evidence Standards
+
+All claims MUST include:
+
+| Evidence Type | Required Format |
+|---------------|-----------------|
+| Code reference | `filename.ts:L42` |
+| Log/metric | Exact value with timestamp |
+| Documentation | Document name + section |
+| Prior knowledge | Memory key or conversation reference |
+
+### Risk Assessment Matrix
+
+| Risk Level | Rollback Required | Approval Required |
+|------------|-------------------|-------------------|
+| **Low** | Optional | No |
+| **Medium** | Yes, automated | No |
+| **High** | Yes, tested | User confirmation |
+| **Critical** | Yes, verified | User + backup plan |
+
+### Forbidden Reasoning Patterns
+
+| Pattern | Issue | Required Fix |
+|---------|-------|--------------|
+| "Probably X" without evidence | Unsubstantiated claim | Add supporting evidence |
+| Single hypothesis | Tunnel vision | Generate alternatives |
+| Skipping risk assessment | Dangerous changes | Always assess risk |
+| "I think" without verification | Assumption | Verify before claiming |
+| Acting before reasoning complete | Premature action | Complete all 9 steps |
+
+### Reasoning Output Requirements
+
+Every reasoning analysis MUST include:
+
+1. **Problem Statement**
+   - Clear description
+   - Context and constraints
+   - Steps applied count (X/9)
+
+2. **Hypothesis Table**
+   - Ranked by likelihood
+   - All 5 components per hypothesis
+   - Verification status
+
+3. **Risk Assessment**
+   - Risk level classification
+   - Rollback possibility
+   - Approval requirements
+
+4. **Recommended Actions**
+   - Immediate (low risk, high confidence)
+   - Short-term (medium priority)
+   - Long-term (systemic fix)