@frankzhang2026/opencode-android-orchestrator 0.7.0 → 0.8.0

package/docs/MIGRATION.md

@@ -1,7 +1,7 @@
 # Migration guide
 
 This guide covers migration to
-`@frankzhang2026/opencode-android-orchestrator@0.7.0`. Pin the exact version and
+`@frankzhang2026/opencode-android-orchestrator@0.8.0`. Pin the exact version and
 prove the migration in a disposable clone before changing a long-lived
 repository.
 
@@ -9,9 +9,9 @@ repository.
 
 | Current state | Correct command after release | Important distinction |
 | --- | --- | --- |
-| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@0.7.0 init .` | Normal new installation; all detected Android modules and registered debug verification tasks are discovered automatically. |
+| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@0.8.0 init .` | Normal new installation; all detected Android modules and registered debug verification tasks are discovered automatically. |
 | Published `0.1.0` scaffold only | Remove any project-local `@0.1.0` plugin reference after review, then run `init`. | `0.1.0` did not create a usable managed installation and cannot be upgraded. |
-| Healthy `0.2.0` through `0.6.1` manifest-managed installation | Run the fixed `0.7.0` doctor, then `upgrade`. | Existing module scope, verification tasks, and policy values are preserved. Pre-`0.6.1` configurations receive the 30-minute long-command timeout default. |
+| Healthy `0.2.0` through `0.7.0` manifest-managed installation | Run the fixed `0.8.0` doctor, then `upgrade`. | Existing module scope, verification tasks, and policy values are preserved. The old managed Superpowers plugin reference is replaced by bundled skills. Pre-`0.6.1` configurations receive the 30-minute long-command timeout default. |
 | Manually copied V3 files, no `.automation-plugin/manifest.json` | Finish active tasks, preserve historical evidence separately, then run `init`. | Exact files can be reused; differing managed files fail as conflicts. |
 | Healthy older manifest-managed installation | Run `doctor`, then the fixed target version's `upgrade`. | `upgrade` requires a valid installed manifest and intact original backups. |
 | Healthy current-version manifest | Run `doctor`; repeated `init` or same-version `upgrade` is verification-only and byte-idempotent. | Do not reinstall or delete the manifest. |
@@ -36,7 +36,7 @@ removes unchanged plugin-created files, and retains drift for manual review.
 5. If a managed manifest already exists, run:
 
    ```sh
-   npx @frankzhang2026/opencode-android-orchestrator@0.7.0 doctor . --json
+   npx @frankzhang2026/opencode-android-orchestrator@0.8.0 doctor . --json
    ```
 
    Do not proceed with `upgrade` unless the installation checks pass.
@@ -52,14 +52,14 @@ scaffold, not as an older managed installation.
 If the project OpenCode configuration contains an exact
 `@frankzhang2026/opencode-android-orchestrator@0.1.0` entry, save the file and
 remove only that obsolete entry in a reviewed Git change before running
-`0.7.0 init`. The merger deliberately rejects a different version of the same
+`0.8.0 init`. The merger deliberately rejects a different version of the same
 managed package; it will not silently replace the reference. A global npm
 installation of `0.1.0` alone does not require project-file cleanup.
 
 After release, initialize with the fixed version:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.7.0 init .
+npx @frankzhang2026/opencode-android-orchestrator@0.8.0 init .
 ```
 
 New installations default to all-module scope, so multiple application modules
@@ -105,8 +105,8 @@ installer to guess which customization should survive.
 Use the lifecycle command selected by the active manifest:
 
 ```sh
