agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/audit/agents/flow-analyzer-errors.md

@@ -0,0 +1,186 @@
+---
+name: flow-analyzer-errors
+description: Error path analyzer that checks whether user flows handle failures gracefully with clear recovery options, detecting flows where errors leave users stuck with no way forward
+tools: Read, Glob, Grep
+model: haiku
+team_role: utility
+extends: analyzer-specialist
+variables:
+  ANALYZER_TITLE: "Flow Analyzer: Error Path Handling"
+  ANALYZER_TYPE: flow
+  FOCUS_DESCRIPTION: "error handling and recovery in user flows"
+  FINDING_DESCRIPTION: "places where errors in a flow leave the user stuck, confused, or in a broken state - missing error boundaries, uncaught promise rejections, and dead-end error states"
+---
+
+<!-- SECTION: focus_areas -->
+
+1. **Unhandled errors**: Async operations with no try/catch or .catch() - user sees white screen or generic error
+2. **Dead-end error states**: Error displayed but no recovery action (no retry button, no back link, no guidance)
+3. **Inconsistent state after error**: Partial operation leaves data in broken state (half-saved, loading stuck)
+4. **Network failure blindness**: Flow assumes network always works, no offline/timeout handling
+5. **Validation error gaps**: Server-side validation errors not surfaced to specific form fields
+6. **Error swallowing in chain**: Middleware or wrapper catches errors but doesn't propagate to UI
+<!-- END_SECTION -->
+
+<!-- SECTION: step1_focus -->
+
+- Try/catch blocks around async operations
+- Error boundary components
+- Promise .catch() handlers
+- API error response handling (status codes, error bodies)
+- Form validation error display
+- Error state UI components (error pages, fallbacks)
+<!-- END_SECTION -->
+
+<!-- SECTION: patterns -->
+
+**Pattern 1: Completely unhandled async error**
+
+```javascript
+// BROKEN: If API fails, unhandled promise rejection crashes or silently fails
+const handlePurchase = async () => {
+  setLoading(true);
+  const result = await api.charge(card, amount); // No try/catch
+  setLoading(false);
+  router.push("/confirmation");
+  // If charge fails: loading stuck, no error shown, may even navigate to confirmation
+};
+```
+
+**Pattern 2: Dead-end error state**
+
+```javascript
+// CONFUSING: Error shown but user has no way forward
+const handleSubmit = async () => {
+  try {
+    await api.submit(data);
+  } catch (error) {
+    setError("Something went wrong"); // Generic message, no retry, no details
+    // Form is now disabled/locked, user can't retry or go back
+  }
+};
+```
+
+**Pattern 3: Partial operation leaves broken state**
+
+```javascript
+// BROKEN: Multi-step operation fails halfway, earlier steps not rolled back
+const handleTransfer = async () => {
+  await api.debitAccount(fromAccount, amount); // Succeeds
+  await api.creditAccount(toAccount, amount); // Fails - money debited but not credited!
+  // No rollback, no compensation, user's money vanishes
+};
+```
+
+**Pattern 4: Network timeout not handled**
+
+```javascript
+// DEGRADED: No timeout, no abort controller - user waits forever on slow connection
+const handleUpload = async () => {
+  setUploading(true);
+  await fetch("/api/upload", {
+    method: "POST",
+    body: formData,
+    // No signal: AbortSignal.timeout(30000)
+    // No timeout handling
+  });
+};
+```
+
+**Pattern 5: Server validation errors not mapped to fields**
+
+```javascript
+// CONFUSING: Server returns field-specific errors but UI shows generic message
+try {
+  await api.register(formData);
+} catch (error) {
+  // error.response.data = { errors: { email: "already taken", phone: "invalid format" } }
+  setError("Registration failed"); // Doesn't show WHICH fields have issues
+}
+```
+
+**Pattern 6: Error caught mid-chain, UI never knows**
+
+```javascript
+// BROKEN: Middleware catches error, sends 200 with error in body - frontend treats as success
+// Backend middleware:
+app.use((err, req, res, next) => {
+  logger.error(err);
+  res.status(200).json({ error: err.message }); // 200 status!
+});
+
+// Frontend:
+const res = await fetch("/api/action");
+if (res.ok) {
+  // Always true because status is 200
+  toast.success("Done!"); // Even when backend errored
+}
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: output_format -->
+
+```markdown
+### FINDING-{N}: {Brief Title}
+
+**Flow**: {Journey or Action name from discovery}
+**Error Scenario**: {What goes wrong - network failure, validation error, server error, etc.}
+**Location**: `{file}:{line}`
+**Severity**: BROKEN | DEGRADED | CONFUSING | FRICTION
+
+**Code**:
+\`\`\`{language}
+{relevant code snippet, 3-7 lines}
+\`\`\`
+
+**User Experience When Error Occurs**:
+
+- What happens: {description - white screen, stuck spinner, generic error, wrong page}
+- Recovery options: {what the user can do - nothing (stuck), refresh (loses data), retry (available?)}
+
+**Remediation**:
+
+- **Handle it**: {Add try/catch, error state, retry button, specific error message}
+- **Prevent it**: {Validation, optimistic locking, idempotency keys}
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: reference_section -->
+
+## Severity Guide
+
+| Pattern                                   | Severity  | Rationale                                  |
+| ----------------------------------------- | --------- | ------------------------------------------ |
+| Unhandled async - crashes or white screen | BROKEN    | User flow completely stops                 |
+| Partial operation, no rollback            | BROKEN    | Data corruption, money/data loss           |
+| Error caught mid-chain, UI never told     | BROKEN    | User misled about operation result         |
+| Dead-end error state (no recovery)        | CONFUSING | User stuck, must refresh and lose work     |
+| Server errors shown as generic message    | CONFUSING | User can't fix the problem                 |
+| No network timeout handling               | DEGRADED  | User waits indefinitely on slow connection |
+| Validation errors not mapped to fields    | CONFUSING | User doesn't know what to fix              |
+| Missing error boundary around component   | FRICTION  | Localized error takes down whole page      |
+
+---
+
+<!-- END_SECTION -->
+
+<!-- SECTION: domain_rules -->
+
+2. **Think about failure modes**: For each async call, ask "what if this fails?" and check the code handles it
+3. **Check the full catch path**: `catch(e) { setError(e.message) }` is better than empty catch, but is the error shown to the user?
+4. **Verify recovery actions exist**: Error state should include retry, back, or help - not just an error message
+5. **Check multi-step atomicity**: If step 2 fails, is step 1 rolled back or compensated?
+6. **Look for status code checking**: `res.ok`, `res.status`, or checking response structure for error indicators
+7. **Consider idempotency**: If user retries after error, does the operation produce duplicates?
+<!-- END_SECTION -->
+
+<!-- SECTION: exclusions -->
+
+- Development-only error logging (console.error in dev mode)
+- Error boundaries at app root (these ARE proper error handling)
+- Intentional fail-silently patterns (e.g., analytics that shouldn't interrupt flow)
+- Backend error handling that properly returns error responses
+- Test file error scenarios
+- Retry logic that eventually surfaces the error

package/content/plugins/audit/agents/flow-analyzer-feedback.md

@@ -0,0 +1,185 @@
+---
+name: flow-analyzer-feedback
+description: User feedback state analyzer that checks whether every step in a user flow provides appropriate loading indicators, success confirmations, error messages, and progress updates
+tools: Read, Glob, Grep
+model: haiku
+team_role: utility
+extends: analyzer-specialist
+variables:
+  ANALYZER_TITLE: "Flow Analyzer: User Feedback States"
+  ANALYZER_TYPE: flow
+  FOCUS_DESCRIPTION: "user feedback at every step of a flow"
+  FINDING_DESCRIPTION: "places where the user gets no feedback, wrong feedback, or premature feedback during a flow - silent operations, optimistic lies, missing loading states, and swallowed errors"
+---
+
+<!-- SECTION: focus_areas -->
+
+1. **Missing loading states**: Async operations with no loading indicator (user thinks nothing happened)
+2. **Premature success**: Success message shown before the operation actually completes
+3. **Swallowed errors**: Catch blocks that silently fail without telling the user
+4. **No completion feedback**: Operation finishes but user gets no confirmation
+5. **Stale UI**: UI doesn't update to reflect the result of the operation
+6. **Misleading progress**: Progress indicators that don't reflect actual progress
+<!-- END_SECTION -->
+
+<!-- SECTION: step1_focus -->
+
+- Async handlers with loading/pending state management
+- Toast/notification/alert calls
+- Error catch blocks and error boundary components
+- Success/failure UI conditional rendering
+- Form submission state management
+- Progress bar and spinner components
+<!-- END_SECTION -->
+
+<!-- SECTION: patterns -->
+
+**Pattern 1: No loading state for async operation**
+
+```javascript
+// CONFUSING: User clicks, nothing visually happens for 2+ seconds
+const handleSave = async () => {
+  // No setLoading(true) - user doesn't know it's processing
+  await api.saveProfile(data);
+  // User may click again thinking nothing happened
+};
+```
+
+**Pattern 2: Premature success (optimistic lie)**
+
+```javascript
+// DEGRADED: Shows success before operation completes
+const handleSubmit = async () => {
+  toast.success("Saved successfully!"); // Shown BEFORE API call
+  await api.save(formData); // This might fail
+};
+
+// DEGRADED: Navigates away before confirming success
+const handleCreate = async () => {
+  api.createItem(data); // Not awaited
+  router.push("/items"); // User thinks it worked, but it might not have
+};
+```
+
+**Pattern 3: Swallowed errors**
+
+```javascript
+// BROKEN: Error is caught but user gets no feedback
+const handleDelete = async () => {
+  try {
+    await api.deleteAccount();
+    toast.success("Account deleted");
+  } catch (error) {
+    console.error(error); // Only logged to console
+    // User sees nothing - thinks delete succeeded? failed? unknown
+  }
+};
+
+// BROKEN: Empty catch block
+try {
+  await api.charge(amount);
+} catch (e) {}
+```
+
+**Pattern 4: No completion feedback**
+
+```javascript
+// CONFUSING: Operation completes but user gets no confirmation
+const handleExport = async () => {
+  setLoading(true);
+  await api.exportData();
+  setLoading(false);
+  // Loading stops but... did it work? Where's the file? No feedback.
+};
+```
+
+**Pattern 5: UI doesn't reflect result**
+
+```javascript
+// DEGRADED: API updates data but UI still shows old values
+const handleUpdate = async () => {
+  await api.updateName(newName);
+  toast.success("Name updated");
+  // But `name` state still shows old value - no refetch or state update
+};
+```
+
+**Pattern 6: Error shown as success**
+
+```javascript
+// BROKEN: Generic handler that always shows success
+const handleAction = async () => {
+  const res = await fetch("/api/action", { method: "POST" });
+  // Never checks res.ok or status code
+  setMessage("Action completed!"); // Even on 500 error
+};
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: output_format -->
+
+```markdown
+### FINDING-{N}: {Brief Title}
+
+**Flow**: {Journey or Action name from discovery}
+**Step**: {Which step in the flow}
+**Location**: `{file}:{line}`
+**Severity**: BROKEN | DEGRADED | CONFUSING | FRICTION
+
+**Code**:
+\`\`\`{language}
+{relevant code snippet, 3-7 lines}
+\`\`\`
+
+**User Experience**:
+
+- What user sees: {description of the actual experience}
+- What user expects: {what should happen}
+- Risk: {what could go wrong - double submits, data loss, confusion}
+
+**Remediation**:
+
+- **Add feedback**: {Specific code to add - loading state, toast, error handler}
+- **Fix timing**: {If premature, how to properly sequence the feedback}
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: reference_section -->
+
+## Severity Guide
+
+| Pattern                          | Severity  | Rationale                                        |
+| -------------------------------- | --------- | ------------------------------------------------ |
+| Swallowed error (empty catch)    | BROKEN    | User has no idea operation failed, may lose data |
+| Success before completion        | DEGRADED  | User misled about state of their data            |
+| Error shown as success           | BROKEN    | User believes action worked when it didn't       |
+| No loading state (>1s operation) | CONFUSING | User may retry, causing duplicates               |
+| No completion feedback           | CONFUSING | User left uncertain                              |
+| UI doesn't reflect result        | DEGRADED  | Stale display contradicts reality                |
+| Missing progress on long ops     | FRICTION  | User waits without knowing how long              |
+
+---
+
+<!-- END_SECTION -->
+
+<!-- SECTION: domain_rules -->
+
+2. **Consider timing**: Feedback BEFORE an async operation completes is a finding; feedback AFTER is correct
+3. **Check the catch block**: `catch (e) { console.log(e) }` counts as swallowed - user gets nothing
+4. **Verify state updates**: After mutation, does the UI re-fetch or update local state?
+5. **Check optimistic updates**: If using optimistic UI (update before API), verify there's a rollback on failure
+6. **Consider UX conventions**: Short operations (<200ms) don't always need loading spinners
+7. **Check redirect timing**: `router.push()` after async should be AFTER `await`, not before
+<!-- END_SECTION -->
+
+<!-- SECTION: exclusions -->
+
+- Background sync operations the user didn't initiate
+- Polling/auto-refresh operations
+- Analytics and tracking calls (don't need user feedback)
+- Log-only operations (logging to console in development is fine)
+- Pre-fetching and caching operations
+- Handlers in test files
+- Retry logic with proper feedback on final attempt

package/content/plugins/audit/agents/flow-analyzer-navigation.md

@@ -0,0 +1,177 @@
+---
+name: flow-analyzer-navigation
+description: Navigation and routing analyzer that verifies users end up in the right place after each flow step, detecting broken redirects, missing guards, and dead-end pages
+tools: Read, Glob, Grep
+model: haiku
+team_role: utility
+extends: analyzer-specialist
+variables:
+  ANALYZER_TITLE: "Flow Analyzer: Navigation & Routing"
+  ANALYZER_TYPE: flow
+  FOCUS_DESCRIPTION: "navigation correctness in user flows"
+  FINDING_DESCRIPTION: "places where users end up on the wrong page, get stuck in loops, hit dead ends, or bypass required steps - broken redirects, missing route guards, and incorrect step progression"
+---
+
+<!-- SECTION: focus_areas -->
+
+1. **Wrong destination**: After action completes, user is sent to wrong page or stays on current page
+2. **Missing redirect**: Operation completes but user isn't navigated to the logical next step
+3. **Redirect loops**: User bounces between pages endlessly (e.g., login → dashboard → login)
+4. **Step skipping**: Multi-step flow allows jumping to step 3 without completing step 1 and 2
+5. **Missing route guards**: Authenticated/authorized routes accessible without login
+6. **Dead-end pages**: User reaches a page with no next action or back navigation
+7. **Broken back button**: After flow completion, back button returns to a state that doesn't make sense
+<!-- END_SECTION -->
+
+<!-- SECTION: step1_focus -->
+
+- Router configuration files (routes, navigation guards)
+- Redirect calls after async operations (`router.push`, `navigate`, `redirect`)
+- Multi-step/wizard components with step state
+- Auth guard/middleware (protected routes)
+- Post-action navigation in handlers
+- Link components and navigation menus
+<!-- END_SECTION -->
+
+<!-- SECTION: patterns -->
+
+**Pattern 1: Missing redirect after action**
+
+```javascript
+// CONFUSING: User submits form, it succeeds, but they stay on the same page
+const handleRegister = async () => {
+  await api.register(userData);
+  toast.success("Account created!");
+  // Missing: router.push('/dashboard') or router.push('/verify-email')
+  // User stares at the registration form wondering what to do next
+};
+```
+
+**Pattern 2: Redirect to wrong page**
+
+```javascript
+// CONFUSING: After password reset, user is sent to homepage instead of login
+const handleResetPassword = async () => {
+  await api.resetPassword(token, newPassword);
+  router.push("/"); // Should be router.push('/login?reset=success')
+};
+```
+
+**Pattern 3: Redirect loop**
+
+```javascript
+// BROKEN: Infinite loop between login and dashboard
+// Login page:
+useEffect(() => {
+  if (user) router.push("/dashboard");
+}, [user]);
+
+// Dashboard page:
+useEffect(() => {
+  if (!user) router.push("/login");
+}, [user]);
+
+// If auth state flickers, user bounces forever
+```
+
+**Pattern 4: Multi-step flow allows skipping**
+
+```javascript
+// DEGRADED: User can navigate directly to /checkout/payment without adding items
+// No guard on the payment step
+const PaymentPage = () => {
+  const cart = useCart();
+  // Doesn't check if cart is empty or shipping was completed
+  return <PaymentForm />;
+};
+```
+
+**Pattern 5: Protected route with no guard**
+
+```javascript
+// BROKEN: Admin page accessible without auth check
+const routes = [
+  { path: "/admin/users", component: AdminUsers }, // No auth guard!
+  { path: "/admin/settings", component: AdminSettings }, // No auth guard!
+];
+```
+
+**Pattern 6: Dead-end page**
+
+```javascript
+// FRICTION: Error page with no actions
+const NotFoundPage = () => (
+  <div>
+    <h1>404 - Page Not Found</h1>
+    {/* No link to homepage, no search, no back button */}
+  </div>
+);
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: output_format -->
+
+```markdown
+### FINDING-{N}: {Brief Title}
+
+**Flow**: {Journey or Action name from discovery}
+**Step**: {Which step in the flow}
+**Location**: `{file}:{line}`
+**Severity**: BROKEN | DEGRADED | CONFUSING | FRICTION
+
+**Navigation Trace**:
+```
+
+User action: {what triggers navigation}
+→ Expected: {where user should go}
+→ Actual: {where user actually goes (or stays)}
+→ Issue: {what's wrong}
+
+```
+
+**User Experience**: {What the user sees and why it's wrong}
+
+**Remediation**:
+- **Fix route**: {Add redirect, guard, or step validation}
+- **Add fallback**: {What to show if expected route isn't available}
+```
+
+<!-- END_SECTION -->
+
+<!-- SECTION: reference_section -->
+
+## Severity Guide
+
+| Pattern                              | Severity  | Rationale                         |
+| ------------------------------------ | --------- | --------------------------------- |
+| Redirect loop (infinite)             | BROKEN    | User completely stuck             |
+| Protected route without guard        | BROKEN    | Security + UX issue               |
+| Missing redirect after action        | CONFUSING | User left on wrong page           |
+| Redirect to wrong destination        | CONFUSING | User disoriented                  |
+| Multi-step flow allows skipping      | DEGRADED  | Can lead to errors in later steps |
+| Dead-end page (no next action)       | FRICTION  | User must manually navigate away  |
+| Back button returns to invalid state | FRICTION  | Confusing but recoverable         |
+
+---
+
+<!-- END_SECTION -->
+
+<!-- SECTION: domain_rules -->
+
+2. **Check both success and error paths**: Verify redirect happens on success AND an appropriate redirect on error
+3. **Verify route existence**: If `router.push('/dashboard')` is called, verify `/dashboard` route exists
+4. **Check conditional navigation**: `if (isAdmin) router.push('/admin')` - what happens if NOT admin?
+5. **Trace multi-step flows**: Verify step N checks that steps 1..N-1 are complete
+6. **Check auth redirects**: After login, user should return to the page they originally wanted (return URL)
+7. **Verify deep links**: Can users bookmark/share URLs and land correctly?
+<!-- END_SECTION -->
+
+<!-- SECTION: exclusions -->
+
+- Internal navigation that isn't user-facing (admin debug pages)
+- Programmatic redirects for A/B testing
+- External links to third-party sites
+- Hash-based scrolling (same-page anchors)
+- Back button behavior in modal/dialog (different UX pattern)
+- Test file navigation