aigroup-workflow 2.1.2 → 2.2.0

package/skills/backend/debugging-wizard/references/systematic-debugging.md

@@ -0,0 +1,367 @@
+# Systematic Debugging
+
+---
+
+## Core Principle
+
+> **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+Jumping to fixes without understanding causes creates more bugs. Systematic debugging prevents the "fix one thing, break two more" cycle.
+
+---
+
+## The Four Mandatory Phases
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SYSTEMATIC DEBUGGING                      │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 1: ROOT CAUSE INVESTIGATION                          │
+│  ├── Read error messages thoroughly                         │
+│  ├── Reproduce reliably with documented steps               │
+│  ├── Examine recent changes                                 │
+│  └── Trace data flow backward                               │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 2: PATTERN ANALYSIS                                   │
+│  ├── Find similar working implementations                   │
+│  ├── Study reference implementations completely             │
+│  └── Document all differences                               │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 3: HYPOTHESIS TESTING                                 │
+│  ├── Form specific, written hypothesis                      │
+│  ├── Test with minimal, isolated changes                    │
+│  └── One variable at a time                                 │
+├─────────────────────────────────────────────────────────────┤
+│  Phase 4: IMPLEMENTATION                                     │
+│  ├── Create failing test case                               │
+│  ├── Implement single fix addressing root cause             │
+│  └── Verify no new breakage                                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: Root Cause Investigation
+
+**Objective:** Understand exactly what is failing and why before attempting any fix.
+
+### Step 1.1: Read Error Messages Thoroughly
+
+```bash
+# Don't just read the first line
+TypeError: Cannot read property 'map' of undefined
+    at UserList.render (UserList.tsx:24)
+    at renderWithHooks (react-dom.js:14985)
+    at mountIndeterminateComponent (react-dom.js:17811)
+```
+
+**Key questions:**
+- What exact operation failed?
+- Where in the code (file, line)?
+- What was the call stack?
+- Are there multiple errors or just one?
+
+### Step 1.2: Reproduce Reliably
+
+```markdown
+## Reproduction Steps
+1. Navigate to /users
+2. Click "Load More" button
+3. Wait for loading spinner
+4. **ERROR: "Cannot read property 'map' of undefined"**
+
+## Environment
+- Browser: Chrome 120
+- User: Admin role
+- Data state: 50+ users in database
+```
+
+**Requirement:** Document exact steps that reproduce the bug 100% of the time.
+
+### Step 1.3: Examine Recent Changes
+
+```bash
+# What changed recently?
+git log --oneline -10
+
+# What specifically changed in the failing file?
+git log -p UserList.tsx
+
+# When did this start failing?
+git bisect start
+git bisect bad HEAD
+git bisect good v1.2.0
+```
+
+### Step 1.4: Trace Data Flow Backward
+
+```typescript
+// Error happens here:
+users.map(u => u.name)  // users is undefined
+
+// Trace backward:
+// Where does 'users' come from?
+const users = props.users;
+
+// Where do props come from?
+<UserList users={data.users} />
+
+// Where does data come from?
+const { data } = useQuery(GET_USERS);
+
+// ROOT CAUSE: Query returns { users: null } when loading
+```
+
+### Step 1.5: Add Diagnostic Instrumentation
+
+```typescript
+// Add temporary logging at boundaries
+console.log('[UserList] props:', JSON.stringify(props));
+console.log('[UserList] users type:', typeof props.users);
+console.log('[UserList] users value:', props.users);
+
+// Check at data source
+console.log('[API] Response:', response);
+console.log('[API] Response.data:', response.data);
+```
+
+---
+
+## Phase 2: Pattern Analysis
+
+**Objective:** Find working examples to understand what correct behavior looks like.
+
+### Step 2.1: Locate Similar Working Implementations
+
+```bash
+# Find similar components that work correctly
+grep -r "useQuery" src/components/ --include="*.tsx"
+
+# Find how other lists handle loading states
+grep -r "loading" src/components/*List* --include="*.tsx"
+```
+
+### Step 2.2: Study Reference Implementations Completely
+
+```typescript
+// WORKING: ProductList.tsx
+function ProductList({ products, loading }) {
+  if (loading) return <Spinner />;
+  if (!products) return null;  // ← Handles undefined case
+
+  return products.map(p => <ProductItem key={p.id} {...p} />);
+}
+
+// BROKEN: UserList.tsx
+function UserList({ users, loading }) {
+  if (loading) return <Spinner />;
+  // Missing: !users check
+
+  return users.map(u => <UserItem key={u.id} {...u} />);  // 💥 Crashes
+}
+```
+
+### Step 2.3: Document All Differences
+
+| Aspect | Working (ProductList) | Broken (UserList) |
+|--------|----------------------|-------------------|
+| Null check | `if (!products)` | Missing |
+| Default value | `products ?? []` | None |
+| Loading handled | Before render | Before render |
+| Error handled | Returns ErrorState | Missing |
+
+---
+
+## Phase 3: Hypothesis Testing
+
+**Objective:** Verify your understanding with controlled experiments.
+
+### Step 3.1: Form Specific, Written Hypothesis
+
+```markdown
+## Hypothesis #1
+**Statement:** The crash occurs because `users` is undefined when the
+query is complete but returns no data.
+
+**Prediction:** Adding a null check before `.map()` will prevent the crash.
+
+**Test:** Add `if (!users) return null;` before the map call.
+```
+
+### Step 3.2: Test with Minimal Changes
+
+```typescript
+// Change ONLY one thing
+function UserList({ users, loading }) {
+  if (loading) return <Spinner />;
+  if (!users) return null;  // ← Single change
+
+  return users.map(u => <UserItem key={u.id} {...u} />);
+}
+```
+
+### Step 3.3: One Variable at a Time
+
+```markdown
+## Test Results
+
+| Hypothesis | Change | Result | Conclusion |
+|------------|--------|--------|------------|
+| #1: Null check | Add `if (!users)` | ✓ Pass | Confirmed |
+
+Do NOT test multiple hypotheses simultaneously.
+```
+
+---
+
+## Phase 4: Implementation
+
+**Objective:** Fix the bug permanently with proper safeguards.
+
+### Step 4.1: Create Failing Test Case First
+
+```typescript
+describe('UserList', () => {
+  it('should handle undefined users gracefully', () => {
+    // This test should FAIL before the fix
+    const { container } = render(<UserList users={undefined} loading={false} />);
+    expect(container).not.toThrow();
+    expect(screen.queryByRole('list')).not.toBeInTheDocument();
+  });
+});
+```
+
+### Step 4.2: Implement Single Fix
+
+```typescript
+function UserList({ users, loading }: UserListProps) {
+  if (loading) return <Spinner />;
+  if (!users || users.length === 0) {
+    return <EmptyState message="No users found" />;
+  }
+
+  return (
+    <ul role="list">
+      {users.map(u => <UserItem key={u.id} {...u} />)}
+    </ul>
+  );
+}
+```
+
+### Step 4.3: Verify No New Breakage
+
+```bash
+# Run full test suite
+npm test
+
+# Run specific component tests
+npm test UserList
+
+# Run integration tests
+npm run test:integration
+
+# Verify in browser
+# 1. Normal case: 50 users
+# 2. Empty case: 0 users
+# 3. Loading case: spinner shows
+# 4. Error case: error message shows
+```
+
+---
+
+## The Three-Fix Threshold
+
+> **After 3 failed fix attempts → STOP.**
+
+Three failures in different locations signals architectural problems, not isolated bugs.
+
+### What Three Failures Means
+
+```
+Fix Attempt 1: Added null check → New error in child component
+Fix Attempt 2: Fixed child component → New error in parent
+Fix Attempt 3: Fixed parent → Original error returns
+                              ↓
+                    STOP. QUESTION ARCHITECTURE.
+```
+
+### At the Threshold, Do This
+
+1. **Stop fixing symptoms**
+2. **Document the pattern** of failures
+3. **Identify architectural assumptions** being violated
+4. **Propose structural change** rather than patch
+5. **Discuss with team** before proceeding
+
+---
+
+## Red Flags Requiring Process Reset
+
+When you notice these, stop and restart from Phase 1:
+
+| Red Flag | Why It's Wrong |
+|----------|----------------|
+| Proposing solutions before tracing data flow | Guessing, not debugging |
+| Making multiple simultaneous changes | Can't identify which change worked |
+| Skipping test creation | Bug will recur |
+| "Let's try this and see if it works" | Shotgun debugging |
+| Fixing without understanding the cause | Band-aid, not cure |
+
+---
+
+## Decision Flowchart
+
+```
+                    ┌──────────────────┐
+                    │   Bug Reported   │
+                    └────────┬─────────┘
+                             │
+              ┌──────────────▼──────────────┐
+              │   Can you reproduce it?      │
+              └──────────────┬──────────────┘
+                    No       │       Yes
+            ┌────────────────┴────────────────┐
+            ▼                                  ▼
+    ┌───────────────┐               ┌─────────────────┐
+    │ Get more info │               │ Trace data flow │
+    └───────────────┘               └────────┬────────┘
+                                             │
+                              ┌──────────────▼──────────────┐
+                              │ Do you understand the cause? │
+                              └──────────────┬──────────────┘
+                                    No       │       Yes
+                    ┌────────────────────────┴─────────┐
+                    ▼                                   ▼
+            ┌───────────────┐               ┌─────────────────┐
+            │ Study working │               │ Write hypothesis│
+            │   examples    │               └────────┬────────┘
+            └───────────────┘                        │
+                                             ┌───────▼───────┐
+                                             │  Write test   │
+                                             └───────┬───────┘
+                                                     │
+                                             ┌───────▼───────┐
+                                             │  Implement    │
+                                             └───────┬───────┘
+                                                     │
+                                  ┌──────────────────▼──────────────────┐
+                                  │          Does test pass?            │
+                                  └──────────────────┬──────────────────┘
+                                            No       │       Yes
+                            ┌────────────────────────┴──────────┐
+                            ▼                                    ▼
+                    ┌───────────────┐                  ┌─────────────────┐
+                    │ Attempt < 3?  │                  │      Done       │
+                    └───────┬───────┘                  └─────────────────┘
+                    No      │      Yes
+            ┌───────────────┴─────────────────┐
+            ▼                                  ▼
+    ┌───────────────────┐          ┌─────────────────────┐
+    │ Question          │          │ Return to Phase 1   │
+    │ architecture      │          └─────────────────────┘
+    └───────────────────┘
+```
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/skills/backend/feature-forge/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: feature-forge
+description: Conducts structured requirements workshops to produce feature specifications, user stories, EARS-format functional requirements, acceptance criteria, and implementation checklists. Use when defining new features, gathering requirements, or writing specifications. Invoke for feature definition, requirements gathering, user stories, EARS format specs, PRDs, acceptance criteria, or requirement matrices.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: workflow
+  triggers: requirements, specification, feature definition, user stories, EARS, planning
+  role: specialist
+  scope: design
+  output-format: document
+  related-skills: fullstack-guardian, spec-miner, test-master
+---
+
+# Feature Forge
+
+Requirements specialist conducting structured workshops to define comprehensive feature specifications.
+
+## Role Definition
+
+Operate with two perspectives:
+- **PM Hat**: Focused on user value, business goals, success metrics
+- **Dev Hat**: Focused on technical feasibility, security, performance, edge cases
+
+## When to Use This Skill
+
+- Defining new features from scratch
+- Gathering comprehensive requirements
+- Writing specifications in EARS format
+- Creating acceptance criteria
+- Planning implementation TODO lists
+
+## Core Workflow
+
+1. **Discover** - Use `AskUserQuestions` to understand the feature goal, target users, and user value. Present structured choices where possible (e.g., user types, priority level).
+2. **Interview** - Systematic questioning from both PM and Dev perspectives using `AskUserQuestions` for structured choices and open-ended follow-ups. Use multi-agent discovery with Task subagents when the feature spans multiple domains (see interview-questions.md for guidance).
+3. **Document** - Write EARS-format requirements
+4. **Validate** - Use `AskUserQuestions` to review acceptance criteria with stakeholder, presenting key trade-offs as structured choices
+5. **Plan** - Create implementation checklist
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| EARS Syntax | `references/ears-syntax.md` | Writing functional requirements |
+| Interview Questions | `references/interview-questions.md` | Gathering requirements |
+| Specification Template | `references/specification-template.md` | Writing final spec document |
+| Acceptance Criteria | `references/acceptance-criteria.md` | Given/When/Then format |
+| Pre-Discovery Subagents | `references/pre-discovery-subagents.md` | Multi-domain features needing front-loaded context |
+
+## Constraints
+
+### MUST DO
+- Use `AskUserQuestions` tool for structured elicitation (priority, scope, format choices)
+- Use open-ended questions only when choices cannot be predetermined
+- Conduct thorough interview before writing spec
+- Use EARS format for all functional requirements
+- Include non-functional requirements (performance, security)
+- Provide testable acceptance criteria
+- Include implementation TODO checklist
+- Ask for clarification on ambiguous requirements
+
+### MUST NOT DO
+- Output interview questions as plain text when `AskUserQuestions` can provide structured options
+- Generate spec without conducting interview
+- Accept vague requirements ("make it fast")
+- Skip security considerations
+- Forget error handling requirements
+- Write untestable acceptance criteria
+
+## Output Templates
+
+The final specification must include:
+1. Overview and user value
+2. Functional requirements (EARS format)
+3. Non-functional requirements
+4. Acceptance criteria (Given/When/Then)
+5. Error handling table
+6. Implementation TODO checklist
+
+**Inline EARS format examples** (load `references/ears-syntax.md` for full syntax):
+```
+When <trigger>, the <system> shall <response>.
+Where <feature> is active, the <system> shall <behaviour>.
+The <system> shall <action> within <measure>.
+```
+
+**Inline acceptance criteria example** (load `references/acceptance-criteria.md` for full format):
+```
+Given a registered user is on the login page,
+When they submit valid credentials,
+Then they are redirected to the dashboard within 2 seconds.
+```
+
+Save as: `specs/{feature_name}.spec.md`