-   npx @frankzhang2026/opencode-android-orchestrator@0.7.0 doctor . --json
-npx @frankzhang2026/opencode-android-orchestrator@0.7.0 upgrade . --json
+   npx @frankzhang2026/opencode-android-orchestrator@0.8.0 doctor . --json
+npx @frankzhang2026/opencode-android-orchestrator@0.8.0 upgrade . --json
 ```
 
 `upgrade` verifies the installed manifest, every managed file, and every
@@ -133,6 +133,15 @@ configurations receive `unitTestsEnabled: true` and `lintEnabled: false`.
 After migration, change only those two values in place and commit the
 configuration; there are no `init` or `upgrade` flags for these policies.
 
+Upgrading a healthy `0.7.0` installation removes the exact managed Superpowers
+v6.2.0 plugin reference that the older Orchestrator added. Upgrade rebuilds the
+OpenCode merge from the verified original pre-install file, so ownership stays
+bounded: if that exact reference was already present before Orchestrator was
+installed, it remains user-owned and is preserved. Other Superpowers versions,
+plugin entries, options, comments, and configuration fields are not silently
+removed. Version `0.8.0` instead registers its five package-local,
+`android-orchestrator-*` workflow skills through the OpenCode `config` hook.
+
 The command refuses:
 
 - a downgrade or malformed semantic version;
@@ -150,8 +159,9 @@ the source of drift and use the recorded recovery data.
 Run all checks from the detected Git root:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.7.0 doctor .
+npx @frankzhang2026/opencode-android-orchestrator@0.8.0 doctor .
 opencode debug config
+opencode debug skill
 opencode debug agent scheduled-planner
 opencode debug agent scheduled-coder
 opencode debug agent scheduled-reviewer
@@ -163,7 +173,8 @@ opencode debug agent scheduled-reviewer
 Verify all of the following before switching normal work to the plugin:
 
 - doctor has no failed check;
-- all three agents, five commands, and required skills are discoverable;
+- all three agents, five commands, three scheduled-quality skills, and five
+  `android-orchestrator-*` workflow skills are discoverable;
 - both read-only custom tools resolve for the scheduled agents;
 - the Shell suite ends with `1..44`;
 - shadow output contains `"mutationPerformed": false`;

package/docs/SECURITY.md

@@ -1,9 +1,9 @@
 # Security model
 
 This document describes the security properties of
-`@frankzhang2026/opencode-android-orchestrator@0.7.0`. The lifecycle foundation
+`@frankzhang2026/opencode-android-orchestrator@0.8.0`. The lifecycle foundation
 completed the real OpenCode `1.14.22` and `1.15.13` release matrix in `0.2.0`;
-`0.7.0` retains that compatibility boundary.
+`0.8.0` retains that compatibility boundary.
 
 ## Security goals and non-goals
 
@@ -53,7 +53,7 @@ modify local files; this package does not claim to protect against that actor.
 
 OpenCode permission prompts are also not semantic workflow approval. They can
 be accepted for the remainder of a session and may be auto-approved. For that
-reason `0.7.0` exposes only `android_orchestrator_status` and
+reason `0.8.0` exposes only `android_orchestrator_status` and
 `android_orchestrator_doctor` as custom tools. State-changing wrappers remain a
 NO-GO until a one-use, non-model-forgeable receipt can bind the approval kind,
 task, session/message, sealed SHA or branch, time, and nonce.
@@ -91,6 +91,13 @@ value is an integer from `120000` through `7200000` milliseconds, defaults to
 `1800000`, never shortens a larger caller timeout, and does not rewrite the
 command or authorize a state change.
 
+The five namespaced bundled workflow skills are loaded from a fixed directory
+inside the installed npm package. The compatible `config` hook only appends
+that directory to `skills.paths`, and plugin startup verifies that every
+expected `SKILL.md` is a regular file. The package omits the upstream
+`using-superpowers` bootstrap, localhost/browser companion, remote branding,
+telemetry, and unrelated skills.
+
 ## Filesystem and configuration safety
 
 The installer never follows a symbolic link at a managed file or required
@@ -196,14 +203,16 @@ surface. Review them before running a workflow in an untrusted project.
 
 ## Dependencies and network behavior
 
-Use fixed package references. The installer adds the exact orchestrator
-version and the configured pinned Superpowers Git tag; it does not use
-`latest`. The package is compiled against `@opencode-ai/plugin@1.14.22` and
+Use fixed package references. The installer adds only the exact Orchestrator
+version; it does not use `latest` or install a GitHub-backed Superpowers
+plugin. The five required Superpowers-derived skills and their supporting
+files are part of the reviewed npm tarball with the upstream MIT license and
+provenance. The package is compiled against `@opencode-ai/plugin@1.14.22` and
 declares the bounded peer range `>=1.14.22 <1.16.0`.
 
 The orchestrator does not contain a telemetry uploader and the deterministic
 Shell flow forbids Git push. Network activity can still occur outside that
-code when npm/npx downloads a package, OpenCode resolves a pinned plugin,
+code when npm/npx downloads a package, OpenCode resolves another configured plugin,
 OpenCode contacts the configured model provider, or project build/test tooling
 uses the network. Apply the host organization's normal npm, Git, OpenCode,
 provider, proxy, certificate, and dependency-review policy.

package/docs/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Use this guide for
-`@frankzhang2026/opencode-android-orchestrator@0.7.0`.
+`@frankzhang2026/opencode-android-orchestrator@0.8.0`.
 
 ## Start with read-only evidence
 
@@ -11,7 +11,7 @@ From the repository root, capture:
 git status --short --branch
 git rev-parse HEAD
 opencode --version
-npx @frankzhang2026/opencode-android-orchestrator@0.7.0 doctor . --json
+npx @frankzhang2026/opencode-android-orchestrator@0.8.0 doctor . --json
 ```
 
 If installation never completed, doctor will correctly report a missing or
