Guardian

Overview

Guardian validates code quality by learning patterns directly from exemplar code in your codebase, then checking if new code follows those patterns. Pure discovery-based approach with zero hardcoded assumptions.

When to Use This Skill

Activate Guardian when:

• Before committing code changes
• During pull request reviews
• When asked to "check code quality" or "review code"
• After implementing new features
• When validating architectural consistency

Core Philosophy

Learn, Don't Assume

Guardian learns everything from the codebase:

• What patterns exist (by reading exemplar files)
• What rules to enforce (by observing consistency)
• What to validate (by understanding context)
• How to search (by discovering naming patterns)

NO hardcoded searches, NO assumed patterns, NO fixed rules.

Meta-Level Reasoning

The skill teaches HOW to figure out what to check:

Instead of: "Check for React hooks"
Do this: "Read how components use hooks, observe the pattern, THEN search for that pattern"

Instead of: "Check package.json"
Do this: "Find the package structure, understand its format, THEN check it"

Instead of: "Look for useQuery"
Do this: "Find data fetching code, see how queries are done, THEN look for violations"

Validation Methodology

Phase 1: Understand the Codebase

Goal: Learn about the codebase before validating anything.

Step 1.1: Identify What Was Changed

Start here - what files did the user change/add?
- Use git status
- Or user tells you specific files
- Or you're checking entire codebase

Step 1.2: Understand File Context

For each file being validated:

1. Where is it located? (path reveals purpose)
2. What's its extension? (.ts, .tsx, .py, etc.)
3. Read the file completely
4. What does it do? (Component? Hook? API? Utility?)
5. What patterns does it use/create?

Key: Read the actual code to understand what you're validating.

Step 1.3: Find Similar Existing Files

Based on the file's apparent purpose:

Example: New file is "useAudioPlayer.hook.ts"
- It's in hooks directory
- Contains a custom hook
- Uses React Query

Find similar files:
- Look in same directory for other *.hook.ts
- Read 2-3 examples completely
- These are your exemplars

How to find exemplars:

1. Same directory (most similar)
2. Same file pattern (name structure)
3. Similar size/complexity
4. Well-implemented (has tests, documentation)

Phase 2: Extract Patterns from Exemplars

Goal: Learn rules by observing consistency across examples.

Step 2.1: Read Exemplars Thoroughly

For each exemplar file:

1. Read COMPLETE file (not just exports)
2. Note structure:
   - What functions are defined?
   - What do they export?
   - What hooks are used?
   - What patterns are followed?

3. Look at imports:
   - What packages are imported?
   - In what order?
   - Any patterns? (external first? types separate?)

4. Observe naming:
   - How are functions named?
   - How are variables named?
   - Any suffixes/prefixes?

5. Check organization:
   - File header comments?
   - Section organization?
   - Documentation style?

Step 2.2: Find Consistency Across Exemplars

Compare 2-3 exemplars:

What's CONSISTENT (= pattern to enforce):
- All hooks return same shape
- All use same error handling
- All have similar structure
- All have same TypeScript patterns
- All registered/exported in same place

What VARIES (= not a rule):
- Specific logic differs
- Parameter counts differ
- Implementation details differ

The consistent parts = validation rules

Step 2.3: Understand WHY Patterns Exist

Read code to understand intent:

Example: All hooks return { data, isLoading, error }
Why? Read exemplar - consistent interface for components
Rule: New hooks must also return this shape

Example: All API routes validate input with Zod
Why? Read route - runtime type safety
Rule: New routes must also validate with Zod

Understanding WHY helps find better violations.

Phase 3: Learn How to Search

Goal: Figure out what to grep for based on discovered patterns.

Step 3.1: Extract Search Terms from Patterns

Based on what you learned:

Pattern discovered: "All hooks use useQuery"
Search term: "useQuery" (the hook name)
Search method: grep for "useQuery" in hooks

Pattern discovered: "Components use Chakra UI"
Search term: Whatever you found in exemplar code
Search method: Look for violations (raw HTML, other UI libs)

Pattern discovered: "Types come from @vox/types"
Search term: Look for type imports
Search method: Check if imports follow pattern

Key: Search terms come from reading code, not assumptions.

Step 3.2: Discover Integration Points

Read exemplar code to find where components connect:

1. Read an exemplar hook file
2. Search entire codebase for its filename
3. Where is it referenced?
   - In components?
   - In other hooks?
   - In index.ts exports?
4. Those locations = integration points to check

Example process:
- Read useAudioPlayer.hook.ts
- grep -r "useAudioPlayer" .
- Find it in: Player.tsx, index.ts
- These are integration patterns to check

Phase 4: Validate New Code

Goal: Check if new code follows discovered patterns.

Step 4.1: Apply Pattern Rules

For each pattern discovered:

Pattern: "Hooks return { data, isLoading, error }"
Check: Read new hook file, find return statement
Validate: Does it return this shape?
Report: If not, it violates the pattern

Pattern: "Components use Chakra UI components"
Check: Read new component, find JSX elements
Validate: Are UI elements from Chakra or raw HTML?
Report: List any non-Chakra UI found