package/skills/backend/feature-forge/references/acceptance-criteria.md

@@ -0,0 +1,104 @@
+# Acceptance Criteria
+
+## Given-When-Then Format
+
+```markdown
+### AC-001: [Scenario Name]
+Given [context/precondition]
+When [action taken]
+Then [expected result]
+```
+
+## Examples by Type
+
+### Happy Path
+
+```markdown
+### AC-001: Successful Login
+Given a registered user with valid credentials
+When they submit the login form
+Then they are redirected to the dashboard
+And a success message is displayed
+And their session is created
+
+### AC-002: Add Item to Cart
+Given a logged-in user viewing a product
+When they click "Add to Cart"
+Then the item appears in their cart
+And the cart badge updates with the count
+And a confirmation toast is shown
+```
+
+### Error Cases
+
+```markdown
+### AC-003: Invalid Login
+Given a user with incorrect password
+When they submit the login form
+Then an error message "Invalid credentials" is displayed
+And the password field is cleared
+And they remain on the login page
+
+### AC-004: Duplicate Email Registration
+Given an email already exists in the system
+When a new user tries to register with that email
+Then an error message "Email already registered" is displayed
+And the form is not submitted
+```
+
+### Edge Cases
+
+```markdown
+### AC-005: Empty Cart Checkout
+Given a user with an empty cart
+When they navigate to checkout
+Then they see "Your cart is empty" message
+And a "Continue Shopping" button is displayed
+
+### AC-006: Session Expiry
+Given a user whose session has expired
+When they try to perform any authenticated action
+Then they are redirected to login
+And a message "Session expired, please log in again" is shown
+And their intended action is preserved for after login
+```
+
+### Authorization
+
+```markdown
+### AC-007: Admin-Only Access
+Given a regular user (non-admin)
+When they try to access /admin/users
+Then they receive a 403 Forbidden response
+And are redirected to the home page
+And an "Access denied" message is shown
+
+### AC-008: Own Resource Only
+Given a user viewing another user's profile
+When they try to edit the profile
+Then the edit button is not visible
+And direct URL access returns 403
+```
+
+## INVEST Criteria
+
+Good acceptance criteria follow INVEST:
+
+| Criterion | Description | Check |
+|-----------|-------------|-------|
+| **I**ndependent | Can be tested alone | No dependencies on other ACs |
+| **N**egotiable | Details can be discussed | Not over-specified |
+| **V**aluable | Delivers user value | Ties to requirement |
+| **E**stimable | Effort can be estimated | Clear scope |
+| **S**mall | Testable in one session | Not too broad |
+| **T**estable | Pass/fail is clear | Objective criteria |
+
+## Quick Reference
+
+| Scenario Type | Given | When | Then |
+|---------------|-------|------|------|
+| Happy path | Valid state | Valid action | Success result |
+| Error | Invalid state/input | Action | Error message |
+| Edge case | Boundary condition | Action | Graceful handling |
+| Authorization | User role | Protected action | Appropriate access |
+| Concurrency | Multiple actors | Simultaneous action | Consistent state |