@@ -50,6 +50,8 @@ remain human-readable on stderr with a stable code such as `[FILE_CONFLICT]`.
 | Invalid `--long-command-timeout-ms` | The value is not an integer from `120000` through `7200000`. | Use the `1800000` ms default or pass an intentional bounded value to `init`/`upgrade`; do not edit the generated config directly. |
 | Android SDK failure | No valid explicit SDK, `ANDROID_HOME`, `ANDROID_SDK_ROOT`, or `local.properties` `sdk.dir` was found. | Configure one real SDK root containing `platforms/` and `build-tools/`. Do not publish `local.properties`. |
 | Missing `git`, `jq`, `rg`, `shasum`, or Java | Required deterministic command is unavailable on `PATH`. | Install or restore the missing command, record its version, and rerun the read-only checks. |
+| `Bundled Orchestrator skill is unavailable` | The installed `0.8.0` package is incomplete, damaged, or loaded from an unsupported partial copy. | Reinstall the exact package, inspect its `resources/third-party/superpowers-v6.2.0/skills/` entries, restart OpenCode, and rerun `opencode debug skill`. Do not add an external Superpowers plugin as a fallback. |
+| The exact Superpowers v6.2.0 plugin remains after upgrade | That entry existed in the verified pre-install OpenCode file and is therefore user-owned. | Leave it in place or remove it as a separate reviewed configuration change. Upgrade only removes the old Orchestrator-managed entry. |
 
 Version `0.6.0` always passes `--no-configuration-cache` to its temporary
 Gradle task-discovery invocation. This overrides a repository-level
@@ -62,7 +64,7 @@ least `1800000` milliseconds. A higher timeout already supplied by the caller
 is preserved; unrelated Bash commands are unchanged. To configure one hour,
 run `upgrade . --long-command-timeout-ms 3600000` on a healthy installation.
 If a command still reports `120000 ms`, confirm that the project manifest and
-OpenCode plugin reference are both `0.7.0`, restart the OpenCode session so the
+OpenCode plugin reference are both `0.8.0`, restart the OpenCode session so the
 plugin reloads, and rerun doctor before attempting recovery.
 
 After installation, inspect OpenCode discovery separately:
