@su-record/vibe 2.8.52 → 2.8.53

package/skills/brand-assets/templates/brand-guide.md

@@ -1,161 +1,161 @@
-# Brand Guide: {{PROJECT_NAME}}
-
-**Version**: {{VERSION}}
-**Last Updated**: {{DATE}}
-**Maintainer**: {{MAINTAINER}}
-
----
-
-## Brand Identity
-
-| Attribute | Value |
-|-----------|-------|
-| Product Name | {{PRODUCT_NAME}} |
-| Tagline | {{TAGLINE}} |
-| Category | {{CATEGORY}} (SaaS / Mobile App / Consumer / Developer Tool) |
-| Personality | {{PERSONALITY_WORDS}} |
-| Tone | {{TONE}} |
-
----
-
-## Logo
-
-| Asset | File | Usage |
-|-------|------|-------|
-| Primary logo (color) | `{{LOGO_COLOR_PATH}}` | Default usage on white/light backgrounds |
-| Primary logo (white) | `{{LOGO_WHITE_PATH}}` | Dark backgrounds |
-| Primary logo (dark) | `{{LOGO_DARK_PATH}}` | Light backgrounds where color logo lacks contrast |
-| Icon only (color) | `{{ICON_COLOR_PATH}}` | App icons, favicons, small contexts |
-| Icon only (mono) | `{{ICON_MONO_PATH}}` | Single-color contexts |
-| Wordmark only | `{{WORDMARK_PATH}}` | When icon is shown separately |
-
-### Logo Clear Space
-
-Maintain minimum clear space of **{{LOGO_CLEAR_SPACE}}** on all sides of the logo. No other elements within this zone.
-
-### Logo Minimum Size
-
-| Context | Minimum Width |
-|---------|--------------|
-| Print | {{LOGO_MIN_PRINT}} |
-| Digital | {{LOGO_MIN_DIGITAL}} |
-| Favicon | 16px (icon only) |
-
-### Logo Misuse
-
-- Do not stretch or distort the logo
-- Do not apply drop shadows to the logo
-- Do not place on busy backgrounds without a clear area
-- Do not recreate with incorrect fonts or colors
-- Do not use at sizes below minimum
-
----
-
-## Color Palette
-
-### Primary Colors
-
-| Name | Hex | RGB | HSL | Usage |
-|------|-----|-----|-----|-------|
-| {{PRIMARY_NAME}} | {{PRIMARY_HEX}} | {{PRIMARY_RGB}} | {{PRIMARY_HSL}} | Primary brand, CTAs |
-| {{SECONDARY_NAME}} | {{SECONDARY_HEX}} | {{SECONDARY_RGB}} | {{SECONDARY_HSL}} | Secondary actions |
-
-### Neutral Colors
-
-| Name | Hex | Usage |
-|------|-----|-------|
-| {{NEUTRAL_DARK}} | {{NEUTRAL_DARK_HEX}} | Primary text |
-| {{NEUTRAL_MID}} | {{NEUTRAL_MID_HEX}} | Secondary text, borders |
-| {{NEUTRAL_LIGHT}} | {{NEUTRAL_LIGHT_HEX}} | Backgrounds, dividers |
-
-### Semantic Colors
-
-| Name | Hex | Usage |
-|------|-----|-------|
-| Error | {{ERROR_HEX}} | Error states, destructive actions |
-| Success | {{SUCCESS_HEX}} | Confirmation, positive states |
-| Warning | {{WARNING_HEX}} | Caution states |
-| Info | {{INFO_HEX}} | Informational states |
-
----
-
-## Typography
-
-### Typefaces
-
-| Role | Font Family | Weight(s) | Source |
-|------|------------|-----------|--------|
-| Heading | {{HEADING_FONT}} | {{HEADING_WEIGHTS}} | {{HEADING_SOURCE}} |
-| Body | {{BODY_FONT}} | {{BODY_WEIGHTS}} | {{BODY_SOURCE}} |
-| Monospace | {{MONO_FONT}} | {{MONO_WEIGHTS}} | {{MONO_SOURCE}} |
-
-### Type Scale
-
-| Level | Size | Weight | Line Height | Use |
-|-------|------|--------|-------------|-----|
-| Display | {{DISPLAY_SIZE}} | {{DISPLAY_WEIGHT}} | {{DISPLAY_LH}} | Hero text |
-| H1 | {{H1_SIZE}} | {{H1_WEIGHT}} | {{H1_LH}} | Page titles |
-| H2 | {{H2_SIZE}} | {{H2_WEIGHT}} | {{H2_LH}} | Section headings |
-| H3 | {{H3_SIZE}} | {{H3_WEIGHT}} | {{H3_LH}} | Subsections |
-| Body | {{BODY_SIZE}} | {{BODY_WEIGHT}} | {{BODY_LH}} | Paragraphs |
-| Caption | {{CAPTION_SIZE}} | {{CAPTION_WEIGHT}} | {{CAPTION_LH}} | Labels, captions |
-
----
-
-## Iconography
-
-| Attribute | Value |
-|-----------|-------|
-| Icon library | {{ICON_LIBRARY}} |
-| Icon style | {{ICON_STYLE}} (outline / solid / duotone) |
-| Standard sizes | 16px, 20px, 24px |
-| Stroke width | {{STROKE_WIDTH}} |
-| Color usage | Match adjacent text or use `--color-primary` for emphasis |
-
----
-
-## App Icons & Favicons
-
-| Asset | Size | File | Format |
-|-------|------|------|--------|
-| Favicon | 16×16 | `public/favicon-16x16.png` | PNG |
-| Favicon | 32×32 | `public/favicon-32x32.png` | PNG |
-| Favicon bundle | 16/32/48 | `public/favicon.ico` | ICO |
-| Apple Touch Icon | 180×180 | `public/apple-touch-icon.png` | PNG |
-| Android Chrome | 192×192 | `public/android-chrome-192x192.png` | PNG |
-| Android Chrome | 512×512 | `public/android-chrome-512x512.png` | PNG |
-
----
-
-## Imagery & Illustration
-
-| Attribute | Guideline |
-|-----------|-----------|
-| Photography style | {{PHOTO_STYLE}} |
-| Illustration style | {{ILLUSTRATION_STYLE}} |
-| Image treatment | {{IMAGE_TREATMENT}} |
-| Avoid | {{IMAGE_AVOID}} |
-
----
-
-## Motion
-
-| Attribute | Value |
-|-----------|-------|
-| Default duration | 200ms |
-| Fast duration | 150ms (micro-interactions) |
-| Slow duration | 300ms (page transitions) |
-| Default easing | `cubic-bezier(0.4, 0, 0.2, 1)` |
-| Personality | {{MOTION_PERSONALITY}} (subtle / expressive / none) |
-
----
-
-## Voice & Tone
-
-| Context | Tone | Example |
-|---------|------|---------|
-| Marketing | {{MARKETING_TONE}} | {{MARKETING_EXAMPLE}} |
-| UI labels | {{UI_TONE}} | {{UI_EXAMPLE}} |
-| Error messages | {{ERROR_TONE}} | {{ERROR_EXAMPLE}} |
-| Success messages | {{SUCCESS_TONE}} | {{SUCCESS_EXAMPLE}} |
-| Empty states | {{EMPTY_TONE}} | {{EMPTY_EXAMPLE}} |
+# Brand Guide: {{PROJECT_NAME}}
+
+**Version**: {{VERSION}}
+**Last Updated**: {{DATE}}
+**Maintainer**: {{MAINTAINER}}
+
+---
+
+## Brand Identity
+
+| Attribute | Value |
+|-----------|-------|
+| Product Name | {{PRODUCT_NAME}} |
+| Tagline | {{TAGLINE}} |
+| Category | {{CATEGORY}} (SaaS / Mobile App / Consumer / Developer Tool) |
+| Personality | {{PERSONALITY_WORDS}} |
+| Tone | {{TONE}} |
+
+---
+
+## Logo
+
+| Asset | File | Usage |
+|-------|------|-------|
+| Primary logo (color) | `{{LOGO_COLOR_PATH}}` | Default usage on white/light backgrounds |
+| Primary logo (white) | `{{LOGO_WHITE_PATH}}` | Dark backgrounds |
+| Primary logo (dark) | `{{LOGO_DARK_PATH}}` | Light backgrounds where color logo lacks contrast |
+| Icon only (color) | `{{ICON_COLOR_PATH}}` | App icons, favicons, small contexts |
+| Icon only (mono) | `{{ICON_MONO_PATH}}` | Single-color contexts |
+| Wordmark only | `{{WORDMARK_PATH}}` | When icon is shown separately |
+
+### Logo Clear Space
+
+Maintain minimum clear space of **{{LOGO_CLEAR_SPACE}}** on all sides of the logo. No other elements within this zone.
+
+### Logo Minimum Size
+
+| Context | Minimum Width |
+|---------|--------------|
+| Print | {{LOGO_MIN_PRINT}} |
+| Digital | {{LOGO_MIN_DIGITAL}} |
+| Favicon | 16px (icon only) |
+
+### Logo Misuse
+
+- Do not stretch or distort the logo
+- Do not apply drop shadows to the logo
+- Do not place on busy backgrounds without a clear area
+- Do not recreate with incorrect fonts or colors
+- Do not use at sizes below minimum
+
+---
+
+## Color Palette
+
+### Primary Colors
+
+| Name | Hex | RGB | HSL | Usage |
+|------|-----|-----|-----|-------|
+| {{PRIMARY_NAME}} | {{PRIMARY_HEX}} | {{PRIMARY_RGB}} | {{PRIMARY_HSL}} | Primary brand, CTAs |
+| {{SECONDARY_NAME}} | {{SECONDARY_HEX}} | {{SECONDARY_RGB}} | {{SECONDARY_HSL}} | Secondary actions |
+
+### Neutral Colors
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| {{NEUTRAL_DARK}} | {{NEUTRAL_DARK_HEX}} | Primary text |
+| {{NEUTRAL_MID}} | {{NEUTRAL_MID_HEX}} | Secondary text, borders |
+| {{NEUTRAL_LIGHT}} | {{NEUTRAL_LIGHT_HEX}} | Backgrounds, dividers |
+
+### Semantic Colors
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| Error | {{ERROR_HEX}} | Error states, destructive actions |
+| Success | {{SUCCESS_HEX}} | Confirmation, positive states |
+| Warning | {{WARNING_HEX}} | Caution states |
+| Info | {{INFO_HEX}} | Informational states |
+
+---
+
+## Typography
+
+### Typefaces
+
+| Role | Font Family | Weight(s) | Source |
+|------|------------|-----------|--------|
+| Heading | {{HEADING_FONT}} | {{HEADING_WEIGHTS}} | {{HEADING_SOURCE}} |
+| Body | {{BODY_FONT}} | {{BODY_WEIGHTS}} | {{BODY_SOURCE}} |
+| Monospace | {{MONO_FONT}} | {{MONO_WEIGHTS}} | {{MONO_SOURCE}} |
+
+### Type Scale
+
+| Level | Size | Weight | Line Height | Use |
+|-------|------|--------|-------------|-----|
+| Display | {{DISPLAY_SIZE}} | {{DISPLAY_WEIGHT}} | {{DISPLAY_LH}} | Hero text |
+| H1 | {{H1_SIZE}} | {{H1_WEIGHT}} | {{H1_LH}} | Page titles |
+| H2 | {{H2_SIZE}} | {{H2_WEIGHT}} | {{H2_LH}} | Section headings |
+| H3 | {{H3_SIZE}} | {{H3_WEIGHT}} | {{H3_LH}} | Subsections |
+| Body | {{BODY_SIZE}} | {{BODY_WEIGHT}} | {{BODY_LH}} | Paragraphs |
+| Caption | {{CAPTION_SIZE}} | {{CAPTION_WEIGHT}} | {{CAPTION_LH}} | Labels, captions |
+
+---
+
+## Iconography
+
+| Attribute | Value |
+|-----------|-------|
+| Icon library | {{ICON_LIBRARY}} |
+| Icon style | {{ICON_STYLE}} (outline / solid / duotone) |
+| Standard sizes | 16px, 20px, 24px |
+| Stroke width | {{STROKE_WIDTH}} |
+| Color usage | Match adjacent text or use `--color-primary` for emphasis |
+
+---
+
+## App Icons & Favicons
+
+| Asset | Size | File | Format |
+|-------|------|------|--------|
+| Favicon | 16×16 | `public/favicon-16x16.png` | PNG |
+| Favicon | 32×32 | `public/favicon-32x32.png` | PNG |
+| Favicon bundle | 16/32/48 | `public/favicon.ico` | ICO |
+| Apple Touch Icon | 180×180 | `public/apple-touch-icon.png` | PNG |
+| Android Chrome | 192×192 | `public/android-chrome-192x192.png` | PNG |
+| Android Chrome | 512×512 | `public/android-chrome-512x512.png` | PNG |
+
+---
+
+## Imagery & Illustration
+
+| Attribute | Guideline |
+|-----------|-----------|
+| Photography style | {{PHOTO_STYLE}} |
+| Illustration style | {{ILLUSTRATION_STYLE}} |
+| Image treatment | {{IMAGE_TREATMENT}} |
+| Avoid | {{IMAGE_AVOID}} |
+
+---
+
+## Motion
+
+| Attribute | Value |
+|-----------|-------|
+| Default duration | 200ms |
+| Fast duration | 150ms (micro-interactions) |
+| Slow duration | 300ms (page transitions) |
+| Default easing | `cubic-bezier(0.4, 0, 0.2, 1)` |
+| Personality | {{MOTION_PERSONALITY}} (subtle / expressive / none) |
+
+---
+
+## Voice & Tone
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Marketing | {{MARKETING_TONE}} | {{MARKETING_EXAMPLE}} |
+| UI labels | {{UI_TONE}} | {{UI_EXAMPLE}} |
+| Error messages | {{ERROR_TONE}} | {{ERROR_EXAMPLE}} |
+| Success messages | {{SUCCESS_TONE}} | {{SUCCESS_EXAMPLE}} |
+| Empty states | {{EMPTY_TONE}} | {{EMPTY_EXAMPLE}} |