package/skills/backend/feature-forge/references/ears-syntax.md

@@ -0,0 +1,99 @@
+# EARS Syntax
+
+## EARS Format
+
+Easy Approach to Requirements Syntax for clear, unambiguous requirements.
+
+### Basic Pattern
+
+```
+While <precondition>, when <trigger>, the system shall <response>.
+```
+
+### Pattern Types
+
+**Ubiquitous (Always True)**
+```
+The system shall [action].
+```
+Example: The system shall encrypt all passwords using bcrypt.
+
+**Event-Driven**
+```
+When [trigger], the system shall [action].
+```
+Example: When the user clicks "Submit", the system shall save the form data.
+
+**State-Driven**
+```
+While [state], the system shall [action].
+```
+Example: While the user is logged in, the system shall display the dashboard.
+
+**Conditional (Most Common)**
+```
+While [state], when [trigger], the system shall [action].
+```
+Example: While the cart contains items, when the user clicks "Checkout", the system shall navigate to the payment page.
+
+**Optional**
+```
+Where [feature enabled], the system shall [action].
+```
+Example: Where two-factor authentication is enabled, the system shall require a verification code.
+
+## Examples by Domain
+
+### Authentication
+
+```markdown
+**FR-AUTH-001**: Login
+While credentials are valid, when POST /auth/login is called,
+the system shall return JWT access token (15min) and refresh token (7d).
+
+**FR-AUTH-002**: Invalid Login
+When invalid credentials are provided,
+the system shall return 401 and increment failed login counter.
+
+**FR-AUTH-003**: Account Lockout
+While failed login count exceeds 5, when login is attempted,
+the system shall reject the attempt and require password reset.
+```
+
+### E-commerce
+
+```markdown
+**FR-CART-001**: Add to Cart
+While user is logged in, when they click "Add to Cart",
+the system shall add the item and update the cart badge count.
+
+**FR-CART-002**: Apply Coupon
+While the cart contains items, when a valid coupon code is applied,
+the system shall reduce the total by the discount amount.
+
+**FR-ORDER-001**: Checkout
+While payment method is valid, when user confirms order,
+the system shall create order, charge payment, and send confirmation email.
+```
+
+### Data Management
+
+```markdown
+**FR-EXPORT-001**: CSV Export
+While user has data access permission, when they click "Export",
+the system shall generate a CSV file and initiate download.
+
+**FR-DELETE-001**: Soft Delete
+When a resource is deleted,
+the system shall set deleted_at timestamp instead of removing the record.
+```
+
+## Quick Reference
+
+| Type | Structure | Use When |
+|------|-----------|----------|
+| Ubiquitous | shall [action] | Always applies |
+| Event | When [X], shall | On trigger |
+| State | While [X], shall | Continuous state |
+| Conditional | While [X], when [Y], shall | State + trigger |
+| Optional | Where [X], shall | Feature flag |