opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/code-showcase-react-ui-patterns/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: code-showcase-react-ui-patterns
+description: Modern React UI patterns for loading states, error handling, and data fetching. Use when building UI components, handling async data, or managing UI states.
+risk: unknown
+source: https://github.com/ChrisWiles/claude-code-showcase/tree/main/.claude/skills/react-ui-patterns
+source_repo: ChrisWiles/claude-code-showcase
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/ChrisWiles/claude-code-showcase/blob/main/LICENSE
+---
+
+# React UI Patterns
+## When to Use
+
+Use this skill when you need modern React UI patterns for loading states, error handling, and data fetching. Use when building UI components, handling async data, or managing UI states.
+
+
+## Core Principles
+
+1. **Never show stale UI** - Loading spinners only when actually loading
+2. **Always surface errors** - Users must know when something fails
+3. **Optimistic updates** - Make the UI feel instant
+4. **Progressive disclosure** - Show content as it becomes available
+5. **Graceful degradation** - Partial data is better than no data
+
+## Loading State Patterns
+
+### The Golden Rule
+
+**Show loading indicator ONLY when there's no data to display.**
+
+```typescript
+// CORRECT - Only show loading when no data exists
+const { data, loading, error } = useGetItemsQuery();
+
+if (error) return <ErrorState error={error} onRetry={refetch} />;
+if (loading && !data) return <LoadingState />;
+if (!data?.items.length) return <EmptyState />;
+
+return <ItemList items={data.items} />;
+```
+
+```typescript
+// WRONG - Shows spinner even when we have cached data
+if (loading) return <LoadingState />; // Flashes on refetch!
+```
+
+### Loading State Decision Tree
+
+```
+Is there an error?
+  → Yes: Show error state with retry option
+  → No: Continue
+
+Is it loading AND we have no data?
+  → Yes: Show loading indicator (spinner/skeleton)
+  → No: Continue
+
+Do we have data?
+  → Yes, with items: Show the data
+  → Yes, but empty: Show empty state
+  → No: Show loading (fallback)
+```
+
+### Skeleton vs Spinner
+
+| Use Skeleton When | Use Spinner When |
+|-------------------|------------------|
+| Known content shape | Unknown content shape |
+| List/card layouts | Modal actions |
+| Initial page load | Button submissions |
+| Content placeholders | Inline operations |
+
+## Error Handling Patterns
+
+### The Error Handling Hierarchy
+
+```
+1. Inline error (field-level) → Form validation errors
+2. Toast notification → Recoverable errors, user can retry
+3. Error banner → Page-level errors, data still partially usable
+4. Full error screen → Unrecoverable, needs user action
+```
+
+### Always Show Errors
+
+**CRITICAL: Never swallow errors silently.**
+
+```typescript
+// CORRECT - Error always surfaced to user
+const [createItem, { loading }] = useCreateItemMutation({
+  onCompleted: () => {
+    toast.success({ title: 'Item created' });
+  },
+  onError: (error) => {
+    console.error('createItem failed:', error);
+    toast.error({ title: 'Failed to create item' });
+  },
+});
+
+// WRONG - Error silently caught, user has no idea
+const [createItem] = useCreateItemMutation({
+  onError: (error) => {
+    console.error(error); // User sees nothing!
+  },
+});
+```
+
+### Error State Component Pattern
+
+```typescript
+interface ErrorStateProps {
+  error: Error;
+  onRetry?: () => void;
+  title?: string;
+}
+
+const ErrorState = ({ error, onRetry, title }: ErrorStateProps) => (
+  <div className="error-state">
+    <Icon name="exclamation-circle" />
+    <h3>{title ?? 'Something went wrong'}</h3>
+    <p>{error.message}</p>
+    {onRetry && (
+      <Button onClick={onRetry}>Try Again</Button>
+    )}
+  </div>
+);
+```
+
+## Button State Patterns
+
+### Button Loading State
+
+```tsx
+<Button
+  onClick={handleSubmit}
+  isLoading={isSubmitting}
+  disabled={!isValid || isSubmitting}
+>
+  Submit
+</Button>
+```
+
+### Disable During Operations
+
+**CRITICAL: Always disable triggers during async operations.**
+
+```tsx
+// CORRECT - Button disabled while loading
+<Button
+  disabled={isSubmitting}
+  isLoading={isSubmitting}
+  onClick={handleSubmit}
+>
+  Submit
+</Button>
+
+// WRONG - User can tap multiple times
+<Button onClick={handleSubmit}>
+  {isSubmitting ? 'Submitting...' : 'Submit'}
+</Button>
+```
+
+## Empty States
+
+### Empty State Requirements
+
+Every list/collection MUST have an empty state:
+
+```tsx
+// WRONG - No empty state
+return <FlatList data={items} />;
+
+// CORRECT - Explicit empty state
+return (
+  <FlatList
+    data={items}
+    ListEmptyComponent={<EmptyState />}
+  />
+);
+```
+
+### Contextual Empty States
+
+```tsx
+// Search with no results
+<EmptyState
+  icon="search"
+  title="No results found"
+  description="Try different search terms"
+/>
+
+// List with no items yet
+<EmptyState
+  icon="plus-circle"
+  title="No items yet"
+  description="Create your first item"
+  action={{ label: 'Create Item', onClick: handleCreate }}
+/>
+```
+
+## Form Submission Pattern
+
+```tsx
+const MyForm = () => {
+  const [submit, { loading }] = useSubmitMutation({
+    onCompleted: handleSuccess,
+    onError: handleError,
+  });
+
+  const handleSubmit = async () => {
+    if (!isValid) {
+      toast.error({ title: 'Please fix errors' });
+      return;
+    }
+    await submit({ variables: { input: values } });
+  };
+
+  return (
+    <form>
+      <Input
+        value={values.name}
+        onChange={handleChange('name')}
+        error={touched.name ? errors.name : undefined}
+      />
+      <Button
+        type="submit"
+        onClick={handleSubmit}
+        disabled={!isValid || loading}
+        isLoading={loading}
+      >
+        Submit
+      </Button>
+    </form>
+  );
+};
+```
+
+## Anti-Patterns
+
+### Loading States
+
+```typescript
+// WRONG - Spinner when data exists (causes flash)
+if (loading) return <Spinner />;
+
+// CORRECT - Only show loading without data
+if (loading && !data) return <Spinner />;
+```
+
+### Error Handling
+
+```typescript
+// WRONG - Error swallowed
+try {
+  await mutation();
+} catch (e) {
+  console.log(e); // User has no idea!
+}
+
+// CORRECT - Error surfaced
+onError: (error) => {
+  console.error('operation failed:', error);
+  toast.error({ title: 'Operation failed' });
+}
+```
+
+### Button States
+
+```typescript
+// WRONG - Button not disabled during submission
+<Button onClick={submit}>Submit</Button>
+
+// CORRECT - Disabled and shows loading
+<Button onClick={submit} disabled={loading} isLoading={loading}>
+  Submit
+</Button>
+```
+
+## Checklist
+
+Before completing any UI component:
+
+**UI States:**
+- [ ] Error state handled and shown to user
+- [ ] Loading state shown only when no data exists
+- [ ] Empty state provided for collections
+- [ ] Buttons disabled during async operations
+- [ ] Buttons show loading indicator when appropriate
+
+**Data & Mutations:**
+- [ ] Mutations have onError handler
+- [ ] All user actions have feedback (toast/visual)
+
+## Integration with Other Skills
+
+- **graphql-schema**: Use mutation patterns with proper error handling
+- **testing-patterns**: Test all UI states (loading, error, empty, success)
+- **formik-patterns**: Apply form submission patterns
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/code-showcase-systematic-debugging/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: code-showcase-systematic-debugging
+description: Four-phase debugging methodology with root cause analysis. Use when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST.
+risk: unknown
+source: https://github.com/ChrisWiles/claude-code-showcase/tree/main/.claude/skills/systematic-debugging
+source_repo: ChrisWiles/claude-code-showcase
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/ChrisWiles/claude-code-showcase/blob/main/LICENSE
+---
+
+# Systematic Debugging
+## When to Use
+
+Use this skill when you need four-phase debugging methodology with root cause analysis. Use when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST.
+
+
+## Core Principle
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+Never apply symptom-focused patches that mask underlying problems. Understand WHY something fails before attempting to fix it.
+
+## The Four-Phase Framework
+
+### Phase 1: Root Cause Investigation
+
+Before touching any code:
+
+1. **Read error messages thoroughly** - Every word matters
+2. **Reproduce the issue consistently** - If you can't reproduce it, you can't verify a fix
+3. **Examine recent changes** - What changed before this started failing?
+4. **Gather diagnostic evidence** - Logs, stack traces, state dumps
+5. **Trace data flow** - Follow the call chain to find where bad values originate
+
+**Root Cause Tracing Technique:**
+```
+1. Observe the symptom - Where does the error manifest?
+2. Find immediate cause - Which code directly produces the error?
+3. Ask "What called this?" - Map the call chain upward
+4. Keep tracing up - Follow invalid data backward through the stack
+5. Find original trigger - Where did the problem actually start?
+```
+
+**Key principle:** Never fix problems solely where errors appear—always trace to the original trigger.
+
+### Phase 2: Pattern Analysis
+
+1. **Locate working examples** - Find similar code that works correctly
+2. **Compare implementations completely** - Don't just skim
+3. **Identify differences** - What's different between working and broken?
+4. **Understand dependencies** - What does this code depend on?
+
+### Phase 3: Hypothesis and Testing
+
+Apply the scientific method:
+
+1. **Formulate ONE clear hypothesis** - "The error occurs because X"
+2. **Design minimal test** - Change ONE variable at a time
+3. **Predict the outcome** - What should happen if hypothesis is correct?
+4. **Run the test** - Execute and observe
+5. **Verify results** - Did it behave as predicted?
+6. **Iterate or proceed** - Refine hypothesis if wrong, implement if right
+
+### Phase 4: Implementation
+
+1. **Create failing test case** - Captures the bug behavior
+2. **Implement single fix** - Address root cause, not symptoms
+3. **Verify test passes** - Confirms fix works
+4. **Run full test suite** - Ensure no regressions
+5. **If fix fails, STOP** - Re-evaluate hypothesis
+
+**Critical rule:** If THREE or more fixes fail consecutively, STOP. This signals architectural problems requiring discussion, not more patches.
+
+## Red Flags - Process Violations
+
+Stop immediately if you catch yourself thinking:
+
+- "Quick fix for now, investigate later"
+- "One more fix attempt" (after multiple failures)
+- "This should work" (without understanding why)
+- "Let me just try..." (without hypothesis)
+- "It works on my machine" (without investigating difference)
+
+## Warning Signs of Deeper Problems
+
+**Consecutive fixes revealing new problems in different areas** indicates architectural issues:
+
+- Stop patching
+- Document what you've found
+- Discuss with team before proceeding
+- Consider if the design needs rethinking
+
+## Common Debugging Scenarios
+
+### Test Failures
+
+```
+1. Read the FULL error message and stack trace
+2. Identify which assertion failed and why
+3. Check test setup - is the test environment correct?
+4. Check test data - are mocks/fixtures correct?
+5. Trace to the source of unexpected value
+```
+
+### Runtime Errors
+
+```
+1. Capture the full stack trace
+2. Identify the line that throws
+3. Check what values are undefined/null
+4. Trace backward to find where bad value originated
+5. Add validation at the source
+```
+
+### "It worked before"
+
+```
+1. Use git bisect to find the breaking commit
+2. Compare the change with previous working version
+3. Identify what assumption changed
+4. Fix at the source of the assumption violation
+```
+
+### Intermittent Failures
+
+```
+1. Look for race conditions
+2. Check for shared mutable state
+3. Examine async operation ordering
+4. Look for timing dependencies
+5. Add deterministic waits or proper synchronization
+```
+
+## Debugging Checklist
+
+Before claiming a bug is fixed:
+
+- [ ] Root cause identified and documented
+- [ ] Hypothesis formed and tested
+- [ ] Fix addresses root cause, not symptoms
+- [ ] Failing test created that reproduces bug
+- [ ] Test now passes with fix
+- [ ] Full test suite passes
+- [ ] No "quick fix" rationalization used
+- [ ] Fix is minimal and focused
+
+## Success Metrics
+
+Systematic debugging achieves ~95% first-time fix rate vs ~40% with ad-hoc approaches.
+
+Signs you're doing it right:
+- Fixes don't create new bugs
+- You can explain WHY the bug occurred
+- Similar bugs don't recur
+- Code is better after the fix, not just "working"
+
+## Integration with Other Skills
+
+- **testing-patterns**: Create test that reproduces the bug before fixing
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.