@jakkrichm/create-nexus-devflow 2.16.2 → 2.16.4

package/template/.claude/skills/debug/root-cause-tracing.md

@@ -0,0 +1,36 @@
+# Root-Cause Tracing
+
+Read when an error occurs deep in the call stack or the source of invalid data is unclear.
+Use with Phase 4 of [debug](SKILL.md); hand repair plans to /fix and /implement.
+
+## 5-Step Backward Trace
+
+1. **Observe symptom**: Capture the error, stack, and exact location.
+2. **Immediate cause**: Identify the failing operation and invalid input.
+3. **Caller**: Find who supplied that input.
+4. **Trace upward**: Follow the parameter back one call at a time to its origin.
+5. **Original trigger**: Reproduce the root cause and propose a regression test.
+
+Example: a test reads tempDir before beforeEach runs, passes an empty value,
+and git init uses the wrong cwd. Prove the setup order before proposing a source guard.
+
+## Stack Trace Instrumentation
+
+Use a scratch reproduction or debugger within /debug's boundaries.
+Record only redacted data; never dump the environment or secrets.
+
+```typescript
+console.error('[DEBUG-trace]', {
+  hasDirectory: Boolean(directory?.trim()),
+  stack: new Error().stack,
+});
+```
+
+Use `rg 'DEBUG-trace' diagnostic.log` to locate probes, then remove them when finished.
+Across multiple layers, compare inputs and outputs at each seam using SET/UNSET status only.
+
+If the bug appears only when tests run together, repeatedly bisect the test set
+to find the polluter, checking state before and after each subset.
+
+Finish when the trigger, call chain, and reproduction evidence are established.
+Then use [defense-in-depth.md](defense-in-depth.md) to plan protective checks.

package/template/.claude/skills/implement/SKILL.md

@@ -114,6 +114,18 @@ Work through the spec's build steps in order, one at a time. For each step:
    - **🟢 GREEN**: Implement only the minimal code in the source file necessary to make the test pass. Re-run test and show passing output.
    - **🔵 REFACTOR**: Refactor and format cleanly, verifying that 100% of tests remain green.
    - *Code Reversion Rule*: If production code is written without a prior test for behavior changes, revert it and write the test first.
+
+   **⚖️ The Iron Law**: `NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST` — Apply to behavior changes according to the spec's test decision. If code came first, revert only your own work for that step and restart from the test, preserving the user's existing work.
+
+   **Red-Phase Verification (confirm all three before GREEN):**
+   - The test actually fails, rather than encountering a syntax error
+   - The error message identifies missing behavior, rather than invalid configuration
+   - The failure reflects the behavior under test, rather than a bug in the test itself
+
+   **Green-Phase Discipline**: Write the minimum code needed to pass the test; add only the options/features it requires (YAGNI constraint).
+
+   > 📖 For anti-patterns and Bad vs Good examples, read [`tdd-anti-patterns.md`](tdd-anti-patterns.md).
+
 2. Implement just that step: the smallest change that satisfies its "done when."
 3. Show the **diff**, not whole files.
 4. **Explain it, and prove it.** Give a short summary: what the step delivered,

package/template/.claude/skills/implement/tdd-anti-patterns.md

@@ -0,0 +1,44 @@
+# TDD Anti-Patterns
+
+Read when planning RED/GREEN or reviewing test quality.
+Follow the test decision in the spec and [implement](SKILL.md).
+
+## The Iron Law
+
+`NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST`
+
+For behavior changes, observe the intended test failure before writing production code.
+If code came first, revert only your own work for that step and restart from the test.
+Preserve the user's existing work; verify docs/config without logic as specified in the spec.
+
+## Red-Phase Checklist
+
+- The test actually fails, rather than encountering a syntax/import error.
+- The failure message identifies missing or incorrect behavior.
+- Test setup is valid, and the intended assertion fails.
+
+If the test passes immediately, check whether it exercises the new behavior.
+Fix setup errors and rerun before GREEN.
+
+| Bad | Good |
+| :--- | :--- |
+| Name: `retry works` | `returns success after transient failure` |
+| Assert only mock calls | Assert outcomes and attempt counts when part of the contract |
+| Combine multiple behaviors | Separate success, retry, and exhausted failure |
+| Write tests without running them | RED → GREEN → REFACTOR with evidence at each stage |
+| Add options for future use | Implement only behavior required by the spec/test |
+
+```typescript
+let attempts = 0;
+const result = await retryOperation(async () => {
+  attempts++;
+  if (attempts < 3) throw new Error('transient');
+  return 'ok';
+});
+assert.equal(result, 'ok');
+assert.equal(attempts, 3);
+```
+
+During GREEN, write the minimum code needed to pass; then REFACTOR while tests stay green.
+Mock only necessary boundaries; check the dependency's contract before creating a fake.
+Finish with evidence of RED for the intended reason, GREEN for the behavior, and regression checks.

package/template/devflow/build-plan.md

