opencode-agile-agent 1.0.1 → 1.0.2

package/templates/.opencode/skills/systematic-debugging/SKILL.md

@@ -1,210 +1,38 @@
 ---
 name: systematic-debugging
-description: Methodical approach to identifying and fixing bugs.
-version: 1.0.0
+description: Reproduce, isolate, test hypotheses, fix the root cause, and verify the recovery.
 ---
 
 # Systematic Debugging
 
-A methodical approach to finding and fixing bugs efficiently.
+## Philosophy
+Fix the cause, not the shape of the symptom. Debugging is a search for truth, not a guessing game.
 
-## Debugging Methodology
+## Use When
+- Something is broken, flaky, or behaving unexpectedly.
+- You need root-cause analysis before a fix.
+- A regression, crash, or slowdown needs a controlled investigation.
 
-### The Scientific Method
+## Core Moves
+- Reproduce the issue with the smallest reliable steps.
+- Change one variable at a time.
+- Use evidence from logs, traces, and diffs.
+- Confirm the fix with the original reproduction path and edge cases.
 
-1. **Observe** - What's the symptom?
-2. **Hypothesize** - What could cause this?
-3. **Test** - Verify or disprove hypothesis
-4. **Repeat** - Until root cause found
-5. **Fix** - Address the root cause
-6. **Verify** - Confirm fix works
-7. **Document** - Record for future
+## Default Moves
+- Capture exact steps, environment, and recent changes first.
+- Test the highest-probability hypothesis before broad changes.
+- Add a regression test or safeguard once the fix is proven.
 
-## Step-by-Step Process
+## Anti-Patterns
+- Shotgun debugging, symptom-only fixes, excessive logging, and changing multiple things at once.
 
-### Step 1: Reproduce
+## Variation
+- Use bisect for regressions, profiler for perf, and traces for async bugs.
+- Use the cheapest evidence source that can disprove the current hypothesis.
 
-```markdown
-Document exact steps:
-1. Open browser
-2. Navigate to /dashboard
-3. Click "Export" button
-4. Error appears
+## Output
+- Return the reproduction, root cause, minimal fix, verification, and prevention step.
 
-Environment:
-- Browser: Chrome 120
-- OS: macOS 14
-- Node: v20.10.0
-```
-
-### Step 2: Gather Information
-
-```bash
-# Check logs
-tail -f /var/log/app.log
-
-# Check recent changes
-git log --oneline -10
-
-# Check error stack trace
-Error: Cannot read property 'map' of undefined
-    at exportData (src/utils/export.ts:45)
-    at handleClick (src/components/ExportButton.tsx:23)
-```
-
-### Step 3: Hypothesize
-
-```markdown
-Possible causes (ranked by likelihood):
-1. data is null/undefined when exportData is called
-2. data structure changed but exportData not updated
-3. Race condition in data loading
-4. API returning unexpected format
-```
-
-### Step 4: Test Hypotheses
-
-```typescript
-// Add defensive logging
-console.log('exportData called with:', { data, type: typeof data });
-
-// Add type guard
-if (!data || !Array.isArray(data)) {
-  console.error('Invalid data for export:', data);
-  return;
-}
-```
-
-### Step 5: Fix Root Cause
-
-```typescript
-// ❌ Fix symptom only
-const items = data?.items || []; // Hides the real problem
-
-// ✅ Fix root cause
-// Investigate WHY data is undefined and fix upstream
-async function loadData() {
-  const response = await fetch('/api/data');
-  if (!response.ok) {
-    throw new Error(`Failed to load data: ${response.status}`);
-  }
-  return response.json();
-}
-```
-
-## Common Bug Patterns
-
-### Null/Undefined Errors
-
-```typescript
-// ❌ Crashes on null
-const name = user.profile.name;
-
-// ✅ Safe access
-const name = user?.profile?.name ?? 'Unknown';
-```
-
-### Race Conditions
-
-```typescript
-// ❌ Race condition
-let data;
-fetchData().then(result => { data = result; });
-console.log(data); // undefined!
-
-// ✅ Proper async handling
-const data = await fetchData();
-console.log(data);
-```
-
-### State Sync Issues
-
-```typescript
-// ❌ Stale closure
-const [count, setCount] = useState(0);
-useEffect(() => {
-  const interval = setInterval(() => {
-    console.log(count); // Always 0!
-  }, 1000);
-  return () => clearInterval(interval);
-}, []);
-
-// ✅ Use ref or dependency
-const countRef = useRef(count);
-countRef.current = count;
-// Or add count to dependencies
-```
-
-## Debugging Tools
-
-### Console Debugging
-
-```typescript
-// Strategic logging
-console.log('1. Before fetch');
-const data = await fetch(url);
-console.log('2. After fetch:', data);
-const processed = processData(data);
-console.log('3. After process:', processed);
-
-// Performance timing
-console.time('operation');
-doSomething();
-console.timeEnd('operation');
-```
-
-### Browser DevTools
-
-```
-1. Sources panel - Set breakpoints
-2. Network panel - Check API calls
-3. Console - Run expressions
-4. React DevTools - Component tree
-5. Performance - Record profile
-```
-
-### Node.js Debugging
-
-```bash
-# Inspector mode
-node --inspect app.js
-
-# Then open chrome://inspect
-```
-
-## Debugging Checklist
-
-- [ ] **Reproduced**: Can consistently reproduce
-- [ ] **Isolated**: Narrowed to specific area
-- [ ] **Root cause**: Understand WHY
-- [ ] **Fix implemented**: Addresses cause, not symptom
-- [ ] **Verified**: Fix resolves the issue
-- [ ] **No regressions**: Other functionality intact
-- [ ] **Tests added**: Prevents future occurrences
-
-## Anti-Patterns to Avoid
-
-### Shotgun Debugging
-
-```
-❌ Change random things hoping it works
-✅ Change one thing at a time, verify each
-```
-
-### Console.log Everything
-
-```
-❌ console.log everywhere
-✅ Strategic, minimal logging with context
-```
-
-### Fix Symptom, Not Cause
-
-```
-❌ Add null check to hide error
-✅ Find why null occurs and fix upstream
-```
-
----
-
-**Systematic debugging finds root causes faster.**
+## Remember
+A good debug session leaves the system easier to reason about than before.

