@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/superpowers-lab.md

@@ -0,0 +1,22 @@
+---
+name: superpowers-lab
+description: "Lab environment for Claude superpowers"
+source: "https://github.com/obra/superpowers-lab"
+risk: safe
+---
+
+# Superpowers Lab
+
+## Overview
+
+Lab environment for Claude superpowers
+
+## When to Use This Skill
+
+Use this skill when you need to work with lab environment for claude superpowers.
+
+## Instructions
+
+This skill provides guidance and patterns for lab environment for claude superpowers.
+
+For more information, see the [source repository](https://github.com/obra/superpowers-lab).

package/merged-commands/swift-expert.md

@@ -0,0 +1,94 @@
+---
+name: swift-expert
+description: Use when building iOS/macOS applications with Swift 5.9+, SwiftUI, or async/await concurrency. Invoke for protocol-oriented programming, SwiftUI state management, actors, server-side Swift.
+triggers:
+  - Swift
+  - SwiftUI
+  - iOS development
+  - macOS development
+  - async/await Swift
+  - Combine
+  - UIKit
+  - Vapor
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# Swift Expert
+
+Senior Swift developer with mastery of Swift 5.9+, Apple's development ecosystem, SwiftUI, async/await concurrency, and protocol-oriented programming.
+
+## Role Definition
+
+You are a senior Swift engineer with 10+ years of Apple platform development. You specialize in Swift 5.9+, SwiftUI, async/await concurrency, protocol-oriented design, and server-side Swift. You build type-safe, performant applications following Apple's API design guidelines.
+
+## When to Use This Skill
+
+- Building iOS/macOS/watchOS/tvOS applications
+- Implementing SwiftUI interfaces and state management
+- Setting up async/await concurrency and actors
+- Creating protocol-oriented architectures
+- Optimizing memory and performance
+- Integrating UIKit with SwiftUI
+
+## Core Workflow
+
+1. **Architecture Analysis** - Identify platform targets, dependencies, design patterns
+2. **Design Protocols** - Create protocol-first APIs with associated types
+3. **Implement** - Write type-safe code with async/await and value semantics
+4. **Optimize** - Profile with Instruments, ensure thread safety
+5. **Test** - Write comprehensive tests with XCTest and async patterns
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| SwiftUI | `references/swiftui-patterns.md` | Building views, state management, modifiers |
+| Concurrency | `references/async-concurrency.md` | async/await, actors, structured concurrency |
+| Protocols | `references/protocol-oriented.md` | Protocol design, generics, type erasure |
+| Memory | `references/memory-performance.md` | ARC, weak/unowned, performance optimization |
+| Testing | `references/testing-patterns.md` | XCTest, async tests, mocking strategies |
+
+## Constraints
+
+### MUST DO
+- Use type hints and inference appropriately
+- Follow Swift API Design Guidelines
+- Use async/await for asynchronous operations
+- Ensure Sendable compliance for concurrency
+- Use value types (struct/enum) by default
+- Document APIs with markup comments
+- Use property wrappers for cross-cutting concerns
+- Profile with Instruments before optimizing
+
+### MUST NOT DO
+- Use force unwrapping (!) without justification
+- Create retain cycles in closures
+- Mix synchronous and asynchronous code improperly
+- Ignore actor isolation warnings
+- Use implicitly unwrapped optionals unnecessarily
+- Skip error handling
+- Use Objective-C patterns when Swift alternatives exist
+- Hardcode platform-specific values
+
+## Output Templates
+
+When implementing Swift features, provide:
+1. Protocol definitions and type aliases
+2. Model types (structs/classes with value semantics)
+3. View implementations (SwiftUI) or view controllers
+4. Tests demonstrating usage
+5. Brief explanation of architectural decisions
+
+## Knowledge Reference
+
+Swift 5.9+, SwiftUI, UIKit, async/await, actors, structured concurrency, Combine, property wrappers, result builders, protocol-oriented programming, generics, type erasure, ARC, Instruments, XCTest, Swift Package Manager, Vapor
+
+## Related Skills
+
+- **Mobile Developer** - Cross-platform mobile development
+- **Frontend Expert** - UI/UX implementation patterns
+- **Backend Developer** - Server-side Swift integration

package/merged-commands/swiftui-expert-skill.md

@@ -0,0 +1,275 @@
+---
+name: swiftui-expert-skill
+description: "Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns."
+source: "https://github.com/AvdLee/SwiftUI-Agent-Skill/tree/main/swiftui-expert-skill"
+risk: safe
+---
+
+# SwiftUI Expert Skill
+
+## Overview
+Use this skill to build, review, or improve SwiftUI features with correct state management, modern API usage, Swift concurrency best practices, optimal view composition, and iOS 26+ Liquid Glass styling. Prioritize native APIs, Apple design guidance, and performance-conscious patterns. This skill focuses on facts and best practices without enforcing specific architectural patterns.
+
+## When to Use This Skill
+
+Use this skill when:
+- Building new SwiftUI features
+- Refactoring existing SwiftUI views
+- Reviewing SwiftUI code quality
+- Adopting modern SwiftUI patterns
+- Working with SwiftUI state management
+- Implementing iOS 26+ Liquid Glass styling
+
+## Workflow Decision Tree
+
+### 1) Review existing SwiftUI code
+- Check property wrapper usage against the selection guide (see `references/state-management.md`)
+- Verify modern API usage (see `references/modern-apis.md`)
+- Verify view composition follows extraction rules (see `references/view-structure.md`)
+- Check performance patterns are applied (see `references/performance-patterns.md`)
+- Verify list patterns use stable identity (see `references/list-patterns.md`)
+- Inspect Liquid Glass usage for correctness and consistency (see `references/liquid-glass.md`)
+- Validate iOS 26+ availability handling with sensible fallbacks
+
+### 2) Improve existing SwiftUI code
+- Audit state management for correct wrapper selection (prefer `@Observable` over `ObservableObject`)
+- Replace deprecated APIs with modern equivalents (see `references/modern-apis.md`)
+- Extract complex views into separate subviews (see `references/view-structure.md`)
+- Refactor hot paths to minimize redundant state updates (see `references/performance-patterns.md`)
+- Ensure ForEach uses stable identity (see `references/list-patterns.md`)
+- Suggest image downsampling when `UIImage(data:)` is used (as optional optimization, see `references/image-optimization.md`)
+- Adopt Liquid Glass only when explicitly requested by the user
+
+### 3) Implement new SwiftUI feature
+- Design data flow first: identify owned vs injected state (see `references/state-management.md`)
+- Use modern APIs (no deprecated modifiers or patterns, see `references/modern-apis.md`)
+- Use `@Observable` for shared state (with `@MainActor` if not using default actor isolation)
+- Structure views for optimal diffing (extract subviews early, keep views small, see `references/view-structure.md`)
+- Separate business logic into testable models (see `references/layout-best-practices.md`)
+- Apply glass effects after layout/appearance modifiers (see `references/liquid-glass.md`)
+- Gate iOS 26+ features with `#available` and provide fallbacks
+
+## Core Guidelines
+
+### State Management
+- **Always prefer `@Observable` over `ObservableObject`** for new code
+- **Mark `@Observable` classes with `@MainActor`** unless using default actor isolation
+- **Always mark `@State` and `@StateObject` as `private`** (makes dependencies clear)
+- **Never declare passed values as `@State` or `@StateObject`** (they only accept initial values)
+- Use `@State` with `@Observable` classes (not `@StateObject`)
+- `@Binding` only when child needs to **modify** parent state
+- `@Bindable` for injected `@Observable` objects needing bindings
+- Use `let` for read-only values; `var` + `.onChange()` for reactive reads
+- Legacy: `@StateObject` for owned `ObservableObject`; `@ObservedObject` for injected
+- Nested `ObservableObject` doesn't work (pass nested objects directly); `@Observable` handles nesting fine
+
+### Modern APIs
+- Use `foregroundStyle()` instead of `foregroundColor()`
+- Use `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- Use `Tab` API instead of `tabItem()`
+- Use `Button` instead of `onTapGesture()` (unless need location/count)
+- Use `NavigationStack` instead of `NavigationView`
+- Use `navigationDestination(for:)` for type-safe navigation
+- Use two-parameter or no-parameter `onChange()` variant
+- Use `ImageRenderer` for rendering SwiftUI views
+- Use `.sheet(item:)` instead of `.sheet(isPresented:)` for model-based content
+- Sheets should own their actions and call `dismiss()` internally
+- Use `ScrollViewReader` for programmatic scrolling with stable IDs
+- Avoid `UIScreen.main.bounds` for sizing
+- Avoid `GeometryReader` when alternatives exist (e.g., `containerRelativeFrame()`)
+
+### Swift Best Practices
+- Use modern Text formatting (`.format` parameters, not `String(format:)`)
+- Use `localizedStandardContains()` for user-input filtering (not `contains()`)
+- Prefer static member lookup (`.blue` vs `Color.blue`)
+- Use `.task` modifier for automatic cancellation of async work
+- Use `.task(id:)` for value-dependent tasks
+
+### View Composition
+- **Prefer modifiers over conditional views** for state changes (maintains view identity)
+- Extract complex views into separate subviews for better readability and performance
+- Keep views small for optimal performance
+- Keep view `body` simple and pure (no side effects or complex logic)
+- Use `@ViewBuilder` functions only for small, simple sections
+- Prefer `@ViewBuilder let content: Content` over closure-based content properties
+- Separate business logic into testable models (not about enforcing architectures)
+- Action handlers should reference methods, not contain inline logic
+- Use relative layout over hard-coded constants
+- Views should work in any context (don't assume screen size or presentation style)
+
+### Performance
+- Pass only needed values to views (avoid large "config" or "context" objects)
+- Eliminate unnecessary dependencies to reduce update fan-out
+- Check for value changes before assigning state in hot paths
+- Avoid redundant state updates in `onReceive`, `onChange`, scroll handlers
+- Minimize work in frequently executed code paths
+- Use `LazyVStack`/`LazyHStack` for large lists
+- Use stable identity for `ForEach` (never `.indices` for dynamic content)
+- Ensure constant number of views per `ForEach` element
+- Avoid inline filtering in `ForEach` (prefilter and cache)
+- Avoid `AnyView` in list rows
+- Consider POD views for fast diffing (or wrap expensive views in POD parents)
+- Suggest image downsampling when `UIImage(data:)` is encountered (as optional optimization)
+- Avoid layout thrash (deep hierarchies, excessive `GeometryReader`)
+- Gate frequent geometry updates by thresholds
+- Use `Self._printChanges()` to debug unexpected view updates
+
+### Liquid Glass (iOS 26+)
+**Only adopt when explicitly requested by the user.**
+- Use native `glassEffect`, `GlassEffectContainer`, and glass button styles
+- Wrap multiple glass elements in `GlassEffectContainer`
+- Apply `.glassEffect()` after layout and visual modifiers
+- Use `.interactive()` only for tappable/focusable elements
+- Use `glassEffectID` with `@Namespace` for morphing transitions
+
+## Quick Reference
+
+### Property Wrapper Selection (Modern)
+| Wrapper | Use When |
+|---------|----------|
+| `@State` | Internal view state (must be `private`), or owned `@Observable` class |
+| `@Binding` | Child modifies parent's state |
+| `@Bindable` | Injected `@Observable` needing bindings |
+| `let` | Read-only value from parent |
+| `var` | Read-only value watched via `.onChange()` |
+
+**Legacy (Pre-iOS 17):**
+| Wrapper | Use When |
+|---------|----------|
+| `@StateObject` | View owns an `ObservableObject` (use `@State` with `@Observable` instead) |
+| `@ObservedObject` | View receives an `ObservableObject` |
+
+### Modern API Replacements
+| Deprecated | Modern Alternative |
+|------------|-------------------|
+| `foregroundColor()` | `foregroundStyle()` |
+| `cornerRadius()` | `clipShape(.rect(cornerRadius:))` |
+| `tabItem()` | `Tab` API |
+| `onTapGesture()` | `Button` (unless need location/count) |
+| `NavigationView` | `NavigationStack` |
+| `onChange(of:) { value in }` | `onChange(of:) { old, new in }` or `onChange(of:) { }` |
+| `fontWeight(.bold)` | `bold()` |
+| `GeometryReader` | `containerRelativeFrame()` or `visualEffect()` |
+| `showsIndicators: false` | `.scrollIndicators(.hidden)` |
+| `String(format: "%.2f", value)` | `Text(value, format: .number.precision(.fractionLength(2)))` |
+| `string.contains(search)` | `string.localizedStandardContains(search)` (for user input) |
+
+### Liquid Glass Patterns
+```swift
+// Basic glass effect with fallback
+if #available(iOS 26, *) {
+    content
+        .padding()
+        .glassEffect(.regular.interactive(), in: .rect(cornerRadius: 16))
+} else {
+    content
+        .padding()
+        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 16))
+}
+
+// Grouped glass elements
+GlassEffectContainer(spacing: 24) {
+    HStack(spacing: 24) {
+        GlassButton1()
+        GlassButton2()
+    }
+}
+
+// Glass buttons
+Button("Confirm") { }
+    .buttonStyle(.glassProminent)
+```
+
+## Review Checklist
+
+### State Management
+- [ ] Using `@Observable` instead of `ObservableObject` for new code
+- [ ] `@Observable` classes marked with `@MainActor` (if needed)
+- [ ] Using `@State` with `@Observable` classes (not `@StateObject`)
+- [ ] `@State` and `@StateObject` properties are `private`
+- [ ] Passed values NOT declared as `@State` or `@StateObject`
+- [ ] `@Binding` only where child modifies parent state
+- [ ] `@Bindable` for injected `@Observable` needing bindings
+- [ ] Nested `ObservableObject` avoided (or passed directly to child views)
+
+### Modern APIs (see `references/modern-apis.md`)
+- [ ] Using `foregroundStyle()` instead of `foregroundColor()`
+- [ ] Using `clipShape(.rect(cornerRadius:))` instead of `cornerRadius()`
+- [ ] Using `Tab` API instead of `tabItem()`
+- [ ] Using `Button` instead of `onTapGesture()` (unless need location/count)
+- [ ] Using `NavigationStack` instead of `NavigationView`
+- [ ] Avoiding `UIScreen.main.bounds`
+- [ ] Using alternatives to `GeometryReader` when possible
+- [ ] Button images include text labels for accessibility
+
+### Sheets & Navigation (see `references/sheet-navigation-patterns.md`)
+- [ ] Using `.sheet(item:)` for model-based sheets
+- [ ] Sheets own their actions and dismiss internally
+- [ ] Using `navigationDestination(for:)` for type-safe navigation
+
+### ScrollView (see `references/scroll-patterns.md`)
+- [ ] Using `ScrollViewReader` with stable IDs for programmatic scrolling
+- [ ] Using `.scrollIndicators(.hidden)` instead of initializer parameter
+
+### Text & Formatting (see `references/text-formatting.md`)
+- [ ] Using modern Text formatting (not `String(format:)`)
+- [ ] Using `localizedStandardContains()` for search filtering
+
+### View Structure (see `references/view-structure.md`)
+- [ ] Using modifiers instead of conditionals for state changes
+- [ ] Complex views extracted to separate subviews
+- [ ] Views kept small for performance
+- [ ] Container views use `@ViewBuilder let content: Content`
+
+### Performance (see `references/performance-patterns.md`)
+- [ ] View `body` kept simple and pure (no side effects)
+- [ ] Passing only needed values (not large config objects)
+- [ ] Eliminating unnecessary dependencies
+- [ ] State updates check for value changes before assigning
+- [ ] Hot paths minimize state updates
+- [ ] No object creation in `body`
+- [ ] Heavy computation moved out of `body`
+
+### List Patterns (see `references/list-patterns.md`)
+- [ ] ForEach uses stable identity (not `.indices`)
+- [ ] Constant number of views per ForEach element
+- [ ] No inline filtering in ForEach
+- [ ] No `AnyView` in list rows
+
+### Layout (see `references/layout-best-practices.md`)
+- [ ] Avoiding layout thrash (deep hierarchies, excessive GeometryReader)
+- [ ] Gating frequent geometry updates by thresholds
+- [ ] Business logic separated into testable models
+- [ ] Action handlers reference methods (not inline logic)
+- [ ] Using relative layout (not hard-coded constants)
+- [ ] Views work in any context (context-agnostic)
+
+### Liquid Glass (iOS 26+)
+- [ ] `#available(iOS 26, *)` with fallback for Liquid Glass
+- [ ] Multiple glass views wrapped in `GlassEffectContainer`
+- [ ] `.glassEffect()` applied after layout/appearance modifiers
+- [ ] `.interactive()` only on user-interactable elements
+- [ ] Shapes and tints consistent across related elements
+
+## References
+- `references/state-management.md` - Property wrappers and data flow (prefer `@Observable`)
+- `references/view-structure.md` - View composition, extraction, and container patterns
+- `references/performance-patterns.md` - Performance optimization techniques and anti-patterns
+- `references/list-patterns.md` - ForEach identity, stability, and list best practices
+- `references/layout-best-practices.md` - Layout patterns, context-agnostic views, and testability
+- `references/modern-apis.md` - Modern API usage and deprecated replacements
+- `references/sheet-navigation-patterns.md` - Sheet presentation and navigation patterns
+- `references/scroll-patterns.md` - ScrollView patterns and programmatic scrolling
+- `references/text-formatting.md` - Modern text formatting and string operations
+- `references/image-optimization.md` - AsyncImage, image downsampling, and optimization
+- `references/liquid-glass.md` - iOS 26+ Liquid Glass API
+
+## Philosophy
+
+This skill focuses on **facts and best practices**, not architectural opinions:
+- We don't enforce specific architectures (e.g., MVVM, VIPER)
+- We do encourage separating business logic for testability
+- We prioritize modern APIs over deprecated ones
+- We emphasize thread safety with `@MainActor` and `@Observable`
+- We optimize for performance and maintainability
+- We follow Apple's Human Interface Guidelines and API design patterns

package/merged-commands/systematic-debugging.md

@@ -0,0 +1,296 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **superpowers:verification-before-completion** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common