@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/debugging-and-error-recovery/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: debugging-and-error-recovery
+description: Guides root-cause debugging and safe recovery from failures. Use when tests fail, builds break, behavior is unexpected, or multiple fix attempts have not worked.
+---
+
+# Debugging & Error Recovery
+
+## Overview
+
+Random fixes create new bugs. Debugging must move from symptom to root cause to guarded fix.
+
+Systematic debugging uses structured triage. When something breaks, stop adding features, preserve evidence, and follow a repeatable process to find and fix the root cause. Guessing wastes time.
+
+Core principle: reproduce, localize, reduce, fix, and guard before claiming resolution.
+
+## When to Use
+
+- Test, lint, typecheck, build, or runtime failure.
+- User reports a bug or unexpected behavior.
+- A previous fix failed.
+- Error crosses multiple layers or components.
+- Multiple fix attempts have not worked.
+- System behavior differs from the stated contract or recent baseline.
+- A subagent reports that a verification step is blocked.
+
+## When NOT to Use
+
+- Feature work with no failure signal; use `incremental-implementation`.
+- Pure research; use `source-driven-development`.
+- Code review feedback without a failing signal; use `code-review-and-quality`.
+
+## Stop-the-Line Rule
+
+When a failure is observed, stop normal work immediately:
+
+1. **STOP** adding features or making unrelated changes.
+2. **PRESERVE** evidence (error output, logs, repro steps, commit hash, environment).
+3. **DIAGNOSE** using the triage checklist.
+4. **FIX** the root cause, not the symptom.
+5. **GUARD** against recurrence with a regression test or monitor.
+6. **RESUME** only after verification passes.
+
+Do not resume feature work while a verified failure is unaddressed. The longer a bug sits, the more assumptions build on top of it.
+
+## The Triage Checklist
+
+### Step 1: Reproduce — Make the failure happen reliably
+
+- Read the full error message and stack trace before acting.
+- Capture relevant logs, request payloads, environment variables, and commit hashes.
+- Run the failing command or scenario until it fails consistently.
+- If the failure is intermittent, record frequency, timing, and environment differences.
+- Document exact reproduction steps so another agent can replay them.
+- If reproduction is impossible, document the evidence and move to the Non-reproducible bugs pattern.
+- If the failure only happens in CI, reproduce in a matching container or environment before assuming it is environmental noise.
+- Check whether the failure depends on a specific seed, order, or race condition.
+
+### Step 2: Localize — Narrow down WHERE the bug lives
+
+- Identify the failing layer: input validation, boundary, business logic, integration, environment.
+- Use `git bisect` when the failure started recently and history is clean.
+- For test failures: confirm whether the code under test changed or the test became stale.
+- For build failures: identify whether it is a type error, import error, config error, dependency error, or environment error.
+- For runtime errors: trace the call path from entry point to the thrown error.
+- For unexpected behavior: compare actual output against expected behavior in the smallest observable scope.
+- Ask: what is the last point where the state was still correct?
+- Use available tools to gather evidence: read source near the error line, inspect callers and callees, search for related symbols, and check recent diffs.
+
+### Step 3: Reduce — Create the minimal failing case
+
+- Remove unrelated code, data, and configuration until the failure still occurs.
+- Replace large inputs with the smallest input that triggers the bug.
+- Run the reduced case in isolation to confirm it reproduces the original failure.
+- A minimal case clarifies the root cause and becomes the basis of a regression test.
+- If reduction is hard, bisect the inputs or the commit history to isolate the trigger.
+- Keep a record of each reduction step so the investigation remains reversible.
+
+### Step 4: Fix the Root Cause — Fix the underlying issue, not the symptom
+
+- Ask "Why does this happen?" repeatedly until you reach the actual cause.
+- Form one hypothesis and test it with one change or one diagnostic.
+- Change one causal layer at a time.
+- Avoid defensive patches that hide symptoms without fixing cause.
+- Prefer the smallest fix that removes the failure and matches the intended design.
+- If the fix requires touching multiple layers, verify each layer independently.
+- Do not combine unrelated changes in the same commit as the bug fix.
+
+### Step 5: Guard Against Recurrence — Write a test that catches this specific failure
+
+- Add a regression test that fails without the fix and passes with it.
+- If the bug cannot be tested directly, add an assertion, monitor, or lint rule that would have caught it.
+- Update documentation or runbooks when the fix involves operational behavior.
+- Make the guard visible: a passing test named after the bug is better than a comment.
+- Ensure the guard runs in CI, not only locally.
+
+### Step 6: Verify End-to-End — Confirm the failure is gone and nothing else broke
+
+- Run the original reproduction scenario and confirm it passes.
+- Run the new regression test.
+- Run the relevant test suite, typecheck, lint, and build.
+- Perform a manual spot check when the failure has UI or workflow behavior.
+- If verification fails, return to Step 2 with fresh evidence.
+- If three fix attempts fail, stop and escalate architecture or assumption risk.
+- Document the verification commands used and their output.
+
+## Error-Specific Patterns
+
+### Test Failure
+
+- Did you change code the test covers? The test may be outdated, or the code may have a bug.
+- Check whether the test makes a brittle assumption about ordering, timing, or internal state.
+- Do not skip or delete the test until you prove it is wrong.
+- If the test is outdated, update it to match the new contract and verify the contract is intentional.
+- If the test is flaky, isolate the source of flakiness rather than increasing retries.
+
+### Build Failure
+
+- **Type error**: check changed signatures, generics, and strict null checks.
+- **Import error**: check moved files, missing exports, circular imports, and dependency versions.
+- **Config error**: check changed config files, environment variables, and CI images.
+- **Dependency error**: check lockfile drift, peer dependency ranges, and installed versions.
+- **Environment error**: check Node/runtime version, OS differences, and CI vs local divergence.
+- Treat build errors as runtime errors that happen earlier: the root cause is usually a recent change, not the build tool.
+
+### Runtime Error
+
+- **TypeError / null / undefined**: trace the value back to its source; add null checks only after understanding why it is missing.
+- **Network / CORS**: verify endpoint, headers, credentials, and allowed origins.
+- **Render error**: check component props, state lifecycle, and framework-specific boundaries.
+- **Unexpected behavior**: compare actual vs expected outputs and reduce to a minimal assertion.
+- **Performance regression**: measure before and after; do not optimize from intuition.
+- **Memory leak**: look for unbounded caches, unremoved listeners, and retained closures.
+
+### Non-reproducible bugs
+
+- **Timing-dependent**: add logging, reduce concurrency, or introduce deterministic sequencing.
+- **Environment-dependent**: compare CI, local, staging, and production configs and dependencies.
+- **State-dependent**: capture full application state at failure time and replay against it.
+- When a bug cannot be reproduced, document everything and add a monitor so the next occurrence is captured.
+- Increase observability before the next attempt; guessing without data usually fails.
+- Set a timebox for chasing a non-reproducible bug before switching to defensive guards.
+
+## Safe Fallback Patterns
+
+When a fix cannot be applied immediately or the root cause is still uncertain:
+
+- Use safe defaults with warnings rather than broken features.
+- Apply graceful degradation that preserves core functionality.
+- Make the fallback observable so users and operators know something is wrong.
+- Do not treat a fallback as a permanent substitute for a root-cause fix.
+- Prefer returning an explicit error over silently returning corrupted or partial data.
+- Log the fallback path and the conditions that triggered it.
+
+## Evidence Log
+
+For complex bugs, maintain a short log in the response or a debug artifact:
+
+```markdown
+## Symptoms
+- ...
+## Reproduction
+- ...
+## Hypotheses Eliminated
+- ...
+## Root Cause
+- ...
+## Fix and Guard
+- ...
+```
+
+Use the log to keep the investigation honest. Each entry should contain a fact, not a guess. Share the log when escalating so the next agent can continue without starting over.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "This is probably the issue" | Probably is a hypothesis, not evidence. Test it minimally. |
+| "I'll patch the symptom now" | Symptom patches hide root causes and regress later. |
+| "Multiple fixes will save time" | You will not know which change mattered. |
+| "The test failure is unrelated" | Prove it with isolation before ignoring it. |
+| "One more attempt" | After three failed fixes, the model is wrong. Stop and rethink. |
+| "I know what the bug is, I'll just fix it" | You might be right 70% of the time. The other 30% costs hours. Reproduce first. |
+| "The failing test is probably wrong" | Verify that assumption. Don't just skip it. |
+| "It works on my machine" | Environments differ. Check CI, config, dependencies. |
+| "I'll fix it in the next commit" | Fix it now. Next commit introduces new bugs on top. |
+| "This is a flaky test, ignore it" | Flaky tests mask real bugs. Fix the flakiness. |
+
+## Red Flags
+
+- Code changes before reproduction.
+- Fix proposed before reading the full error.
+- Same failure persists after two attempts.
+- New failures appear in different layers.
+- Regression test is skipped for a reproducible bug.
+- Success claimed without re-running the original failing scenario.
+- Skipping a failing test to work on new features.
+- Guessing at fixes without reproducing the bug.
+- Fixing symptoms instead of root causes.
+- No regression test added after a bug fix.
+- Continuing feature work while a failure is unverified.
+- Treating environment differences as unimportant.
+
+## Verification Checklist
+
+- [ ] Original failure is reproduced or documented as non-reproducible.
+- [ ] Root cause is identified and documented with evidence.
+- [ ] Fix addresses the root cause, not just symptoms.
+- [ ] A regression test exists that fails without the fix.
+- [ ] All existing tests pass.
+- [ ] Build / lint / typecheck succeeds.
+- [ ] The original bug scenario is verified end-to-end.
+- [ ] Related tests and checks pass.
+- [ ] No new failures appear in adjacent layers.
+- [ ] Evidence log or debug notes are updated.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>debugging-and-error-recovery</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Reproduction, root cause, fix, and verification commands</evidence>
+  <artifacts>Changed files, tests, debug notes</artifacts>
+  <risks>Non-reproducible behavior, missing regression test, or none</risks>
+</skill_result>
+```
+
+## Consolidated Debugging Workflow
+
+This is the canonical active debugging skill. It absorbs `systematic-debugging` while preserving root-cause discipline. Use `root-cause-tracing` as an advanced companion when the failure is deep in execution.
+
+Required posture:
+
+- reproduce or observe the failure before fixing;
+- state the hypothesis and evidence;
+- change one causal layer at a time;
+- verify the failure mode is gone;
+- record recovery actions and residual risk.
+
+## How to Use Tools During Debugging
+
+Use tool calls deliberately, not randomly:
+
+- Read the error location and a few lines of surrounding code before hypothesizing.
+- Search for the error message or symbol across the codebase to find related call sites.
+- Inspect callers and callees of the failing function to understand data flow.
+- Check recent commits and diffs when the failure is new.
+- Run the exact failing command and capture full output.
+- Use memory search to see if this failure or a similar one was recorded before.
+
+Avoid changing code until the evidence points to a specific cause.
+
+## Escalation Guidance
+
+Escalate when any of the following are true:
+
+- Three fix attempts have failed.
+- The failure spans multiple services, repositories, or teams.
+- The root cause points to an architectural assumption that needs a decision.
+- The fix would require a breaking change or new dependency.
+- The bug is security-sensitive or affects production data integrity.
+
+When escalating, include the Evidence Log, the current hypothesis, and the commands that reproduce the failure.
+
+## Short Example
+
+A failing test reports `TypeError: Cannot read property 'name' of undefined`.
+
+1. Reproduce: run the single test; it fails every time.
+2. Localize: the undefined value comes from a mapper function that receives `user.profile`.
+3. Reduce: pass the smallest payload that still triggers the undefined read.
+4. Fix root cause: the upstream API now omits `profile` for guests; update the mapper to handle missing `profile`.
+5. Guard: add a regression test with a guest payload.
+6. Verify: run the new test without the fix to confirm it fails, then with the fix, then run the full suite.

package/dist/template/.pi/skills/deep-module-design/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: deep-module-design
+description: Applies Ousterhout's deep module principles to code design — small interfaces, information hiding, pull complexity downward. Use when designing modules, refactoring shallow structures, or reviewing AI-generated code for structural quality.
+---
+
+# Deep Module Design
+
+> Based on John Ousterhout's *A Philosophy of Software Design*
+
+## Overview
+
+A deep module has a **small interface relative to its implementation**. It provides significant functionality through a compact abstraction, hiding complexity from its callers. A shallow module has an **interface as complex as its implementation** — it wraps one small thing with ceremony, adding overhead without hiding anything.
+
+**Why this matters for AI agents:** AI coding tools generate code faster than humans can review. Shallow modules compound this problem — every AI pass can produce more tiny, shallow abstractions that increase cognitive load without reducing complexity. Deep modules constrain the AI: a small, stable interface limits the blast radius of AI-generated changes and makes verification tractable.
+
+> *"The most important technique for achieving deep modules is information hiding."* — Ousterhout
+
+## When to Use
+
+- Designing a new module, class, or API boundary
+- Reviewing code for structural quality (beyond just correctness)
+- Refactoring a codebase where changes are too expensive because interfaces are too complex
+- Working with AI agents that need tight, stable interfaces to produce reliable code
+- Any time you find yourself writing a class/method that just calls another class/method
+
+## When NOT to Use
+
+- Prototyping where the abstraction will change completely (use after stabilization)
+- Tiny utility functions that are inherently single-purpose and shallow by nature
+- Code that will be replaced within the sprint
+
+## Core Concept: Deep vs Shallow
+
+### Deep Module
+
+```
+┌─────────────────────────────────────┐
+│       COMPLEX IMPLEMENTATION        │
+│   (caching, retries, batching,      │
+│    connection pooling, fallbacks)    │
+│                                     │
+│   ┌─────────────────────────────┐   │
+│   │     SMALL INTERFACE         │   │
+│   │   get(key), set(key, val)   │   │
+│   └─────────────────────────────┘   │
+└─────────────────────────────────────┘
+```
+
+Example: Unix I/O (`open`, `read`, `write`, `close`). Five system calls hide filesystems, device drivers, disk scheduling, buffering, permissions, and network mounts. The interface has not changed in decades.
+
+### Shallow Module
+
+```
+┌─────────────────────┐
+│  SMALL IMPLEMENT.   │
+│  (just wraps one    │
+│   function call)    │
+│                     │
+│  ┌───────────────┐  │
+│  │ COMPLEX IFACE │  │
+│  │ many methods,  │  │
+│  │ many config    │  │
+│  │ options        │  │
+│  └───────────────┘  │
+└─────────────────────┘
+```
+
+Example: A "ParserFactory" that has one method `createParser(type)` which does a switch statement. The factory adds a class, an interface, and a registration mechanism — more surface area than the problem requires. Better to just call the parser directly or use a simple config object.
+
+### Self-Test
+
+Ask about ANY module you design or review:
+
+> "Can I understand this module's interface in 30 seconds?"
+> "Does the caller need to know implementation details to use it?"
+> "Is this module's API surface area proportional to the complexity it hides?"
+
+If the interface takes longer to learn than the implementation, the module is shallow — either deepen it or eliminate it.
+
+## Design Principles
+
+### 1. Information Hiding
+
+The most important technique for achieving deep modules. Every implementation detail that callers don't need to know about should be private, internal, or abstracted away.
+
+**Signs of information leakage:**
+- Configuration that callers must set but relates to internal behavior (buffer sizes, retry counts, thread pool sizes)
+- Methods that expose internal types (returning database rows, internal DTOs)
+- Callers constructing complex intermediate objects before calling your API
+
+**Fix:** Move the complexity inside. Default everything. Accept simple inputs.
+
+### 2. Pull Complexity Downward
+
+If a feature introduces complexity, handle it inside the module rather than pushing it to callers.
+
+| [ ] Pushed to caller | [x] Pulled downward |
+|---|---|
+| Caller must handle retries, timeouts, and fallbacks | Module handles them internally |
+| Caller must format data correctly before passing | Module accepts raw data and transforms it |
+| Caller must manage connection lifecycle | Module manages pools transparently |
+
+> *"It is more important for a module to have a simple interface than a simple implementation."* — Ousterhout
+
+### 3. General-Purpose vs Special-Purpose
+
+General-purpose modules tend to be **deeper** because they solve a class of problems, not just one specific case. Special-purpose modules tend to be **shallower** because they're closely coupled to one use case.
+
+**Rule of thumb:** Design modules to solve general problems. A "UserRepository" is deep (CRUD + queries for any user need). A "GetUserForLoginHandler" is shallow (only handles one specific query) — better to have a general `getUser` method and let callers filter as needed.
+
+**Exception:** If the general-purpose interface would be significantly harder to understand, keep it special-purpose. Depth wins over generality.
+
+### 4. Different Layer, Different Abstraction
+
+Each layer of a system should provide a **different abstraction**. If two layers provide the same abstraction, one of them is redundant.
+
+**Red flag — pass-through methods:**
+```typescript
+// Layer 2: Service layer
+class UserService {
+  constructor(private repo: UserRepository) {}
+
+  // This is a pass-through — it adds nothing
+  getUser(id: string) {
+    return this.repo.findById(id);
+  }
+}
+```
+
+If a method does nothing except delegate with the exact same signature, it's a **pass-through method** — a sign the layer boundary is wrong. Either make the layer do something meaningful, or remove it.
+
+**Red flag — pass-through variables:**
+```typescript
+// Top-level handler
+function handleRequest(req, config) {
+  return processRequest(req, config);
+}
+
+// Middle layer
+function processRequest(req, config) {
+  return executeQuery(req, config);
+}
+
+// Bottom layer
+function executeQuery(req, config) {
+  return db.query(req, config);
+}
+```
+
+When the same variable (`config`) passes through multiple layers without being used by the middle layers, it's a **pass-through variable**. This couples all layers to the config shape. Fix: put config in a global context, or restructure so the middle layers don't need it.
+
+## Red Flag Catalog
+
+| Red Flag | What it looks like | Fix |
+|---|---|---|
+| **Shallow module** | Interface as complex as its implementation | Eliminate or merge into caller |
+| **Information leakage** | One module exposes types another module depends on | Move the types to a shared neutral location or hide them |
+| **Pass-through method** | Method just delegates with same signature | Remove the middle layer or make it add value |
+| **Pass-through variable** | Same data flows through many layers unused | Use a context object or restructure |
+| **Replicated code smell** | Same pattern appears across modules instead of once | Extract a deeper module that encapsulates the pattern |
+| **Configuration pollution** | Callers must configure internal behavior (buffer sizes, timeouts) | Auto-detect or default everything |
+| **Returning internal state** | API exposes DB rows, internal DTOs, or raw storage types | Map to public types at the boundary |
+| **Temporal coupling** | Methods must be called in a specific order not enforced by types | Design so invalid states are unrepresentable |
+
+## AI-Specific Applications
+
+Deep modules are especially valuable for AI-generated code:
+
+| Problem | Deep module solution |
+|---|---|
+| AI creates shallow wrappers every time it refactors | Eliminate or merge them — keep the abstraction layer count minimal |
+| AI introduces pass-through methods when adding layers | Spot them in review and remove — they add surface area without depth |
+| AI makes cascading changes because interfaces are too wide | Narrow interfaces — a small, stable surface limits blast radius |
+| AI generates inconsistent implementations across similar operations | Create one deep general-purpose module the AI can reuse instead of reimplementing |
+| AI hallucinates configuration options the module doesn't need | Remove configurability — deep modules default aggressively |
+
+## Verification
+
+- [ ] Every module's interface is easier to understand than its implementation
+- [ ] No pass-through methods (methods that just delegate with same signature)
+- [ ] No information leakage (callers don't depend on internal types)
+- [ ] No configuration that should be internalized
+- [ ] Different layers provide different abstractions
+- [ ] AI agents could safely use this module without reading its implementation
+
+## See Also
+
+- **code-review-and-quality** — Assess for shallow modules and information leakage during review
+- **api-and-interface-design** — Deep module principles applied to REST/API design
+- **code-cleanup** — Consolidate shallow modules during cleanup passes
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>deep-module-design</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Modules assessed, red flags found or cleared, depth ratio evaluated</evidence>
+  <artifacts>Files or modules reviewed/designed</artifacts>
+  <risks>Known shallow modules deferred, or none</risks>
+</skill_result>
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The interface is simple enough" | Shallow modules (complex interface, simple implementation) leak complexity to callers. Go deep. |
+| "I'll add this convenience method to the interface" | Every interface addition is a future compatibility constraint. Be minimal. |
+| "Abstraction is always good" | Bad abstraction is worse than no abstraction. Generalize on the third use, not the first. |
+
+## Red Flags
+
+- Interface method count exceeding implementation method count (shallow module)
+- Information leakage between modules through shared mutable state
+- "General" or "utils" modules with no clear responsibility
+- Abstraction layer that adds indirection without hiding complexity
+- Module boundary crossed for data that should be encapsulated

package/dist/template/.pi/skills/defense-in-depth/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: defense-in-depth
+description: Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible
+---
+
+# Defense-in-Depth Validation
+
+> **Replaces** single-layer validation where bad data propagates silently until it causes cryptic failures deep in execution
+
+## When to Use
+
+- A bug is caused by invalid data flowing through multiple layers
+- One validation check is insufficient because data crosses boundaries
+
+## When NOT to Use
+
+- Simple, single-layer validation at an obvious entry point is enough
+- The issue is unrelated to invalid data or boundary checks
+
+## Common Rationalizations
+
+| Rationalization                                  | Rebuttal                                                                                                  |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| "One validation at the entry point is enough"    | Different code paths, refactors, and mocks all bypass a single gate — each layer catches what others miss |
+| "This adds too much boilerplate"                 | Each validation is 2-3 lines. The bug it prevents costs hours of debugging                                |
+| "The caller already validates this"              | You don't control the caller. New callers won't know your assumptions                                     |
+| "Tests will catch it"                            | Tests run after the fact. Validation prevents the bug from existing                                       |
+| "This is an internal function, input is trusted" | Internal functions get called from new paths during refactors. Trust no input                             |
+
+## Anti-Patterns
+
+| Anti-Pattern                                             | Why It Fails                                  | Instead                                                      |
+| -------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
+| Validating only at the entry point (trusting downstream) | Alternate paths and refactors bypass one gate | Add independent checks at each boundary                      |
+| Duplicating identical validation at every layer          | Creates noise without improving safety        | Tailor each layer to boundary-specific invariants            |
+| Catching and swallowing errors silently                  | Hides failures and delays detection           | Raise explicit errors with actionable context                |
+| Mixing validation with business logic                    | Makes behavior hard to reason about and test  | Keep validation checks explicit and separate from core logic |
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === "") {
+    throw new Error("workingDirectory cannot be empty");
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error("projectDir required for workspace initialization");
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === "test") {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(`Refusing git init outside temp dir during tests: ${directory}`);
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug("About to git init", {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Verification
+
+- Test with invalid input at each layer boundary — each should reject independently.
+- Remove one validation layer — the next layer should still catch the error.
+
+## See Also
+
+- `verification-before-completion` skill
+- `behavioral-kernel` skill
+
+## Red Flags
+
+- Validation only at the outermost layer
+- Trusting upstream data without verification
+- Error handling that assumes valid input
+- "This can never be null" comments without null checks
+- Single-point validation in a multi-hop data flow
+
+## Verification
+
+After applying defense-in-depth:
+
+- [ ] Validation exists at every system boundary data crosses
+- [ ] Each layer validates independently, not relying on upstream guarantees
+- [ ] Invalid data cannot reach the persistence or business logic layer
+- [ ] Error handling at each layer is appropriate (not swallowing, not crashing)
+- [ ] New validation rules have corresponding tests