package/templates/.opencode/skills/testing-patterns/SKILL.md

@@ -1,252 +1,39 @@
 ---
 name: testing-patterns
-description: Testing strategies, patterns, and best practices for unit, integration, and E2E tests.
-version: 1.0.0
+description: Choose unit, integration, or E2E tests that prove behavior without overspecifying implementation.
 ---
 
 # Testing Patterns
 
-Comprehensive testing strategies and best practices.
+## Philosophy
+Tests are executable specs. They should protect behavior, not lock you into internals.
 
-## Testing Pyramid
+## Use When
+- You are adding tests or choosing the right test layer.
+- Coverage needs to increase without making the suite flaky.
+- A feature needs confidence before merge or release.
 
-```
-        /\
-       /E2E\      Few, slow, critical paths
-      /------\    
-     /  API   \   Some, integration tests
-    /----------\
-   /   Unit     \  Many, fast, isolated
-  /--------------\
-```
+## Core Moves
+- Follow the pyramid: many unit tests, some integration tests, few E2E tests.
+- Test behavior over implementation details.
+- Keep tests deterministic, isolated, and readable.
+- Use resilient selectors and stable fixtures.
 
-## Unit Testing
-
-### AAA Pattern
-
-```typescript
-describe('calculateTotal', () => {
-  it('should sum item prices', () => {
-    // Arrange
-    const items = [{ price: 10 }, { price: 20 }];
-    
-    // Act
-    const result = calculateTotal(items);
-    
-    // Assert
-    expect(result).toBe(30);
-  });
-});
-```
-
-### Test Edge Cases
-
-```typescript
-describe('calculateTotal', () => {
-  it('should handle empty array', () => {
-    expect(calculateTotal([])).toBe(0);
-  });
-  
-  it('should handle null', () => {
-    expect(calculateTotal(null)).toBe(0);
-  });
-  
-  it('should handle negative prices', () => {
-    expect(calculateTotal([{ price: -5 }])).toBe(-5);
-  });
-});
-```
-
-### Mocking
-
-```typescript
-// Mock external dependency
-jest.mock('./api');
-api.fetchUser.mockResolvedValue({ id: 1, name: 'Test' });
-
-// Mock function
-const mockCallback = jest.fn();
-mockCallback.mockReturnValue(true);
-mockCallback.mockImplementation(x => x * 2);
-```
-
-## Integration Testing
-
-### API Testing
-
-```typescript
-describe('POST /api/users', () => {
-  it('should create user with valid data', async () => {
-    const response = await request(app)
-      .post('/api/users')
-      .send({ name: 'Test', email: 'test@example.com' });
-    
-    expect(response.status).toBe(201);
-    expect(response.body.data.name).toBe('Test');
-  });
-  
-  it('should reject invalid email', async () => {
-    const response = await request(app)
-      .post('/api/users')
-      .send({ name: 'Test', email: 'invalid' });
-    
-    expect(response.status).toBe(400);
-  });
-});
-```
-
-### Database Testing
-
-```typescript
-describe('UserService', () => {
-  beforeAll(async () => {
-    await setupTestDatabase();
-  });
-  
-  afterAll(async () => {
-    await teardownTestDatabase();
-  });
-  
-  beforeEach(async () => {
-    await clearDatabase();
-  });
-  
-  it('should create user', async () => {
-    const user = await UserService.create({ name: 'Test' });
-    expect(user.id).toBeDefined();
-  });
-});
-```
-
-## E2E Testing
-
-### Page Object Model
-
-```typescript
-// pages/LoginPage.ts
-export class LoginPage {
-  constructor(private page: Page) {}
-  
-  async goto() {
-    await this.page.goto('/login');
-  }
-  
-  async login(email: string, password: string) {
-    await this.page.fill('[data-testid="email"]', email);
-    await this.page.fill('[data-testid="password"]', password);
-    await this.page.click('[data-testid="login-btn"]');
-  }
-}
-
-// tests/auth.spec.ts
-test('should login successfully', async ({ page }) => {
-  const loginPage = new LoginPage(page);
-  await loginPage.goto();
-  await loginPage.login('user@example.com', 'password');
-  
-  await expect(page).toHaveURL('/dashboard');
-});
-```
-
-### Test Selectors
-
-```typescript
-// ❌ Brittle
-await page.locator('.card > .title').click();
-
-// ✅ Resilient
-await page.locator('[data-testid="product-title"]').click();
-```
-
-## Test Organization
-
-```
-tests/
-├── unit/
-│   ├── utils/
-│   │   └── calculate.test.ts
-│   └── components/
-│       └── Button.test.tsx
-├── integration/
-│   ├── api/
-│   │   └── users.test.ts
-│   └── services/
-│       └── auth.test.ts
-└── e2e/
-    ├── auth.spec.ts
-    └── checkout.spec.ts
-```
-
-## Coverage Guidelines
-
-| Type | Target |
-|------|--------|
-| Statements | 80% |
-| Branches | 75% |
-| Functions | 85% |
-| Lines | 80% |
-
-## Best Practices
-
-### Descriptive Names
-
-```typescript
-// ❌ Vague
-test('user', () => {});
-
-// ✅ Descriptive
-test('should create user with valid email', () => {});
-```
-
-### One Concept Per Test
-
-```typescript
-// ❌ Multiple concepts
-test('user operations', () => {
-  // Test create
-  // Test update
-  // Test delete
-});
-
-// ✅ One concept
-test('should create user', () => {});
-test('should update user', () => {});
-test('should delete user', () => {});
-```
-
-### Test Behavior, Not Implementation
-
-```typescript
-// ❌ Tests implementation
-expect(component.state.count).toBe(1);
-
-// ✅ Tests behavior
-expect(screen.getByText('Count: 1')).toBeInTheDocument();
-```
+## Default Moves
+- Use unit tests for pure logic, integration tests for boundaries, and E2E for critical journeys.
+- Use AAA or Given-When-Then for clarity.
+- Add the cheapest test that proves the risk.
 
 ## Anti-Patterns
+- Testing internals, shared state, flaky timing, overspecifying every property, and too many E2E tests.
 
-### Testing Implementation
-
-```
-❌ Test that function calls internal helper
-✅ Test the output/behavior
-```
-
-### Shared State
+## Variation
+- Use page objects for complex browser flows.
+- Mock only at the boundary you do not want to test.
+- Choose a lower layer when the same confidence can be achieved more cheaply.
 
-```
-❌ Tests that depend on each other
-✅ Each test is independent
-```
-
-### Overspecifying
-
-```
-❌ Assert every property
-✅ Assert essential behavior
-```
-
----
+## Output
+- Return the test plan, the coverage gap, and the recommended layer for each risk.
 
-**Good tests enable confident refactoring.**
+## Remember
+The best test suite is small enough to trust and broad enough to matter.