Validate

Validate

Purpose: Run validation checks for code quality, security, and correctness Modes: Quick (default) | Full (--full) | Fix (--fix) | CI Mirror (--ci) Usage: /validate [scope flags]

Iron Laws

1. NEVER SKIP TYPE CHECK — Type check is the first gate. If it fails, nothing else matters. Fix types before running lint or tests.
2. REPORT WHAT THE OUTPUT SAYS — Never summarize or interpret validation output. Show the actual errors with file paths and line numbers.
3. FAILURES ARE NOT SUGGESTIONS — A failing validation means the code is not ready. Do not proceed past a failing check.
4. NO CLAIMS WITHOUT FRESH EVIDENCE — Never report a check as passing without showing the actual command output from this session. Words like "should pass," "probably works," or "looks correct" are not verification. Run the command, read the output, then state the result.

When to Use

• After making code changes to check nothing is broken
• Before committing to ensure quality
• As part of /implement or /finish workflows
• To check if CI will pass locally

When NOT to Use

• Writing or running specific tests → /test-coverage or /tdd
• Reviewing code quality and patterns → /review
• Fixing bugs → /debug
• Security-specific audit → /security-review

Early Exit

If git status shows no changes and no specific mode is requested, report "No changes to validate" and offer to run full validation anyway.

Constraints