package/skills/capability-loop/SKILL.md

@@ -1,168 +1,168 @@
----
-name: capability-loop
-tier: standard
-description: "When an agent fails, diagnose which capability is missing and build it into the repo. Activates after repeated agent failures, tool errors, or when a task keeps failing in the same way. Analyzes failure transcripts, identifies the missing guardrail/tool/abstraction/doc, and creates it permanently. Use this skill whenever you see 3+ similar failures, an agent hitting the same wall repeatedly, or the user asking 'why does this keep failing'."
-triggers: [capability loop, failure loop, build capability, missing capability, agent failed, why did it fail]
-priority: 75
----
-
-# Capability Loop — Failure → Capability Building
-
-> **Principle**: "Ask what capability is missing, not why it failed." Every failure is a missing tool, guardrail, abstraction, or piece of documentation. Build the capability so the failure NEVER recurs.
-
-## When to Use
-
-| Trigger | Signal |
-|---------|--------|
-| Agent fails a task | Error, wrong output, timeout, confusion |
-| Same error occurs twice | Pattern of missing capability |
-| Agent asks clarifying question | Information not discoverable |
-| Review finds recurring issue | Systemic gap, not one-off mistake |
-| Manual intervention needed | Agent should have been self-sufficient |
-
-## Core Flow
-
-```
-FAILURE → DIAGNOSE → CLASSIFY → BUILD → VERIFY → PERSIST
-```
-
-### Step 1: DIAGNOSE — What Capability is Missing?
-
-Do NOT ask "why did it fail?" Instead ask: **"What would have prevented this failure?"**
-
-```
-Diagnosis questions (answer ALL):
-
-1. TOOL: Did the agent lack a tool to accomplish the task?
-   → Missing CLI command, missing API, missing utility function
-
-2. GUARDRAIL: Did the agent do something it shouldn't have?
-   → Missing lint rule, missing test, missing hook check
-
-3. ABSTRACTION: Did the agent struggle with unnecessary complexity?
-   → Missing helper, missing wrapper, missing shared module
-
-4. DOCUMENTATION: Did the agent lack discoverable information?
-   → Missing CLAUDE.md entry, missing code comment, missing type definition
-
-5. FEEDBACK: Did the agent not know it was doing the wrong thing?
-   → Missing error message, missing test assertion, missing type error
-```
-
-### Step 2: CLASSIFY — What Type of Capability?
-
-| Category | Example | Where to Build |
-|----------|---------|---------------|
-| **Tool** | "No way to validate schema" | New CLI command or skill |
-| **Guardrail** | "Accidentally deleted migration" | New hook or test |
-| **Abstraction** | "Copy-pasted auth logic 3 times" | New shared module |
-| **Documentation** | "Didn't know config format" | CLAUDE.md or code comments |
-| **Feedback** | "Didn't realize test was wrong" | Better error messages or types |
-
-### Step 3: BUILD — Create the Capability
-
-Based on classification, build the appropriate artifact:
-
-#### Tool → New Skill or Command
-```
-1. Create skills/{capability-name}/SKILL.md
-2. Add triggers for automatic activation
-3. Test with a simulated scenario
-```
-
-#### Guardrail → New Test or Hook
-```
-1. Add test to tests/arch-guard.test.ts (if structural)
-2. Or add check to hooks/scripts/ (if runtime)
-3. Verify it catches the original failure
-```
-
-#### Abstraction → New Module
-```
-1. Extract shared code into appropriate location
-2. Update existing callers to use new abstraction
-3. Add tests for the abstraction
-```
-
-#### Documentation → CLAUDE.md or Inline
-```
-1. If it's a constraint/gotcha → add to CLAUDE.md "Gotchas" section
-2. If it's discoverable from code → add code comment or type definition
-3. If it's a pattern → add to relevant language rule file
-```
-
-#### Feedback → Better Types or Errors
-```
-1. Add TypeScript type that prevents the mistake at compile time
-2. Or add runtime validation with clear error message
-3. Or add test that catches the mistake early
-```
-
-### Step 4: VERIFY — Reproduce and Confirm Fix
-
-```
-1. Reproduce the original failure scenario
-2. Confirm the new capability prevents it
-3. Run existing tests to verify no regressions
-4. If the capability is a test, verify it FAILS without the fix
-```
-
-### Step 5: PERSIST — Record for Future Reference
-
-Save the capability-building decision:
-
-```
-save_memory("capability-{name}", {
-  failure: "description of what failed",
-  diagnosis: "what capability was missing",
-  category: "tool|guardrail|abstraction|documentation|feedback",
-  solution: "what was built",
-  files_changed: ["list of files"]
-})
-```
-
-Update `.claude/vibe/capabilities-log.md`:
-
-```markdown
-## {date} — {capability-name}
-
-**Failure**: {what happened}
-**Missing**: {what capability was absent}
-**Built**: {what was created}
-**Files**: {list}
-**Prevents**: {what class of failures this prevents}
-```
-
-## Decision Tree
-
-```
-Agent failed
-    │
-    ├─ Could a TOOL have done it automatically?
-    │   YES → Build tool (skill/command/script)
-    │
-    ├─ Should the agent have been PREVENTED from doing it?
-    │   YES → Build guardrail (hook/test/lint rule)
-    │
-    ├─ Was the agent REPEATING work that should be shared?
-    │   YES → Build abstraction (module/helper/utility)
-    │
-    ├─ Did the agent lack KNOWLEDGE it needed?
-    │   YES → Add documentation (CLAUDE.md/comments/types)
-    │
-    └─ Did the agent not KNOW it was wrong?
-        YES → Build feedback (types/errors/tests)
-```
-
-## Anti-patterns
-
-- "Add a note to be more careful" → Build a guardrail instead
-- "Document the right way to do it" → If possible, make the wrong way a compile/test error
-- "Tell the agent to check X first" → Make X discoverable automatically
-- "It was a one-off mistake" → If it happened once, it will happen again. Build the capability.
-
-## Integration Points
-
-- After `/vibe.run` failure → auto-trigger capability-loop diagnosis
-- After `/vibe.review` findings → suggest capability-loop for recurring patterns
-- After manual agent correction → prompt "What capability would have prevented this?"
+---
+name: capability-loop
+tier: standard
+description: "When an agent fails, diagnose which capability is missing and build it into the repo. Activates after repeated agent failures, tool errors, or when a task keeps failing in the same way. Analyzes failure transcripts, identifies the missing guardrail/tool/abstraction/doc, and creates it permanently. Use this skill whenever you see 3+ similar failures, an agent hitting the same wall repeatedly, or the user asking 'why does this keep failing'."
+triggers: [capability loop, failure loop, build capability, missing capability, agent failed, why did it fail]
+priority: 75
+---
+
+# Capability Loop — Failure → Capability Building
+
+> **Principle**: "Ask what capability is missing, not why it failed." Every failure is a missing tool, guardrail, abstraction, or piece of documentation. Build the capability so the failure NEVER recurs.
+
+## When to Use
+
+| Trigger | Signal |
+|---------|--------|
+| Agent fails a task | Error, wrong output, timeout, confusion |
+| Same error occurs twice | Pattern of missing capability |
+| Agent asks clarifying question | Information not discoverable |
+| Review finds recurring issue | Systemic gap, not one-off mistake |
+| Manual intervention needed | Agent should have been self-sufficient |
+
+## Core Flow
+
+```
+FAILURE → DIAGNOSE → CLASSIFY → BUILD → VERIFY → PERSIST
+```
+
+### Step 1: DIAGNOSE — What Capability is Missing?
+
+Do NOT ask "why did it fail?" Instead ask: **"What would have prevented this failure?"**
+
+```
+Diagnosis questions (answer ALL):
+
+1. TOOL: Did the agent lack a tool to accomplish the task?
+   → Missing CLI command, missing API, missing utility function
+
+2. GUARDRAIL: Did the agent do something it shouldn't have?
+   → Missing lint rule, missing test, missing hook check
+
+3. ABSTRACTION: Did the agent struggle with unnecessary complexity?
+   → Missing helper, missing wrapper, missing shared module
+
+4. DOCUMENTATION: Did the agent lack discoverable information?
+   → Missing CLAUDE.md entry, missing code comment, missing type definition
+
+5. FEEDBACK: Did the agent not know it was doing the wrong thing?
+   → Missing error message, missing test assertion, missing type error
+```
+
+### Step 2: CLASSIFY — What Type of Capability?
+
+| Category | Example | Where to Build |
+|----------|---------|---------------|
+| **Tool** | "No way to validate schema" | New CLI command or skill |
+| **Guardrail** | "Accidentally deleted migration" | New hook or test |
+| **Abstraction** | "Copy-pasted auth logic 3 times" | New shared module |
+| **Documentation** | "Didn't know config format" | CLAUDE.md or code comments |
+| **Feedback** | "Didn't realize test was wrong" | Better error messages or types |
+
+### Step 3: BUILD — Create the Capability
+
+Based on classification, build the appropriate artifact:
+
+#### Tool → New Skill or Command
+```
+1. Create skills/{capability-name}/SKILL.md
+2. Add triggers for automatic activation
+3. Test with a simulated scenario
+```
+
+#### Guardrail → New Test or Hook
+```
+1. Add test to tests/arch-guard.test.ts (if structural)
+2. Or add check to hooks/scripts/ (if runtime)
+3. Verify it catches the original failure
+```
+
+#### Abstraction → New Module
+```
+1. Extract shared code into appropriate location
+2. Update existing callers to use new abstraction
+3. Add tests for the abstraction
+```
+
+#### Documentation → CLAUDE.md or Inline
+```
+1. If it's a constraint/gotcha → add to CLAUDE.md "Gotchas" section
+2. If it's discoverable from code → add code comment or type definition
+3. If it's a pattern → add to relevant language rule file
+```
+
+#### Feedback → Better Types or Errors
+```
+1. Add TypeScript type that prevents the mistake at compile time
+2. Or add runtime validation with clear error message
+3. Or add test that catches the mistake early
+```
+
+### Step 4: VERIFY — Reproduce and Confirm Fix
+
+```
+1. Reproduce the original failure scenario
+2. Confirm the new capability prevents it
+3. Run existing tests to verify no regressions
+4. If the capability is a test, verify it FAILS without the fix
+```
+
+### Step 5: PERSIST — Record for Future Reference
+
+Save the capability-building decision:
+
+```
+save_memory("capability-{name}", {
+  failure: "description of what failed",
+  diagnosis: "what capability was missing",
+  category: "tool|guardrail|abstraction|documentation|feedback",
+  solution: "what was built",
+  files_changed: ["list of files"]
+})
+```
+
+Update `.claude/vibe/capabilities-log.md`:
+
+```markdown
+## {date} — {capability-name}
+
+**Failure**: {what happened}
+**Missing**: {what capability was absent}
+**Built**: {what was created}
+**Files**: {list}
+**Prevents**: {what class of failures this prevents}
+```
+
+## Decision Tree
+
+```
+Agent failed
+    │
+    ├─ Could a TOOL have done it automatically?
+    │   YES → Build tool (skill/command/script)
+    │
+    ├─ Should the agent have been PREVENTED from doing it?
+    │   YES → Build guardrail (hook/test/lint rule)
+    │
+    ├─ Was the agent REPEATING work that should be shared?
+    │   YES → Build abstraction (module/helper/utility)
+    │
+    ├─ Did the agent lack KNOWLEDGE it needed?
+    │   YES → Add documentation (CLAUDE.md/comments/types)
+    │
+    └─ Did the agent not KNOW it was wrong?
+        YES → Build feedback (types/errors/tests)
+```
+
+## Anti-patterns
+
+- "Add a note to be more careful" → Build a guardrail instead
+- "Document the right way to do it" → If possible, make the wrong way a compile/test error
+- "Tell the agent to check X first" → Make X discoverable automatically
+- "It was a one-off mistake" → If it happened once, it will happen again. Build the capability.
+
+## Integration Points
+
+- After `/vibe.run` failure → auto-trigger capability-loop diagnosis
+- After `/vibe.review` findings → suggest capability-loop for recurring patterns
+- After manual agent correction → prompt "What capability would have prevented this?"