@@ -268,3 +268,11 @@
   - *Scope*: สร้างและกำหนดค่า Wrapper Shims สำหรับ Unscoped NPM Packages: `nexus-devflow` (เพื่อรองรับ `npx nexus-devflow`) และ `create-nexus-devflow` (เพื่อรองรับ `npm create nexus-devflow`), อัปเดต Pipeline การ Publish ใน `.github/workflows/publish.yml` และ `publish-devflow` ให้ซิงก์เวอร์ชันและเผยแพร่คู่ขนานกับ `@jakkrichm/create-nexus-devflow`, อัปเดตเอกสาร `AGENTS.md`, `CLAUDE.md` และ README ให้แนะนำคำสั่งสั้นเป็นหลัก
 
 
+
+---
+
+## Phase 35: Superpowers Debugging & TDD Heuristics Integration
+
+- [x] **35. Superpowers Debugging Heuristics & TDD Reference Guides (`DISC-20260909-003`, `085-superpowers-debugging-heuristics-integration`)** `[Size: S]`
+  - *Dependencies*: Feature 31 (`081`), Feature 32 (`082`)
+  - *Scope*: เพิ่ม JIT reference guides สำหรับ root-cause tracing, defense-in-depth, condition-based waiting, TDD anti-patterns และ two-stage review พร้อม 3-Strike Rule และ Iron Law; ซิงก์ `.agents/` กับ `.claude/` และตรวจ file contracts

package/template/devflow/docs/USAGE.md

@@ -121,6 +121,55 @@ abstraction. `/debug` diagnoses first and hands confirmed repairs to `/fix` or
 
 ---
 
+### Debugging, TDD & Review Reference Guides
+
+The `debug`, `implement`, and `audit` skills include five English reference guides.
+They are supporting files read when needed, not additional commands. Both
+`.agents/skills/` and `.claude/skills/` contain matching copies; no separate
+Superpowers plugin installation is required.
+
+| Situation | Entry point | Reference guide |
+| :--- | :--- | :--- |
+| Error deep in a call stack or unclear input origin | `/debug` Phase 4 | [Root-cause tracing](../../.agents/skills/debug/root-cause-tracing.md) |
+| Confirmed root cause needs protective checks | `/debug` repair planning → `/fix` → `/implement` | [Defense-in-depth](../../.agents/skills/debug/defense-in-depth.md) |
+| Flaky async tests or guessed sleep delays | `/debug` Phase 4 | [Condition-based waiting](../../.agents/skills/debug/condition-based-waiting.md) |
+| Planning RED/GREEN or inspecting test quality | `/implement [id]` | [TDD anti-patterns](../../.agents/skills/implement/tdd-anti-patterns.md) |
+| Preparing an independent review | `/audit independent current` | [Two-stage review template](../../.agents/skills/audit/two-stage-review-template.md) |
+
+**Debugging:** Trace the trigger before planning a repair. Use validation layers
+according to actual invariants and risks, and keep diagnostic output redacted.
+The waiting example accepts synchronous predicates only; async I/O needs an
+appropriate async helper with cancellation or timeout. `/debug` remains a
+diagnostic stage. After three unsuccessful repair attempts in the supplied
+history, stop and discuss the architecture before attempting another fix.
+
+**Implementation:** Apply the Iron Law to behavior changes according to the
+spec's test decision: observe the intended failing test before production code.
+Confirm that RED reflects missing behavior rather than broken setup, implement
+the minimum change for GREEN, then refactor with tests passing. Preserve existing
+user work; verify documentation or configuration without logic as the spec directs.
+
+**Review:** Check spec compliance first, then code quality only after Stage 1
+passes. Use the template alongside the canonical
+[independent-review contract](../../.agents/skills/audit/reference/independent-review.md).
+The configured gate still determines whether review runs, and its request,
+immutable checkpoint, reviewer identity, and receipt requirements remain in force.
+Open or fixed P0/P1 findings continue to block completion.
+
+Example prompts (use `$debug` and `$implement` in Codex where appropriate):
+
+```text
+/debug "This async test passes locally but times out in CI; inspect its waiting conditions"
+/implement 085
+/audit independent current
+```
+
+Replace `085` with your active task ID. For the review prompt, ask the reviewer
+to use `audit/two-stage-review-template.md` with the canonical receipt contract;
+the template does not launch a reviewer or authorize a checkpoint commit itself.
+
+---
+
 ## 6. Web Dashboard & CLI Management
 
 ```bash

package/template/devflow/docs/quickstart.md

@@ -50,6 +50,11 @@ All development tasks (from small UI fixes to deep architectural features) execu
 
 ## 4. Pre-Flight Discovery, SA & Architectural Alignment
 
+For debugging, TDD, and independent review, see the
+[English JIT reference guides](USAGE.md#debugging-tdd--review-reference-guides).
+Use them through `debug`, `implement`, and `audit`; they are bundled supporting
+files, not additional commands or a separate plugin installation.
+
 Before committing to delivery, use specialized companion skills to refine complex requirements:
 
 ```text