• Type check must pass before running tests
• Report all failures clearly with file, line, and suggested fix
• Stop at first failing level (don't waste time on later checks)
• Never skip type check
• Never commit with lint errors
• Run scoped tests by default (not full suite unless --full)

Note: Detect package manager from lockfile (package-lock.json = npm, pnpm-lock.yaml = pnpm, yarn.lock = yarn, bun.lockb = bun). Use detected manager for all commands. Command examples below use npm as placeholder — substitute the detected manager.

Scope Flags

Examples:

/validate                           # Quick validation of uncommitted changes
/validate --files=src/components/   # Specific directory
/validate --full                    # Complete CI pipeline
/validate --fix                     # Auto-fix lint/format issues
/validate --ci                      # Mirror exact CI checks
/validate --full --coverage         # Full validation with coverage

Quick Validation (Default)

Fast feedback during development — validate only what changed.

Step 0: Determine Scope

git diff --name-only HEAD
git diff --name-only --staged  # if --staged flag

Level 1: Syntax & Style

Execution order within this level: Run checks in dependency order: (a) Typecheck first (catches type errors that cause other failures), (b) Lint second (may depend on types), (c) Tests third (need types and imports correct), (d) Build last (depends on all above). This prevents cascading failures from obscuring root causes.

Format Check:

npm run format:check 2>/dev/null || npx prettier --check [changed-files]

Type Check:

npm run typecheck

Lint:

npm run lint -- [changed-files]

Security Scan (always runs):

See references/security-scan-patterns.md for concrete grep patterns for secrets, dangerous functions, and security anti-patterns. Run these scans as part of full validation.

# Secrets detection
grep -rn --include="*.ts" --include="*.tsx" --include="*.js" --include="*.json" \
  -E "(api[_-]?key|secret|password|token|credential|private[_-]?key)\s*[:=]" [changed-files]

# Insecure pattern detection
grep -rn --include="*.ts" --include="*.tsx" --include="*.js" \
  -E "(eval\(|new Function\(|innerHTML\s*=|dangerouslySetInnerHTML|document\.write\()" [changed-files]

# Raw SQL interpolation (injection risk)
grep -rn --include="*.ts" --include="*.tsx" --include="*.js" \
  -E "(\\\$queryRaw\`|\\\$executeRaw\`|\.query\(.*\\\$\{|SELECT.*\\\$\{|INSERT.*\\\$\{|UPDATE.*\\\$\{|DELETE.*\\\$\{)" [changed-files]

# Command injection patterns
grep -rn --include="*.ts" --include="*.tsx" --include="*.js" \
  -E "(child_process|exec\(|execSync\(|spawn\(|execFile\()" [changed-files]

# Disabled security controls
grep -rn --include="*.ts" --include="*.tsx" --include="*.js" \
  -E "(rejectUnauthorized:\s*false|NODE_TLS_REJECT_UNAUTHORIZED|--no-verify)" [changed-files]

Interpreting results:

• Secrets: Any match in non-test, non-example files is a blocker — do not proceed
• eval/innerHTML/dangerouslySetInnerHTML: Requires justification — flag for review
• Raw SQL with interpolation: Blocker unless using tagged template literals (Prisma.sql\...``)
• child_process/exec: Flag for review — verify no user input reaches the command
• Disabled TLS/verification: Blocker unless in test configuration only

Report:

### Level 1: Syntax & Style

| Check | Status | Details |
|-------|--------|---------|
| Format | ✓ Pass / ✗ Fail | [N files need formatting] |
| Types | ✓ Pass / ✗ Fail | [N errors] |
| Lint | ✓ Pass / ✗ Fail | [N errors, M warnings] |
| Secrets | ✓ Pass / ⚠️ Review | [N potential secrets found] |
| Security patterns | ✓ Pass / ⚠️ Review | [N insecure patterns found] |

If failures, stop and report before Level 2.

Level 2: Scoped Tests

Run tests only for changed components/files:

npm run test -- ComponentName
npm run test -- "src/components/"

Level 3: Integration (Optional)

For UI changes, suggest manual verification:

npm run dev

Full Validation (--full)

Complete CI pipeline verification before push/merge.

Report:

## Full Validation Results

| Step | Check | Status | Time |
|------|-------|--------|------|
| 1 | Format | ✓ Pass | 2s |
| 2 | Types | ✓ Pass | 8s |
| ... | ... | ... | ... |

✅ **All CI checks passed** — Ready to push

Fix Mode (--fix)

Auto-correct formatting and lint issues.

1. Auto-fix format: npm run format 2>/dev/null || npx prettier --write [changed-files]
2. Auto-fix lint: npm run lint -- --fix [changed-files]
3. Verify fixes: Re-run typecheck and lint
4. Run scoped tests: npm run test -- [affected-tests]

Report:

## Fix Mode Results

### Auto-fixed
| Type | Files Fixed | Issues Resolved |
|------|-------------|-----------------|
| Format | 5 | 23 |
| Lint | 3 | 8 |

### Remaining Issues (manual fix required)
| File | Line | Issue |
|------|------|-------|
| `src/utils.ts` | 45 | Type error: cannot assign... |

CI Mirror Mode (--ci)

Run exact same checks as CI pipeline.

1. Detect CI config: Look for .github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile
2. Extract CI steps: Parse config and run equivalent local commands
3. Report: Show CI job → local command → status mapping

In CI mode (--mode=ci):

• Run the same checks as full mode
• Use non-interactive output (no fix offers)
• Exit with non-zero code on any failure
• Output results in a format parseable by CI systems (structured JSON or standard exit codes)

Verification Patterns

Regression Test Verification

When validating a bug fix with a regression test, verify the test actually catches the bug:

1. Write the regression test
2. Run it → MUST PASS (with the fix in place)
3. Revert the fix
4. Run it → MUST FAIL (proves the test catches the bug)
5. Restore the fix
6. Run it → MUST PASS (confirms fix works)

A regression test that passes both with and without the fix proves nothing. Skip the red-green cycle only for tests that verify new behavior (not bug fixes).

Agent Delegation Verification

When a subagent reports task completion, verify independently:

1. Check the VCS diff — does it show the expected changes?
2. Run validation commands yourself — don't trust "all tests pass" claims from agents
3. Report the actual state based on your own verification

Common Issues & Solutions (see references/validation-troubleshooting.md for expanded patterns including build failures and CI discrepancies)

Type Errors

Test Failures

Validation Levels Reference

Acceptance Tests

Converted and distributed by TomeVault — claim your Tome and manage your conversions.