@@ -75,8 +77,9 @@ opencode debug agent scheduled-coder
 opencode debug agent scheduled-reviewer
 ```
 
-Then run `./scripts/automation/preflight.sh --source`. It validates pinned
-plugins, required skills, agent permissions, and both read-only custom tools.
+Then run `./scripts/automation/preflight.sh --source`. It validates resolved
+configuration, required bundled and project skills, agent permissions, and
+both read-only custom tools.
 If it fails, preserve its exact output. Do not broaden an agent's default-deny
 permissions to make discovery pass.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frankzhang2026/opencode-android-orchestrator",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Reusable OpenCode orchestration for Android projects",
   "license": "MIT",
   "author": "frankzhang2026",
@@ -31,6 +31,7 @@
   "files": [
     "dist/",
     "docs/",
+    "resources/",
     "templates/",
     "README.md",
     "CHANGELOG.md",
@@ -45,6 +46,7 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test tests/*.test.mjs",
+    "test:offline-discovery": "npm run build && node --test tests/offline-skill-discovery.integration.mjs",
     "pack:check": "npm pack --dry-run",
     "prepack": "npm run build"
   },

package/resources/third-party/superpowers-v6.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/resources/third-party/superpowers-v6.2.0/PROVENANCE.md

@@ -0,0 +1,21 @@
+# Bundled Superpowers-derived resources
+
+- Upstream: https://github.com/obra/superpowers
+- Upstream version: v6.2.0
+- Upstream copyright: Copyright (c) 2025 Jesse Vincent
+- License: MIT; see `LICENSE` in this directory.
+
+This directory contains a curated, Orchestrator-specific derivative of five
+upstream workflow skills. Names are prefixed with `android-orchestrator-` to
+avoid collisions with independently installed skills.
+
+Intentional changes:
+
+- removed the `using-superpowers` bootstrap dependency;
+- removed brainstorming's visual companion, localhost server, browser launch,
+  remote branding, and telemetry resources;
+- replaced Superpowers plan execution handoffs with the sealed Android
+  Orchestrator contract/Coder/Reviewer workflow;
+- moved optional supporting documents under `references/` and scripts under
+  `scripts/`;
+- rewrote cross-skill references to the bundled namespaced skill IDs.

package/resources/third-party/superpowers-v6.2.0/skills/android-orchestrator-brainstorming/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: android-orchestrator-brainstorming
+description: Refine one Android Orchestrator coding request into a bounded observable behavior proposal before plan and contract creation
+license: MIT
+compatibility: opencode
+metadata:
+  upstream: obra/superpowers@v6.2.0
+  workflow: scheduled-coding
+---
+
+# Android Orchestrator brainstorming
+
+Turn a rough request into one small, testable behavior change. This is an
+interactive planning aid; it never edits product code, creates planning files,
+starts execution, or grants approval.
+
+## Workflow
+
+1. Inspect the relevant repository code, tests, and project instructions.
+2. Summarize current observable behavior and the requested behavior.
+3. Identify ambiguity in scope, acceptance behavior, edge cases, or test
+   strategy. Ask one focused question at a time only when the answer changes
+   the proposal.
+4. Consider two or three approaches when a meaningful tradeoff exists. Lead
+   with the recommended approach and explain the material tradeoff.
+5. Converge on exactly one bounded behavior change with:
+   - observable acceptance criteria;
+   - important edge cases;
+   - exact allowed implementation and test paths;
+   - maximum changed-file count;
+   - focused test filter and device-test policy;
+   - protected paths and explicit non-goals.
+6. Hand the proposal back to `scheduled-quality-orchestrator` for its formal
+   `方案确认` boundary.
+
+## Boundaries
+
+- Never treat discussion or agreement in prose as approval.
+- Never broaden a request merely to make the implementation cleaner.
+- Never propose dependency, build-system, automation-rule, push, merge, or
+  worktree changes unless the user explicitly put them in scope.
+- Use text-only interaction. This bundled skill contains no localhost server,
+  browser launcher, remote image, or telemetry path.

package/resources/third-party/superpowers-v6.2.0/skills/android-orchestrator-systematic-debugging/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: android-orchestrator-systematic-debugging
+description: Diagnose the root cause of an Android Orchestrator task failure before the single permitted repair loop
+license: MIT
+compatibility: opencode
+metadata:
+  upstream: obra/superpowers@v6.2.0
+  workflow: scheduled-coding
+---
+
+# Systematic Debugging
+
+## Overview
+
+**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 `references/root-cause-tracing.md` 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 `android-orchestrator-test-driven-development` for 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?
+   - Use `android-orchestrator-verification-before-completion` before claiming success
+
+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
+- "Ultra-think 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:
+
+- **`references/root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`references/defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`references/condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling