opencodekit 0.20.1 → 0.20.3

package/dist/template/.opencode/plugin/lib/validate.ts

@@ -0,0 +1,243 @@
+/**
+ * Observation Validation Gate
+ *
+ * Inspired by jumperz's Secondmate Hermes validation:
+ * checks for duplicates and contradictions BEFORE storing an observation.
+ *
+ * Unlike Secondmate's approach (separate LLM model), this uses
+ * FTS5 similarity search + heuristic contradiction detection.
+ *
+ * Returns a validation result that can:
+ * - PASS: store normally
+ * - WARN: store but flag issues
+ * - REJECT: don't store, return reason
+ */
+
+import type { ObservationInput, ObservationRow } from "./db/types.js";
+import { getMemoryDB } from "./memory-db.js";
+import { hasWord } from "./memory-helpers.js";
+import { appendOperationLog } from "./operation-log.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ValidationVerdict = "pass" | "warn" | "reject";
+
+export interface ValidationResult {
+	verdict: ValidationVerdict;
+	issues: ValidationIssue[];
+	/** If a near-duplicate was found, its ID */
+	duplicateOf?: number;
+}
+
+export interface ValidationIssue {
+	type: "duplicate" | "near-duplicate" | "contradiction" | "low-quality";
+	severity: "high" | "medium" | "low";
+	message: string;
+	relatedId?: number;
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate an observation before storing.
+ * Returns verdict (pass/warn/reject) with issues.
+ */
+export function validateObservation(input: ObservationInput): ValidationResult {
+	const issues: ValidationIssue[] = [];
+
+	// Check 1: Exact title duplicate
+	const exactDup = findExactDuplicate(input);
+	if (exactDup) {
+		// If it's explicitly superseding, that's fine
+		if (input.supersedes === exactDup.id) {
+			// Intentional supersede — pass
+		} else {
+			issues.push({
+				type: "duplicate",
+				severity: "high",
+				message: `Exact duplicate of #${exactDup.id}: "${exactDup.title}"`,
+				relatedId: exactDup.id,
+			});
+
+			appendOperationLog({
+				operation: "observation-duplicate-warning",
+				targets: [`#${exactDup.id}`],
+				summary: `Duplicate warning: "${input.title}" (matches #${exactDup.id})`,
+			});
+
+			return {
+				verdict: "warn",
+				issues,
+				duplicateOf: exactDup.id,
+			};
+		}
+	}
+
+	// Check 2: Near-duplicate via FTS5
+	const nearDup = findNearDuplicate(input);
+	if (nearDup) {
+		issues.push({
+			type: "near-duplicate",
+			severity: "medium",
+			message: `Similar to #${nearDup.id}: "${nearDup.title}" (consider superseding)`,
+			relatedId: nearDup.id,
+		});
+	}
+
+	// Check 3: Contradiction with existing decisions
+	if (input.type === "decision") {
+		const contradiction = findContradiction(input);
+		if (contradiction) {
+			issues.push({
+				type: "contradiction",
+				severity: "medium",
+				message: `May contradict #${contradiction.id}: "${contradiction.title}"`,
+				relatedId: contradiction.id,
+			});
+		}
+	}
+
+	// Check 4: Low quality (no narrative, no concepts)
+	if (!input.narrative && !input.concepts) {
+		issues.push({
+			type: "low-quality",
+			severity: "low",
+			message:
+				"Observation has no narrative and no concepts — low knowledge value",
+		});
+	}
+
+	// Determine verdict
+	const hasHigh = issues.some((i) => i.severity === "high");
+	const verdict: ValidationVerdict = hasHigh
+		? "reject"
+		: issues.length > 0
+			? "warn"
+			: "pass";
+
+	if (verdict === "pass" || verdict === "warn") {
+		appendOperationLog({
+			operation: "observation-validated",
+			targets: [input.title],
+			summary: `Validated [${input.type}] "${input.title}" — ${verdict}${issues.length > 0 ? ` (${issues.length} issues)` : ""}`,
+		});
+	}
+
+	return { verdict, issues };
+}
+
+// ============================================================================
+// Internal Checks
+// ============================================================================
+
+/**
+ * Check for exact title match (same type, active).
+ */
+function findExactDuplicate(input: ObservationInput): ObservationRow | null {
+	const db = getMemoryDB();
+	return db
+		.query(
+			`SELECT * FROM observations
+			 WHERE type = ? AND LOWER(title) = LOWER(?) AND superseded_by IS NULL
+			 LIMIT 1`,
+		)
+		.get(input.type, input.title) as ObservationRow | null;
+}
+
+/**
+ * Check for near-duplicate via FTS5 title search.
+ */
+function findNearDuplicate(input: ObservationInput): ObservationRow | null {
+	const db = getMemoryDB();
+
+	// Build FTS query from title words
+	// Strip FTS5 special operators and characters to prevent query syntax errors
+	const FTS5_OPERATORS = /\b(AND|OR|NOT|NEAR)\b/gi;
+	const words = input.title
+		.replace(FTS5_OPERATORS, "")
+		.replace(/['"*^+(){}]/g, "")
+		.split(/\s+/)
+		.filter((w) => w.length > 2)
+		.map((w) => `"${w}"*`)
+		.join(" AND ");
+
+	if (!words) return null;
+
+	try {
+		const result = db
+			.query(
+				`SELECT o.* FROM observations o
+				 JOIN observations_fts fts ON fts.rowid = o.id
+				 WHERE observations_fts MATCH ?
+				   AND o.type = ?
+				   AND o.superseded_by IS NULL
+				   AND o.id != COALESCE(?, -1)
+				 ORDER BY bm25(observations_fts) LIMIT 1`,
+			)
+			.get(
+				words,
+				input.type,
+				input.supersedes ?? null,
+			) as ObservationRow | null;
+
+		return result;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Check for contradictions with existing decisions.
+ */
+function findContradiction(input: ObservationInput): ObservationRow | null {
+	if (!input.concepts || input.concepts.length === 0) return null;
+
+	const db = getMemoryDB();
+
+	// Search for decisions with overlapping concepts
+	const conceptQuery = input.concepts.map((c) => `"${c}"*`).join(" OR ");
+
+	try {
+		const candidates = db
+			.query(
+				`SELECT o.* FROM observations o
+				 JOIN observations_fts fts ON fts.rowid = o.id
+				 WHERE observations_fts MATCH ?
+				   AND o.type = 'decision'
+				   AND o.superseded_by IS NULL
+				 ORDER BY bm25(observations_fts) LIMIT 5`,
+			)
+			.all(conceptQuery) as ObservationRow[];
+
+		// Check for opposing signals
+		const inputText = `${input.title} ${input.narrative ?? ""}`.toLowerCase();
+		const contradictionPairs = [
+			["use", "don't use"],
+			["enable", "disable"],
+			["add", "remove"],
+			["prefer", "avoid"],
+			["always", "never"],
+		];
+
+		for (const candidate of candidates) {
+			const candidateText =
+				`${candidate.title} ${candidate.narrative ?? ""}`.toLowerCase();
+			for (const [wordA, wordB] of contradictionPairs) {
+				if (
+					(hasWord(inputText, wordA) && hasWord(candidateText, wordB)) ||
+					(hasWord(inputText, wordB) && hasWord(candidateText, wordA))
+				) {
+					return candidate;
+				}
+			}
+		}
+	} catch {
+		// FTS5 query failed
+	}
+
+	return null;
+}

package/dist/template/.opencode/skill/design-taste-frontend/SKILL.md

@@ -1,8 +1,20 @@
 ---
 name: design-taste-frontend
-description: Use as the BASE aesthetic skill for any web UI to override default LLM design biases. Enforces strict typography, color, spacing, and component architecture rules. Load BEFORE frontend-design when premium visual quality is required.
+description: Use when building any web UI as the BASE aesthetic layer to override default LLM design biases. Enforces strict typography, color, spacing, and component architecture rules. Load BEFORE frontend-design when premium visual quality is required.
 ---
 
+## When to Use
+
+- When building any web UI that needs to override default LLM design biases
+- Before loading `frontend-design` skill when premium visual quality is required
+- As the base aesthetic layer for any UI implementation task
+
+## When NOT to Use
+
+- When a more specific aesthetic overlay is loaded (high-end-visual-design, minimalist-ui, industrial-brutalist-ui)
+- For non-UI tasks (backend, CLI, data processing)
+
+
 # High-Agency Frontend Skill
 
 ## 1. ACTIVE BASELINE CONFIGURATION

package/dist/template/.opencode/skill/figma-go/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figma-go
-description: Use for Figma read/write access WITHOUT an API token, via figma-mcp-go plugin bridge. Prefer over figma skill when no API token is available. MUST load when user needs Figma data and has the desktop plugin installed.
+description: Use when you need Figma read/write access WITHOUT an API token, via figma-mcp-go plugin bridge. Prefer over figma skill when no API token is available. MUST load when user needs Figma data and has the desktop plugin installed.
 mcp:
   figma-mcp-go:
     command: npx

package/dist/template/.opencode/skill/full-output-enforcement/SKILL.md

@@ -3,6 +3,19 @@ name: full-output-enforcement
 description: MUST load when generating complete files, long code blocks, or any output where truncation or placeholder comments like '// ... rest of code' would be harmful. Bans all placeholder patterns and enforces exhaustive, unabridged output.
 ---
 
+## When to Use
+
+- When generating complete files, long code blocks, or full configuration outputs
+- When truncation or placeholder comments like `// ... rest of code` would be harmful
+- When the user needs exhaustive, unabridged output
+
+## When NOT to Use
+
+- For short code snippets or single-function responses
+- When summarization is explicitly requested
+- For conversational responses that don't involve code generation
+
+
 # Full-Output Enforcement
 
 ## Baseline

package/dist/template/.opencode/skill/high-end-visual-design/SKILL.md

@@ -3,6 +3,19 @@ name: high-end-visual-design
 description: Use INSTEAD OF design-taste-frontend when user explicitly requests premium, agency-quality, or luxury visual design. Defines exact fonts, spacing, shadows, and animations that make websites feel expensive. Blocks cheap AI defaults.
 ---
 
+## When to Use
+
+- When the user explicitly requests premium, agency-quality, or luxury visual design
+- Instead of design-taste-frontend when high-end aesthetics are the priority
+- For landing pages, marketing sites, or portfolio projects that need to feel expensive
+
+## When NOT to Use
+
+- For internal tools, admin panels, or dashboards where function > form
+- When minimalist-ui or industrial-brutalist-ui aesthetics are requested instead
+- For rapid prototyping where visual polish is not yet needed
+
+
 # Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
 
 ## 1. Meta Information & Core Directive

package/dist/template/.opencode/skill/industrial-brutalist-ui/SKILL.md

@@ -3,6 +3,19 @@ name: industrial-brutalist-ui
 description: Use INSTEAD OF design-taste-frontend when user requests brutalist, military-terminal, or raw mechanical aesthetics. Swiss typographic print meets utilitarian color. For data-heavy dashboards or editorial sites needing declassified-blueprint energy.
 ---
 
+## When to Use
+
+- When the user requests brutalist, military-terminal, or raw mechanical aesthetics
+- For data-heavy dashboards or editorial sites needing declassified-blueprint energy
+- Instead of design-taste-frontend when utilitarian aesthetics are requested
+
+## When NOT to Use
+
+- For consumer-facing marketing or e-commerce sites
+- When clean, minimalist, or luxury aesthetics are requested
+- For accessibility-critical applications where brutalist patterns may reduce readability
+
+
 # SKILL: Industrial Brutalism & Tactical Telemetry UI
 
 ## 1. Skill Meta

package/dist/template/.opencode/skill/memory-system/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: memory-system
 description: Use when persisting learnings, loading previous context, or searching past decisions - covers memory file structure, tools, and when to update each file
-version: 1.1.0
+version: 1.2.0
 tags: [context, workflow]
 dependencies: []
 ---
@@ -78,6 +78,70 @@ After creating an observation: `memory-search` with relevant keywords should fin
 - For ongoing work, append to one handoff file per task/day instead of many tiny files.
 - Keep observation titles concrete and action-oriented.
 
+## Admin Operations
+
+The `memory-admin` tool supports these operations:
+
+### Core (existing)
+| Operation | Purpose |
+|---|---|
+| `status` | Storage stats, FTS5 health, pipeline counts |
+| `full` | Full maintenance cycle (archive + checkpoint + vacuum) |
+| `archive` | Archive observations older than N days |
+| `checkpoint` | Checkpoint WAL file |
+| `vacuum` | Vacuum database |
+| `migrate` | Import .opencode/memory/observations/*.md into SQLite |
+| `capture-stats` | Temporal message capture statistics |
+| `distill-now` | Force distillation for current session |
+| `curate-now` | Force curator run |
+
+### Knowledge Intelligence (new in v2.1)
+| Operation | Purpose |
+|---|---|
+| `lint` | Find duplicates, contradictions, stale/orphan observations |
+| `index` | Generate a structured catalog of all observations |
+| `compile` | Build concept-grouped articles from observation clusters |
+| `log` | View the append-only operation audit trail |
+
+Examples:
+```
+memory-admin({ operation: "lint" })
+memory-admin({ operation: "lint", older_than_days: 60 })
+memory-admin({ operation: "index" })
+memory-admin({ operation: "compile" })
+memory-admin({ operation: "log" })
+```
+
+### Reading Compiled Artifacts
+```
+memory-read({ file: "index" })             // Full observation catalog
+memory-read({ file: "compiled/auth" })      // Compiled article for "auth" concept
+memory-read({ file: "log" })                // Operation audit trail
+```
+
+## Validation Gate
+
+The `observation` tool now validates before storing:
+- **Exact duplicate** → rejected (returns duplicate ID + supersede hint)
+- **Near-duplicate** → stored with warning
+- **Contradiction** → stored with warning (for decisions sharing concepts)
+- **Low quality** → stored with warning (no narrative + no concepts)
+
+To update an existing observation, use `supersedes`:
+```
+observation({ type: "decision", title: "Use JWT", supersedes: "42", ... })
+```
+
+## Idle Pipeline
+
+During `session.idle`, the memory system automatically runs:
+1. Distill undistilled messages
+2. Curate observations from distillations
+3. Optimize FTS5 index
+4. Checkpoint WAL if large
+5. Compile concept articles (max 10)
+6. Regenerate memory index
+
 ## See Also
 
 - `context-management`

package/dist/template/.opencode/skill/minimalist-ui/SKILL.md

@@ -3,6 +3,19 @@ name: minimalist-ui
 description: Use INSTEAD OF design-taste-frontend when user requests clean, editorial, or minimalist aesthetics. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
 ---
 
+## When to Use
+
+- When the user requests clean, editorial, or minimalist aesthetics
+- For content-focused sites, blogs, or documentation pages
+- Instead of design-taste-frontend when warm monochrome and flat layouts are desired
+
+## When NOT to Use
+
+- When bold, attention-grabbing, or luxury visual design is requested
+- For data-heavy dashboards that need dense information display
+- When industrial-brutalist-ui or high-end-visual-design is a better fit
+
+
 # Protocol: Premium Utilitarian Minimalism UI Architect
 
 ## 1. Protocol Overview

package/dist/template/.opencode/skill/redesign-existing-projects/SKILL.md

@@ -3,6 +3,19 @@ name: redesign-existing-projects
 description: Use when upgrading an existing website or app's visual design to premium quality. Audits current design, identifies generic AI patterns, applies high-end standards without breaking functionality. MUST load before any design overhaul of existing projects.
 ---
 
+## When to Use
+
+- When upgrading an existing website or app's visual design to premium quality
+- Before any design overhaul of existing projects
+- When the current design has been identified as generic, template-looking, or AI-default
+
+## When NOT to Use
+
+- For greenfield projects (use frontend-design with an aesthetic overlay instead)
+- When the design is already polished and only minor tweaks are needed
+- For non-visual changes (performance, accessibility-only fixes)
+
+
 # Redesign Skill
 
 ## How This Works

package/dist/template/.opencode/skill/requesting-code-review/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: requesting-code-review
 description: Use when completing meaningful implementation work and needing a high-signal review pass before merge or release - dispatches scoped review agents, synthesizes findings, and routes follow-up actions by severity.
-version: 1.1.0
+version: 1.2.0
 tags: [workflow, code-quality, research]
 dependencies: []
+references:
+  - references/specialist-profiles.md
 ---
 
 # Requesting Code Review
@@ -90,7 +92,9 @@ Choose the smallest review depth that still covers the risk.
 
 - **targeted**: use 1-2 specific review prompts
 - **standard**: use security/correctness, tests/types, and completeness
-- **full**: use all 5 specialized review prompts
+- **full**: use all 5 specialized review prompts + specialist profiles from [references/specialist-profiles.md](references/specialist-profiles.md)
+
+For **standard** and **full** reviews, enhance dispatch prompts with specialist reviewer profiles (security, architecture, performance) and run an adversarial pass on findings. See [references/specialist-profiles.md](references/specialist-profiles.md) for the exact prompt additions and confidence thresholds.
 
 Do **not** dispatch 5 reviewers by reflex for every tiny change. That produces noise, not rigor.
 
@@ -395,3 +399,45 @@ Run `/compound` after resolving review findings to capture:
 - Newly discovered codebase conventions
 
 That turns review from a gate into a feedback loop.
+
+## Autofix Classification
+
+Every review finding should include a **fix category** that routes remediation. This prevents the user from manually triaging every finding.
+
+| Category       | Meaning                                          | Agent Action                              |
+| -------------- | ------------------------------------------------ | ----------------------------------------- |
+| `safe_auto`    | Zero-risk fix (formatting, unused imports, typos) | Fix immediately without asking            |
+| `gated_auto`   | Likely correct fix, but verify first              | Fix and show diff before committing       |
+| `manual`       | Requires human judgment or architectural decision | Report to user with context, don't touch  |
+| `advisory`     | Informational only, no action required            | Include in report, no remediation needed  |
+
+### Reviewer Output Format (Enhanced)
+
+Reviewers should return findings in this structure:
+
+```markdown
+### [SEVERITY]: [Title]
+
+- **File:** `path/to/file.ts:123`
+- **Category:** safe_auto | gated_auto | manual | advisory
+- **Issue:** [concrete description of the problem]
+- **Fix:** [specific fix if category is safe_auto or gated_auto]
+```
+
+### Classification Rules
+
+1. **safe_auto** — formatting, whitespace, unused imports, typo in comments, missing trailing newlines. Must not change behavior.
+2. **gated_auto** — missing null checks, error handling gaps, type narrowing fixes. Changes behavior but fix is clear and low-risk.
+3. **manual** — architectural concerns, API design questions, security decisions, breaking changes. Requires human context.
+4. **advisory** — "consider doing X", performance suggestions without evidence, alternative patterns. No action needed.
+
+### Post-Synthesis Routing
+
+After synthesizing all findings:
+
+1. **Apply all `safe_auto` fixes** immediately
+2. **Show `gated_auto` diffs** to user for approval before applying
+3. **Present `manual` findings** as a prioritized list for user decision
+4. **Append `advisory` findings** at the end of the report for reference
+
+This routing ensures trivial fixes don't block the review while keeping humans in the loop for judgment calls.

package/dist/template/.opencode/skill/requesting-code-review/references/specialist-profiles.md

@@ -0,0 +1,108 @@
+# Specialist Reviewer Profiles
+
+Use these profiles when dispatching review agents for **standard** or **full** depth reviews. Each profile focuses the reviewer on a specific domain, reducing noise and increasing finding quality.
+
+## Security Reviewer
+
+**Focus:** OWASP Top 10, auth/authz, data exposure, injection, secrets
+
+**Dispatch prompt addition:**
+
+```
+You are reviewing as a SECURITY SPECIALIST. Focus exclusively on:
+
+1. Authentication/authorization gaps (missing auth checks, privilege escalation)
+2. Injection vulnerabilities (SQL, XSS, command injection, path traversal)
+3. Secrets exposure (hardcoded tokens, API keys in source, logged credentials)
+4. Data validation gaps (missing input sanitization, unsafe deserialization)
+5. Insecure defaults (permissive CORS, missing rate limiting, debug mode)
+
+Ignore: Style, architecture, performance (other reviewers handle those).
+
+Confidence threshold: Only report findings with confidence >= 0.60.
+Below 0.60, include in a separate "Low Confidence / Investigate" section.
+```
+
+**When to use:** Always in standard and full reviews. Skip only for purely internal tools with no user input.
+
+---
+
+## Architecture Reviewer
+
+**Focus:** Coupling, SOLID principles, API design, dependency direction
+
+**Dispatch prompt addition:**
+
+```
+You are reviewing as an ARCHITECTURE SPECIALIST. Focus exclusively on:
+
+1. Coupling violations (circular deps, god modules, leaky abstractions)
+2. API contract issues (breaking changes, inconsistent error formats, missing versioning)
+3. Dependency direction violations (inner layers importing outer layers)
+4. Abstraction misuse (over-engineering, unnecessary indirection, premature abstraction)
+5. Pattern divergence (new code contradicts established codebase patterns)
+
+Rules:
+- Only flag architecture issues that will cause CONCRETE problems (maintenance cost, bugs, scaling)
+- "I would have done it differently" is NOT a finding
+- Preference for existing patterns over theoretically better ones
+
+Confidence threshold: Only report findings with confidence >= 0.60.
+```
+
+**When to use:** Full reviews only. Skip for small fixes, config changes, or documentation updates.
+
+---
+
+## Performance Reviewer
+
+**Focus:** Runtime efficiency, bundle size, database queries, memory
+
+**Dispatch prompt addition:**
+
+```
+You are reviewing as a PERFORMANCE SPECIALIST. Focus exclusively on:
+
+1. N+1 query patterns (loops that make DB/API calls)
+2. Missing memoization on expensive computations
+3. Unbounded data loading (no pagination, no limits)
+4. Bundle size regressions (large imports that could be lazy-loaded)
+5. Memory leaks (event listeners without cleanup, growing caches)
+
+Rules:
+- Only flag issues with MEASURABLE impact (not theoretical)
+- "This could be faster" without evidence is NOT a finding
+- Quantify impact where possible (e.g., "This runs N queries instead of 1")
+
+Confidence threshold: Only report findings with confidence >= 0.70.
+Performance findings below 0.70 are usually speculative — suppress them.
+```
+
+**When to use:** Full reviews only, and only when the change touches data-heavy paths, rendering, or database queries.
+
+---
+
+## Adversarial Pass
+
+After all specialist reviews complete, run an adversarial pass on the combined findings. This prevents false positives from making it into the final report.
+
+**Adversarial prompt:**
+
+```
+Review these findings from specialist reviewers. For EACH finding, challenge it from these angles:
+
+1. **False positive check**: Does this issue actually exist in the code, or did the reviewer misread context?
+2. **Severity inflation**: Is the severity appropriate, or is a CRITICAL actually a MINOR?
+3. **Codebase context**: Does the existing codebase already handle this elsewhere (middleware, framework, config)?
+4. **Cost-benefit**: Is the fix worth the effort, or is this pedantic?
+
+For each finding, output:
+- CONFIRMED (keep as-is)
+- DOWNGRADED (reduce severity, explain why)
+- REJECTED (false positive, explain why)
+
+Only CONFIRMED and DOWNGRADED findings should appear in the final report.
+Confidence threshold for rejection: >= 0.60 (be sure before removing a finding).
+```
+
+**When to use:** Full reviews with 3+ specialist reviewers. Reduces noise by ~30% based on typical review output.

package/dist/template/.opencode/skill/skill-creator/SKILL.md

@@ -154,3 +154,28 @@ Answer these questions:
 - [ ] **No XML-style tags**
 - [ ] **SKILL.md under 200 lines**
 - [ ] **All referenced files exist**
+
+## Recommended Sections for SKILL.md
+
+Beyond the required structure, include these sections when applicable:
+
+### `## Gotchas`
+
+Every skill should accumulate a Gotchas section over time. This is **failure-driven documentation** — each entry should trace to a specific failure encountered during real use.
+
+```markdown
+## Gotchas
+
+- **[Short description of what went wrong]** — [What the agent did wrong, why, and the fix]. Discovered [date or session reference].
+- **[Another failure]** — [Details]. Discovered [date].
+```
+
+**Rules for Gotchas:**
+
+1. Every entry must trace to an actual failure, not a hypothetical risk
+2. Include what the agent did, why it failed, and how to avoid it
+3. New entries are added when a skill causes a failure — the fix PR should include a gotcha entry
+4. Keep entries concise (1-3 sentences each)
+5. This section grows over time and is never cleared — it's the skill's scar tissue
+
+**Why this matters:** Skills without gotchas are untested skills. A skill with 5 gotchas has been battle-tested through 5 real failures and is structurally better than a pristine skill with zero. When a skill causes a failure, always ask: "Should this become a gotcha entry?"

package/dist/template/.opencode/skill/stitch-design-taste/SKILL.md

@@ -3,6 +3,19 @@ name: stitch-design-taste
 description: Use when generating DESIGN.md files for Google Stitch projects to enforce premium, anti-generic UI standards. Load BEFORE stitch skill when design quality matters. Stitch-specific only — do not use for general web projects.
 ---
 
+## When to Use
+
+- When generating DESIGN.md files for Google Stitch projects
+- Before loading the stitch skill when design quality matters
+- When enforcing premium, anti-generic UI standards in Stitch workflows
+
+## When NOT to Use
+
+- For general web projects not using Google Stitch
+- When the stitch project already has a satisfactory DESIGN.md
+- For non-UI Stitch operations (data, API, backend)
+
+
 # Stitch Design Taste — Semantic Design System Skill
 
 ## Overview