aigroup-workflow 2.1.1 → 2.2.0

package/skills/quality/code-reviewer/references/spec-compliance-review.md

@@ -0,0 +1,258 @@
+# Spec Compliance Review
+
+---
+
+## Two-Stage Review Architecture
+
+```
+                    ┌─────────────────────┐
+                    │   Implementation    │
+                    └──────────┬──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │  STAGE 1: Spec      │
+                    │  Compliance Review  │
+                    └──────────┬──────────┘
+                               │
+              ┌────────────────┴────────────────┐
+              │                                  │
+      ┌───────▼───────┐                ┌────────▼────────┐
+      │   ✗ Issues    │                │   ✓ Compliant   │
+      │     Found     │                │                 │
+      └───────┬───────┘                └────────┬────────┘
+              │                                  │
+              │                        ┌────────▼────────┐
+              │                        │  STAGE 2: Code  │
+              │                        │  Quality Review │
+              │                        └────────┬────────┘
+              │                                  │
+              │                    ┌─────────────┴─────────────┐
+              │                    │                           │
+              │            ┌───────▼───────┐         ┌────────▼────────┐
+              │            │   ✗ Issues    │         │   ✓ Approved    │
+              │            │     Found     │         │                 │
+              │            └───────┬───────┘         └─────────────────┘
+              │                    │
+              └────────────────────┴────────────────────┐
+                                                        │
+                                              ┌─────────▼─────────┐
+                                              │ Return to Author  │
+                                              └───────────────────┘
+```
+
+**Critical:** Complete Stage 1 (spec compliance) BEFORE Stage 2 (code quality). Never review code quality for functionality that doesn't meet the specification.
+
+---
+
+## Stage 1: Spec Compliance Review
+
+### Core Directive
+
+> "The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic."
+
+Approach every review with professional skepticism. Verify claims independently.
+
+### The Three Verification Categories
+
+#### Category 1: Missing Requirements
+
+**Check for features that were requested but not implemented.**
+
+| Question | How to Verify |
+|----------|---------------|
+| Did they skip requested features? | Compare PR to original requirements line by line |
+| Are edge cases handled? | Check error paths, empty states, boundaries |
+| Were error scenarios addressed? | Look for try/catch, error boundaries, validation |
+| Is the happy path complete? | Trace through primary use case manually |
+
+```markdown
+## Example Review Finding
+
+**Missing Requirement:** Issue #42 requested "password must be at least 8 characters"
+
+**Found in code:**
+```typescript
+// No length validation present
+function validatePassword(password: string) {
+  return password.length > 0;  // Only checks non-empty
+}
+```
+
+**Status:** ❌ Incomplete - minimum length validation missing
+```
+
+#### Category 2: Unnecessary Additions
+
+**Check for scope creep and over-engineering.**
+
+| Question | How to Verify |
+|----------|---------------|
+| Features beyond specification? | Compare to original requirements |
+| Over-engineering? | Is complexity justified by requirements? |
+| Premature optimization? | Is performance cited without measurements? |
+| Unrequested abstractions? | Are there helpers/utils for one-time use? |
+
+```markdown
+## Example Review Finding
+
+**Unnecessary Addition:** Added caching layer not in requirements
+
+**Found in code:**
+```typescript
+// Original requirement: "Fetch user by ID"
+// Actual implementation:
+class CachedUserRepository {  // Not requested
+  private cache = new Map();
+  private ttl = 60000;
+
+  async getUser(id: string) {
+    if (this.cache.has(id)) { ... }
+    // 50 lines of cache logic
+  }
+}
+```
+
+**Status:** ⚠️ Scope creep - discuss before merging
+```
+
+#### Category 3: Interpretation Gaps
+
+**Check for misunderstandings of requirements.**
+
+| Question | How to Verify |
+|----------|---------------|
+| Different understanding of requirements? | Ask author to explain their interpretation |
+| Unclarified assumptions? | Look for comments like "assuming..." |
+| Ambiguous specs resolved incorrectly? | Compare to similar existing features |
+
+```markdown
+## Example Review Finding
+
+**Interpretation Gap:** "Sort by date" implemented as ascending
+
+**Requirement stated:** "Sort by date" (ambiguous)
+
+**Author implemented:** Oldest first (ascending)
+
+**Expected:** Most recent first is typical UX pattern
+
+**Status:** ❓ Clarify - which sort order was intended?
+```
+
+---
+
+## Why Order Matters
+
+### Stage 1 Must Come First
+
+| Scenario | Waste from Wrong Order |
+|----------|------------------------|
+| Skip Stage 1 | Review 500 lines of code quality, then discover wrong feature was built |
+| Stage 2 First | Suggest refactoring, then realize the code shouldn't exist |
+| Combined | Mix concerns, miss systematic issues |
+
+### Separation of Concerns
+
+- **Stage 1 (Spec):** Does it do the right thing?
+- **Stage 2 (Quality):** Does it do the thing right?
+
+Code quality review is meaningless if the code doesn't implement the correct functionality.
+
+---
+
+## Spec Compliance Checklist
+
+### Before You Start
+
+- [ ] Read the original issue/ticket completely
+- [ ] Identify all explicit requirements
+- [ ] Identify implicit requirements from context
+- [ ] Note any acceptance criteria listed
+
+### During Review
+
+**Missing Requirements:**
+- [ ] All required features present
+- [ ] Edge cases covered (empty, null, max values)
+- [ ] Error handling as specified
+- [ ] Happy path fully functional
+- [ ] UI matches mockups/specs if provided
+
+**Unnecessary Additions:**
+- [ ] No unrequested features
+- [ ] No speculative abstractions
+- [ ] No premature optimizations
+- [ ] Scope matches requirements exactly
+
+**Interpretation Gaps:**
+- [ ] Author's understanding matches spec
+- [ ] Ambiguities resolved correctly
+- [ ] Assumptions are documented and valid
+- [ ] Behavior matches similar existing features
+
+### After Review
+
+- [ ] Document all findings with file:line references
+- [ ] Categorize as missing/unnecessary/interpretation
+- [ ] Prioritize: blocking vs. non-blocking issues
+
+---
+
+## Output Format
+
+### Compliant Result
+
+```markdown
+## Spec Compliance Review: ✅ PASS
+
+All requirements verified:
+- ✅ User can upload profile image (req #1)
+- ✅ Image resized to 200x200 (req #2)
+- ✅ Invalid formats rejected with error message (req #3)
+- ✅ Progress indicator during upload (req #4)
+
+**Proceed to:** Code Quality Review
+```
+
+### Issues Found
+
+```markdown
+## Spec Compliance Review: ❌ ISSUES FOUND
+
+### Missing Requirements
+
+1. **Progress indicator not implemented** (req #4)
+   - File: `ProfileUpload.tsx`
+   - Expected: Progress bar during upload
+   - Found: No progress indication
+
+2. **Error messages not user-friendly** (req #3)
+   - File: `ProfileUpload.tsx:45`
+   - Expected: "Please upload a JPG or PNG file"
+   - Found: "Error: INVALID_FORMAT"
+
+### Unnecessary Additions
+
+1. **Image cropping feature not requested**
+   - File: `ImageCropper.tsx` (new file, 150 lines)
+   - Impact: Adds complexity, delays delivery
+   - Recommendation: Remove or create separate PR
+
+**Action Required:** Address missing requirements before code quality review
+```
+
+---
+
+## Common Mistakes to Avoid
+
+| Mistake | Why It's Wrong |
+|---------|----------------|
+| Reviewing code style before spec compliance | Wasted effort if wrong thing was built |
+| Assuming spec was followed | Verify independently |
+| Skipping edge cases | Bugs hide in boundaries |
+| Accepting "we can add it later" | Technical debt accumulates |
+| Missing scope creep | Unreviewed code enters codebase |
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/skills/quality/playwright-expert/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: playwright-expert
+description: "Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression testing. Trigger terms: Playwright, E2E test, end-to-end, browser testing, automation, UI testing, visual testing, Page Object Model, test flakiness."
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: quality
+  triggers: Playwright, E2E test, end-to-end, browser testing, automation, UI testing, visual testing
+  role: specialist
+  scope: testing
+  output-format: code
+  related-skills: test-master, react-expert, devops-engineer
+---
+
+# Playwright Expert
+
+E2E testing specialist with deep expertise in Playwright for robust, maintainable browser automation.
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify user flows to test
+2. **Setup** - Configure Playwright with proper settings
+3. **Write tests** - Use POM pattern, proper selectors, auto-waiting
+4. **Debug** - Run test → check trace → identify issue → fix → verify fix
+5. **Integrate** - Add to CI/CD pipeline
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Selectors | `references/selectors-locators.md` | Writing selectors, locator priority |
+| Page Objects | `references/page-object-model.md` | POM patterns, fixtures |
+| API Mocking | `references/api-mocking.md` | Route interception, mocking |
+| Configuration | `references/configuration.md` | playwright.config.ts setup |
+| Debugging | `references/debugging-flaky.md` | Flaky tests, trace viewer |
+
+## Constraints
+
+### MUST DO
+- Use role-based selectors when possible
+- Leverage auto-waiting (don't add arbitrary timeouts)
+- Keep tests independent (no shared state)
+- Use Page Object Model for maintainability
+- Enable traces/screenshots for debugging
+- Run tests in parallel
+
+### MUST NOT DO
+- Use `waitForTimeout()` (use proper waits)
+- Rely on CSS class selectors (brittle)
+- Share state between tests
+- Ignore flaky tests
+- Use `first()`, `nth()` without good reason
+
+## Code Examples
+
+### Selector: Role-based (correct) vs CSS class (brittle)
+
+```typescript
+// ✅ Role-based selector — resilient to styling changes
+await page.getByRole('button', { name: 'Submit' }).click();
+await page.getByLabel('Email address').fill('user@example.com');
+
+// ❌ CSS class selector — breaks on refactor
+await page.locator('.btn-primary.submit-btn').click();
+await page.locator('.email-input').fill('user@example.com');
+```
+
+### Page Object Model + Test File
+
+```typescript
+// pages/LoginPage.ts
+import { type Page, type Locator } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel('Email address');
+    this.passwordInput = page.getByLabel('Password');
+    this.submitButton = page.getByRole('button', { name: 'Sign in' });
+    this.errorMessage = page.getByRole('alert');
+  }
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+}
+```
+
+```typescript
+// tests/login.spec.ts
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+
+test.describe('Login', () => {
+  let loginPage: LoginPage;
+
+  test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    await loginPage.goto();
+  });
+
+  test('successful login redirects to dashboard', async ({ page }) => {
+    await loginPage.login('user@example.com', 'correct-password');
+    await expect(page).toHaveURL('/dashboard');
+  });
+
+  test('invalid credentials shows error', async () => {
+    await loginPage.login('user@example.com', 'wrong-password');
+    await expect(loginPage.errorMessage).toBeVisible();
+    await expect(loginPage.errorMessage).toContainText('Invalid credentials');
+  });
+});
+```
+
+### Debugging Workflow for Flaky Tests
+
+```typescript
+// 1. Run failing test with trace enabled
+// playwright.config.ts
+use: {
+  trace: 'on-first-retry',
+  screenshot: 'only-on-failure',
+}
+
+// 2. Re-run with retries to capture trace
+// npx playwright test --retries=2
+
+// 3. Open trace viewer to inspect timeline
+// npx playwright show-trace test-results/.../trace.zip
+
+// 4. Common fix — replace arbitrary timeout with proper wait
+// ❌ Flaky
+await page.waitForTimeout(2000);
+await page.getByRole('button', { name: 'Save' }).click();
+
+// ✅ Reliable — waits for element state
+await page.getByRole('button', { name: 'Save' }).waitFor({ state: 'visible' });
+await page.getByRole('button', { name: 'Save' }).click();
+
+// 5. Verify fix — run test 10x to confirm stability
+// npx playwright test --repeat-each=10
+```
+
+## Output Templates
+
+When implementing Playwright tests, provide:
+1. Page Object classes
+2. Test files with proper assertions
+3. Fixture setup if needed
+4. Configuration recommendations
+
+## Knowledge Reference
+
+Playwright, Page Object Model, auto-waiting, locators, fixtures, API mocking, trace viewer, visual comparisons, parallel execution, CI/CD integration

package/skills/quality/playwright-expert/references/api-mocking.md

@@ -0,0 +1,140 @@
+# API Mocking
+
+## Basic Route Mocking
+
+```typescript
+test('displays mocked user data', async ({ page }) => {
+  await page.route('**/api/users', route =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' },
+      ]),
+    })
+  );
+
+  await page.goto('/users');
+  await expect(page.getByText('Alice')).toBeVisible();
+  await expect(page.getByText('Bob')).toBeVisible();
+});
+```
+
+## Mock Error Responses
+
+```typescript
+test('handles API error gracefully', async ({ page }) => {
+  await page.route('**/api/users', route =>
+    route.fulfill({
+      status: 500,
+      body: JSON.stringify({ error: 'Server error' }),
+    })
+  );
+
+  await page.goto('/users');
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+});
+```
+
+## Conditional Mocking
+
+```typescript
+test('mock specific requests', async ({ page }) => {
+  await page.route('**/api/**', route => {
+    const url = route.request().url();
+
+    if (url.includes('/api/users')) {
+      return route.fulfill({
+        status: 200,
+        json: [{ id: 1, name: 'Mocked User' }],
+      });
+    }
+
+    // Let other requests through
+    return route.continue();
+  });
+});
+```
+
+## Modify Responses
+
+```typescript
+test('modify API response', async ({ page }) => {
+  await page.route('**/api/products', async route => {
+    // Get real response
+    const response = await route.fetch();
+    const json = await response.json();
+
+    // Modify it
+    json.products = json.products.map(p => ({
+      ...p,
+      price: p.price * 0.9, // 10% discount
+    }));
+
+    // Return modified response
+    await route.fulfill({ json });
+  });
+});
+```
+
+## Wait for Response
+
+```typescript
+test('waits for API response', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  await page.getByRole('button', { name: 'Load Users' }).click();
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+```
+
+## Mock Network Conditions
+
+```typescript
+test('slow network', async ({ page }) => {
+  await page.route('**/api/**', async route => {
+    await new Promise(resolve => setTimeout(resolve, 3000));
+    await route.continue();
+  });
+
+  await page.goto('/dashboard');
+  await expect(page.getByText('Loading...')).toBeVisible();
+});
+```
+
+## HAR File Mocking
+
+```typescript
+// Record responses
+await page.routeFromHAR('mocks/api.har', {
+  url: '**/api/**',
+  update: true, // Record new responses
+});
+
+// Playback recorded responses
+await page.routeFromHAR('mocks/api.har', {
+  url: '**/api/**',
+  update: false,
+});
+```
+
+## Quick Reference
+
+| Method | Purpose |
+|--------|---------|
+| `route.fulfill()` | Return mock response |
+| `route.continue()` | Pass to real server |
+| `route.fetch()` | Get real response |
+| `route.abort()` | Block request |
+| `waitForResponse()` | Wait for API call |
+| `routeFromHAR()` | Use recorded responses |
+
+| Pattern | Use Case |
+|---------|----------|
+| Mock all | Isolated testing |
+| Mock errors | Error handling |
+| Modify response | Test edge cases |
+| Network delay | Loading states |