Step 4.2: Check Integration Points

Based on discovered integration:

Example: Hooks are exported from index.ts
1. Find index.ts (same way exemplar was found)
2. Read the file
3. Look for section where exemplar hooks are listed
4. Check if new hook is exported same way
5. Report if missing

Step 4.3: Cross-Reference Pattern

If exemplars have corresponding tests:
- Check if new component also has tests
- Look in same test structure

If exemplars have corresponding types:
- Check if new code has proper types
- Look for type definitions

Phase 5: Report Findings

Goal: Actionable feedback with evidence.

Report Structure

=== Guardian Validation Report ===

File: [path/to/new/file]
Patterns checked: N
Violations found: M

[SEVERITY] Issue Description
Pattern learned from: [exemplar files]
Observed in exemplars: [what the pattern is]
Found in new code: [what violates it]
Fix: [specific correction]
Evidence: [file:line from exemplars]

Example:
[HIGH] Missing error handling
Pattern learned from: useChat.hook.ts, usePlayer.hook.ts
Observed: All hooks handle errors with try/catch (line 24, 31)
Found: useMicrophone throws unhandled errors
Fix: Add try/catch with error state following useChat pattern

Advanced Techniques

Technique 1: Recursive Pattern Discovery

1. Read new file to understand its purpose
2. Find exemplars (similar files)
3. Read exemplars to learn patterns
4. Read files THOSE exemplars reference
5. Build complete pattern map
6. Validate against entire pattern

Technique 2: Convention Extraction

Instead of assuming naming conventions:

1. List all similar files
2. Observe naming patterns:
   - Suffix patterns (*.hook.ts, *.types.ts)
   - Case patterns (PascalCase, camelCase)
   - Organization patterns (by feature, by type)
3. Extract convention from observation
4. Check new files follow same convention

Technique 3: Package Structure Discovery

Don't assume structure:

1. Look for package files:
   - find . -name "package.json"
   - find . -name "tsconfig.json"
   - find . -name "pyproject.toml"

2. Read exemplar packages to understand structure
3. Check new code follows same structure

Integration with Other Skills

Research First

User: "Check code quality"
→ Research: Check CLAUDE.md for coding standards
→ Guardian: Apply those standards + discovered patterns

Builder Shows Correct Way

Guardian: Reports pattern violation
→ Builder: Shows how to follow the pattern correctly

Key Principles

1. Read to understand - Every validation starts with reading code
2. Observe to learn - Patterns emerge from examples, not assumptions
3. Compare to validate - Check new against observed consistency
4. Evidence-based - Always reference exemplar code
5. Adapt continuously - Patterns change, re-learn as needed

Example Workflow

User: "Check useNewFeature.hook.ts"

STEP 1: Understand the file
- Read useNewFeature.hook.ts completely
- It's a custom React hook
- Located in apps/web/src/hooks/

STEP 2: Find exemplars
- List files in apps/web/src/hooks/
- Found: useChat.hook.ts, usePlayer.hook.ts
- Read both completely

STEP 3: Extract patterns
- Both use useQuery for data fetching
- Both return { data, isLoading, error, refetch }
- Both have TypeScript interfaces for params/return
- Both exported from index.ts
- Both handle errors consistently

STEP 4: Learn how to search
- Hook pattern: use[Name].hook.ts
- Export file: hooks/index.ts
- Query pattern: useQuery({ queryKey, queryFn })

STEP 5: Validate useNewFeature.hook.ts
- Check: Uses useQuery? ✓
- Check: Returns standard shape? ✗ Missing refetch
- Check: Has TypeScript interfaces? ✓
- Check: Exported from index.ts? ✗ Missing
- Check: Handles errors? ✗ No error handling

STEP 6: Report
[HIGH] Missing error handling
Pattern learned from: useChat.hook.ts:45, usePlayer.hook.ts:38
Observed: All hooks wrap async calls in try/catch
Found: useNewFeature has unhandled promise
Fix: Add error handling following useChat pattern

[MEDIUM] Not exported from index
Pattern learned from: hooks/index.ts
Observed: All hooks exported for clean imports
Found: useNewFeature not in exports
Fix: Add "export { useNewFeature } from './useNewFeature.hook'"

[LOW] Missing refetch in return
Pattern learned from: useChat.hook.ts:67
Observed: Hooks return refetch for manual refresh
Found: useNewFeature doesn't return refetch
Fix: Include refetch in return object

Success Criteria

Validation complete when:

• Read new code to understand it
• Found and read 2-3 exemplar files
• Extracted consistent patterns from exemplars
• Learned what search terms to use
• Discovered integration points
• Validated new code against all patterns
• Provided evidence-based report

Key Insight

The codebase IS the documentation.

Every rule, every pattern, every convention is learned by reading existing code. No assumptions, no hardcoded searches, no predetermined rules.

If the codebase changes, Guardian adapts automatically because it re-learns patterns from the current state of the code.

Limitations

Guardian cannot:

• Validate correctness of business logic (only patterns)
• Understand product requirements
• Make architectural decisions
• Know if patterns are "good" (just consistent)

For algorithm validation, use tests. For architecture, use human judgment.