pentaxis93 · pentaxis93 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -48,7 +48,7 @@ Groundwork ships skills from two maintenance locations, but inventory is unified
 
 Skills maintained in this repository are listed in `skills/skills.toml` with local paths under `skills/`. These skills define the pipeline's structure — what stages exist, what handoff contracts connect them, and what cognitive discipline the pipeline enforces.
 
-Skills maintained upstream (from [obra/superpowers](https://github.com/obra/superpowers)) are listed in the same manifest with pinned commits and fetched at install time. They fill the execution phase — debugging and subagent orchestration — where high-quality implementations already exist.
+Skills maintained upstream (from [obra/superpowers](https://github.com/obra/superpowers)) are listed in the same manifest with pinned commits and fetched at install time. They fill the execution phase — subagent orchestration — where high-quality implementations already exist.
 
 Curated skills are pinned to a specific commit. They are not forked, vendored, or modified. Integration happens through documentation: WORKFLOW.md defines handoff rules that connect curated skills to the pipeline's input/output contracts.
 

diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ For the concise inventory and shipped order reference, see [`skills/skills.toml`
 | `plan` | Decomposition | Unclear scope, design choices left to implementer |
 | `test-first` | Execution | Implementation-first regressions |
 | `subagent-driven-development` | Execution | Context drift in parallel work |
-| `systematic-debugging` | Execution | Thrashing and symptom-fixing |
+| `systematic-debugging` | Cross-cutting | Thrashing and symptom-fixing |
 | `verification-before-completion` | Verification | False completion claims without evidence |
 | `documentation` | Verification | Drifted docs, missing artifact updates |
 | `propose` | Delivery | Manual ad-hoc commit/push/PR between implementation and merge |

diff --git a/WORKFLOW.md b/WORKFLOW.md
@@ -36,7 +36,7 @@ Use `test-first` to implement each plan step through RED-GREEN-REFACTOR. Each RE
 
 Use `subagent-driven-development` when the plan contains independent tasks that can run in parallel. It dispatches a fresh subagent per task with two-stage review (spec compliance, then code quality).
 
-Use `systematic-debugging` when a test fails or behavior is unexpected. It finds root cause before proposing fixes — no symptom-patching.
+Use `systematic-debugging` when a test fails or behavior is unexpected. It finds root cause before proposing fixes — no symptom-patching. Although listed here because most debugging occurs during execution, it is a cross-cutting discipline that fires at any pipeline stage when failures appear.
 
 Code review is handled by CI/CD infrastructure, not a methodology skill. The pipeline requires review before landing but does not prescribe the mechanism.
 
@@ -89,6 +89,18 @@ Documentation is a cross-cutting communication discipline, not a pipeline phase.
 
 For fail conditions and anti-divergence rules, see [docs/architecture/pipeline-contract.md](docs/architecture/pipeline-contract.md).
 
+## Root-Cause Investigation Thread
+
+Root-cause investigation is a cross-cutting discipline. It fires at any pipeline stage when a test fails, behavior is unexpected, or any failure occurs — before proposing fixes. See `systematic-debugging` for the full methodology.
+
+### Handoff Rules
+
+1. `systematic-debugging -> test-first`: once root cause is established, hand off to `test-first` fix-bug to write a failing test and implement the fix.
+2. `systematic-debugging -> ground`: when the 3-fix escalation rule fires, invoke `ground` to re-examine architectural assumptions.
+3. `systematic-debugging -> third-force`: when investigation reveals the root cause is operational friction (missing tool, broken config, stale convention), hand off to `third-force`.
+
+For fail conditions and anti-divergence rules, see [docs/architecture/pipeline-contract.md](docs/architecture/pipeline-contract.md).
+
 ## Friction Resolution Thread
 
 Friction resolution is a cross-cutting discipline. It fires at any pipeline stage when the operational environment impedes progress. See `third-force` for the full methodology.

diff --git a/agents.toml b/agents.toml
@@ -19,5 +19,5 @@ using_groundwork = { gh = "pentaxis93/groundwork", path = "skills/using-groundwo
 third_force = { gh = "pentaxis93/groundwork", path = "skills/third-force" }
 subagent_driven_development = { gh = "obra/superpowers", path = "skills/subagent-driven-development", rev = "e4a2375cb705ca5800f0833528ce36a3faf9017a" }
 test_first = { gh = "pentaxis93/groundwork", path = "skills/test-first" }
-systematic_debugging = { gh = "obra/superpowers", path = "skills/systematic-debugging", rev = "e4a2375cb705ca5800f0833528ce36a3faf9017a" }
+systematic_debugging = { gh = "pentaxis93/groundwork", path = "skills/systematic-debugging" }
 verification_before_completion = { gh = "pentaxis93/groundwork", path = "skills/verification-before-completion" }
diff --git a/docs/architecture/pipeline-contract.md b/docs/architecture/pipeline-contract.md
@@ -87,6 +87,20 @@ Requirement:
 Fail condition:
 - `land` invoked on a branch with no PR, falling back to local merge and losing PR merge metadata.
 
+### `systematic-debugging -> test-first`
+Requirement:
+- root cause is established before a fix is attempted through `test-first` fix-bug. Investigation output identifies the specific cause and the transition point where valid data becomes invalid.
+
+Fail condition:
+- fix-bug entered without root-cause analysis when the cause was unclear — agent proposed a fix from symptoms alone.
+
+### `systematic-debugging -> ground`
+Requirement:
+- the 3-fix escalation rule triggers architectural re-examination via `ground` when 3 fix attempts have failed. The debugging scope ends and the architectural scope begins.
+
+Fail condition:
+- fourth fix attempt without questioning the architecture — agent continued to apply fixes past the point where the methodology indicated an architectural problem.
+
 ### `third-force -> documentation`
 Requirement:
 - structural fixes that change operational instructions are reflected in CLAUDE.md, CONTRIBUTING.md, or WORKFLOW.md.
@@ -111,6 +125,7 @@ Fail condition:
 6. Do not land user-visible changes without a CHANGELOG entry.
 7. Do not treat stale documentation as authoritative over code behavior.
 8. Do not collapse the triad by routing around operational friction — resolve it structurally or file an issue.
+9. Do not propose fixes without root-cause investigation when the cause is unclear.
 
 ## Quick Compliance Checklist
 
@@ -122,3 +137,4 @@ Fail condition:
 - [ ] Documentation review completed before verification.
 - [ ] User-facing changes include CHANGELOG entry.
 - [ ] Documentation coverage status recorded at completion.
+- [ ] Root-cause investigation completed before fix when cause was unclear.
diff --git a/skills/skills.toml b/skills/skills.toml
@@ -68,8 +68,7 @@ use_when = "Use when a verified plan contains independent tasks that can run in
 name = "systematic-debugging"
 path = "skills/systematic-debugging"
 provider = "gh"
-repo = "obra/superpowers"
-rev = "e4a2375cb705ca5800f0833528ce36a3faf9017a"
+repo = "pentaxis93/groundwork"
 use_when = "Use when tests fail or behavior is unexpected and root cause is not yet established."
 
 [[skills]]

diff --git a/skills/systematic-debugging/LICENSE-UPSTREAM b/skills/systematic-debugging/LICENSE-UPSTREAM
@@ -0,0 +1,37 @@
+This skill is adapted from the systematic-debugging skill in
+obra/superpowers (https://github.com/obra/superpowers), pinned at commit
+e4a2375. The original skill and its companion files (root-cause-tracing.md,
+defense-in-depth.md, condition-based-waiting.md) are licensed under the MIT
+License reproduced below.
+
+Substantial portions of the original are preserved in this adaptation: the
+Iron Law, the four-phase investigation model, the 3-fix architectural
+escalation rule, the anti-rationalization table, and the red flags list.
+These have been restructured as a cross-cutting discipline with vocabulary
+normalization, language-agnostic examples, and bidirectional pipeline
+integration with groundwork's test-first, verification, ground, and
+third-force skills.
+
+---
+
+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.