What problem does it solves?
This Skill prevents the recurrence of bugs caused by invalid data by mandating validation at every layer data passes through. It makes bugs structurally impossible rather than relying on a single, potentially bypassable check, ensuring robust system integrity.
Core Features & Use Cases
- Four Layers of Validation: Guides implementation of checks at entry point, business logic, environment guards, and debug instrumentation, creating a comprehensive defense.
- Structural Bug Prevention: Ensures that even if one validation layer is bypassed, subsequent layers will catch the invalid data, preventing issues from propagating.
- Context-Specific Guards: Recommends environment-specific checks (e.g., refusing
git init outside temp directories in tests) to prevent dangerous operations in specific contexts.
- Use Case: After fixing a bug where an empty
projectDir caused git init in the source code, this skill ensures you add validation not just at the Project.create() call, but also in WorkspaceManager, WorktreeManager (with environment guards), and debug logging, making the bug impossible to reintroduce.
Quick Start
Example: Validating workingDirectory for project creation
Layer 1: Entry Point Validation (API boundary)
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});
}
// ... more checks ...
}
Layer 2: Business Logic Validation (operation-specific)
function initializeWorkspace(projectDir: string, sessionId: string) {
if (!projectDir) {
throw new Error('projectDir required for workspace initialization');
}
// ...
}
Layer 3: Environment Guards (context-specific dangers)
async function gitInit(directory: string) {
if (process.env.NODE_ENV === 'test') {
// Refuse git init outside temp dir during tests
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});
}
}
// ...
}
Layer 4: Debug Instrumentation (forensics)
async function gitInit(directory: string) {
const stack = new Error().stack;
logger.debug('About to git init', { directory, cwd: process.cwd(), stack });
// ...
}
