@allthingsclaude/blueprints 0.1.1

package/content/commands/cleanup.md

@@ -0,0 +1,326 @@
+---
+description: Find and remove dead code, unused imports, and technical debt
+argument-hint: [optional: "imports" | "dead-code" | "types" | "todos" | focus area]
+author: "@markoradak"
+---
+
+# Code Cleanup Assistant
+
+I'll help identify and clean up dead code, unused imports, and technical debt in your codebase.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current`
+
+**Files to Analyze**:
+!`find src -name "*.ts" -o -name "*.tsx" 2>/dev/null | wc -l` TypeScript files
+
+---
+
+## Focus Area
+
+$ARGUMENTS
+
+---
+
+## Cleanup Workflow
+
+Based on the arguments, I'll focus on specific cleanup tasks:
+
+### If "imports" or no argument:
+- Find and remove unused imports
+- Organize import order
+- Remove duplicate imports
+
+### If "dead-code":
+- Find unreferenced exports
+- Identify unused functions/components
+- Detect unreachable code
+
+### If "types":
+- Audit `any` usage
+- Find implicit any
+- Identify redundant type assertions
+
+### If "todos":
+- Inventory all TODO/FIXME/HACK comments
+- Categorize by priority
+- Suggest which to address or remove
+
+### If specific file/folder provided:
+- Deep cleanup of that area only
+
+---
+
+## Cleanup Categories
+
+### 1. Unused Imports
+
+**Detection**:
+```bash
+# ESLint can find these
+pnpm eslint src --rule '@typescript-eslint/no-unused-vars: error' --format compact 2>&1 | grep "no-unused-vars"
+
+# Or check specific file
+grep -E "^import" path/to/file.ts
+```
+
+**Cleanup Strategy**:
+- Remove imports not referenced in the file
+- Remove type-only imports if types aren't used
+- Consolidate multiple imports from same module
+
+### 2. Dead Code
+
+**Detection Patterns**:
+
+**Unreferenced Exports**:
+```bash
+# Find all exports
+grep -rn "export " src/ --include="*.ts" --include="*.tsx"
+
+# Check if each is imported anywhere
+grep -rn "import.*{.*ExportName" src/
+```
+
+**Unused Functions**:
+- Functions defined but never called
+- Event handlers attached to removed elements
+- Utility functions from old features
+
+**Unreachable Code**:
+- Code after return/throw statements
+- Conditions that can never be true
+- Catch blocks for errors that can't occur
+
+### 3. Type Cleanup
+
+**`any` Audit**:
+```bash
+# Find explicit any
+grep -rn ": any" src/ --include="*.ts" --include="*.tsx"
+
+# Find any in function parameters
+grep -rn "(.*any.*)" src/ --include="*.ts"
+```
+
+**Categories**:
+- **Justified**: External library types, truly dynamic data
+- **Lazy**: Should be properly typed
+- **Accidental**: Implicit any from missing types
+
+### 4. TODO/FIXME Inventory
+
+**Detection**:
+```bash
+# Find all TODOs
+grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx"
+```
+
+**Categories**:
+- **Stale**: Old TODOs that are no longer relevant
+- **Completed**: Work is done but comment remains
+- **Valid**: Still needs to be done
+- **Won't Do**: Decided against implementing
+
+### 5. Console Statements
+
+**Detection**:
+```bash
+# Find console.log/warn/error
+grep -rn "console\." src/ --include="*.ts" --include="*.tsx"
+```
+
+**Categories**:
+- **Debug**: Should be removed
+- **Intentional**: Error logging, should use proper logger
+- **Temporary**: Left from debugging session
+
+### 6. Commented Code
+
+**Detection**:
+- Large blocks of commented-out code
+- Commented function definitions
+- "Old" or "backup" comments
+
+**Policy**:
+- If it's in git history, delete it
+- If it might be needed, create a branch
+- Never commit commented-out code
+
+---
+
+## Cleanup Report Format
+
+```markdown
+# Cleanup Report
+
+**Scanned**: [X] files in [path]
+**Date**: [timestamp]
+**Focus**: [area or "all"]
+
+---
+
+## Summary
+
+| Category | Found | Auto-fixable | Manual Review |
+|----------|-------|--------------|---------------|
+| Unused Imports | X | X | 0 |
+| Dead Code | X | 0 | X |
+| `any` Types | X | 0 | X |
+| TODOs | X | N/A | X |
+| Console Statements | X | X | 0 |
+| Commented Code | X | X | 0 |
+
+**Estimated Impact**: -[X] lines of code
+
+---
+
+## Unused Imports
+
+### `src/components/Example.tsx`
+
+**Remove**:
+```typescript
+// Line 3: unused
+import { unusedFunction } from '@/lib/utils'
+
+// Line 5: only 'used' is used, remove 'unused'
+import { used, unused } from '@/lib/helpers'
+```
+
+**After**:
+```typescript
+import { used } from '@/lib/helpers'
+```
+
+---
+
+## Dead Code
+
+### Unreferenced Exports
+
+| Export | File | Last Modified | Recommendation |
+|--------|------|---------------|----------------|
+| `oldHelper` | `src/lib/utils.ts:45` | 3 months ago | Remove |
+| `deprecatedFn` | `src/lib/api.ts:123` | 6 months ago | Remove |
+
+### Unused Functions
+
+**`src/lib/helpers.ts:78`** - `formatOldDate()`
+- Not imported anywhere
+- Last modified: [date]
+- **Recommendation**: Remove
+
+---
+
+## Type Issues
+
+### `any` Usage
+
+| Location | Context | Recommendation |
+|----------|---------|----------------|
+| `src/api/route.ts:23` | API response | Type as `ApiResponse` |
+| `src/utils/parse.ts:45` | JSON parse | Use `unknown` + validation |
+| `src/lib/external.ts:12` | 3rd party | Justified - add comment |
+
+---
+
+## TODO Inventory
+
+### Stale (Remove)
+
+- `src/old.ts:45`: "TODO: refactor this" (file deleted 2 months ago)
+- `src/api.ts:23`: "FIXME: temporary" (been there 6 months)
+
+### Valid (Keep/Address)
+
+- `src/auth.ts:89`: "TODO: add rate limiting" - Still needed
+- `src/db.ts:34`: "FIXME: optimize query" - Performance issue
+
+### Completed (Remove)
+
+- `src/user.ts:56`: "TODO: add validation" - Validation exists
+
+---
+
+## Console Statements
+
+| Location | Type | Action |
+|----------|------|--------|
+| `src/debug.ts:12` | `console.log` | Remove (debug) |
+| `src/api.ts:45` | `console.error` | Replace with logger |
+
+---
+
+## Commented Code
+
+| Location | Lines | Age | Action |
+|----------|-------|-----|--------|
+| `src/old.tsx:34-56` | 22 | 4 months | Remove |
+| `src/utils.ts:78-89` | 11 | 2 months | Remove |
+
+---
+
+## Recommended Actions
+
+### Auto-fix (Safe)
+
+These can be automatically cleaned up:
+
+1. [ ] Remove unused imports
+2. [ ] Remove console.log statements
+3. [ ] Remove commented-out code
+
+Run: "Would you like me to auto-fix these?"
+
+### Manual Review Required
+
+These need human decision:
+
+1. [ ] Review dead code exports before removal
+2. [ ] Decide on TODO items
+3. [ ] Type the `any` usages appropriately
+
+---
+
+## Next Steps
+
+1. Review this report
+2. Approve auto-fixes
+3. Address manual review items
+4. Run `pnpm typecheck && pnpm lint` to verify
+5. Commit cleanup: `git commit -m "chore: code cleanup"`
+```
+
+---
+
+## Auto-Fix Capabilities
+
+When user approves, I can automatically:
+
+- **Remove unused imports**: Edit files to remove
+- **Remove console statements**: Edit to remove (except console.error in catch blocks)
+- **Remove commented code**: Edit to remove blocks
+- **Organize imports**: Sort and group imports
+
+I will NOT automatically:
+- Remove functions (might have dynamic usage)
+- Change `any` types (needs proper typing)
+- Remove TODOs (needs human decision)
+- Remove exports (might be used externally)
+
+---
+
+## Safety Guidelines
+
+1. **Always validate after cleanup**: Run typecheck and lint
+2. **Review before committing**: Show git diff
+3. **Don't break functionality**: When in doubt, leave it
+4. **Track what was removed**: Clear commit message
+
+---
+
+Begin cleanup analysis based on the focus area provided. Use Grep to find patterns, Read to analyze context, and Edit to apply fixes (with user approval).

package/content/commands/critique.md

@@ -0,0 +1,34 @@
+---
+description: Critique Mode
+author: "@markoradak"
+---
+
+# Critique Mode
+
+You are now in "CRITIQUE" mode. Provide direct, unfiltered feedback without sugar-coating. Your goal is to give the most helpful criticism possible, even if it's uncomfortable to hear.
+
+## Guidelines
+- Be direct and specific about problems, flaws, or better alternatives
+- Don't soften criticism with excessive politeness
+- Point out obvious issues that might be ignored due to politeness
+- Suggest concrete improvements, not just criticism
+- Focus on what's actually wrong or suboptimal
+- Call out bad practices, poor decisions, or flawed reasoning
+- Still be professional, but prioritize honesty over comfort
+
+## Response Style
+- Start with the biggest/most important issues first
+- Use clear, direct language: "This is wrong because..." not "You might consider..."
+- Don't hedge with "maybe" or "perhaps" when you're confident about an issue
+- Give specific examples of why something won't work
+- Mention consequences of continuing with flawed approaches
+
+## What to focus on
+- Technical issues that will cause problems later
+- Inefficient or overcomplicated approaches
+- Security vulnerabilities or bad practices
+- Design decisions that will hurt maintainability
+- Unrealistic expectations or timelines
+- Missing critical considerations
+
+$ARGUMENTS

package/content/commands/debug.md

@@ -0,0 +1,283 @@
+---
+description: Investigate and diagnose issues with systematic analysis
+argument-hint: [error message, file path, or behavior description]
+author: "@markoradak"
+---
+
+# Debug Assistant
+
+I'll systematically investigate and diagnose the issue you're experiencing.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current`
+
+**Recent Changes** (potential cause):
+!`git log --oneline -5`
+
+**Modified Files**:
+!`git status --short`
+
+---
+
+## Issue Description
+
+$ARGUMENTS
+
+---
+
+## Debugging Methodology
+
+I'll follow a systematic approach to diagnose this issue:
+
+### Phase 1: Reproduce & Understand
+
+1. **Clarify the Issue**
+   - What is the expected behavior?
+   - What is the actual behavior?
+   - When did this start happening?
+   - Is it reproducible consistently?
+
+2. **Gather Context**
+   - Check error messages and stack traces
+   - Review relevant logs
+   - Identify affected files/components
+
+### Phase 2: Isolate the Problem
+
+3. **Narrow Down the Scope**
+   - Which layer is the issue in? (UI, API, DB, external service)
+   - Is it environment-specific? (dev, prod, test)
+   - Does it affect all users/data or specific cases?
+
+4. **Trace Data Flow**
+   - Follow the execution path
+   - Check input/output at each step
+   - Identify where behavior diverges from expected
+
+### Phase 3: Root Cause Analysis
+
+5. **Identify Candidates**
+   - Recent code changes (git blame, git log)
+   - Configuration changes
+   - Dependency updates
+   - External factors (API changes, data issues)
+
+6. **Verify Hypothesis**
+   - Test each candidate systematically
+   - Use console.log/debugger strategically
+   - Check edge cases and boundary conditions
+
+### Phase 4: Resolution
+
+7. **Develop Fix**
+   - Address root cause, not symptoms
+   - Consider side effects
+   - Validate fix doesn't break other things
+
+8. **Prevent Recurrence**
+   - Add test coverage
+   - Improve error handling
+   - Update documentation if needed
+
+---
+
+## Diagnostic Commands
+
+### Error Analysis
+```bash
+# Search for error patterns in logs
+grep -r "error" .next/server/ 2>/dev/null | tail -20
+
+# Check recent console output
+# (User should provide if available)
+
+# TypeScript errors
+pnpm typecheck 2>&1 | head -50
+```
+
+### Code Investigation
+```bash
+# Find where something is defined
+grep -rn "functionName" src/
+
+# Check recent changes to a file
+git log -p --follow -5 -- path/to/file.ts
+
+# Find all usages of a function/component
+grep -rn "ComponentName" src/
+```
+
+### Runtime Investigation
+```bash
+# Check if dev server is running
+lsof -i :3000 2>/dev/null || echo "Port 3000 not in use"
+
+# Check environment
+env | grep -E "^(DATABASE|NEXT|NODE)" | head -10
+```
+
+### Database Investigation
+```bash
+# Check Prisma schema
+cat prisma/schema.prisma | grep -A5 "model"
+
+# Verify database connection
+pnpm prisma db pull --print 2>&1 | head -20
+```
+
+---
+
+## Common Issue Patterns
+
+### TypeScript Errors
+- **"Cannot find module"**: Check imports, paths, tsconfig
+- **"Type X is not assignable"**: Verify types match at boundaries
+- **"Property does not exist"**: Check object shape, optional chaining
+
+### React/Next.js Issues
+- **Hydration mismatch**: Server/client rendering differences
+- **"use client" missing**: Server component using client features
+- **Stale data**: Cache invalidation, revalidation issues
+
+### API/tRPC Issues
+- **401/403**: Authentication/authorization check
+- **500**: Server-side error, check logs
+- **Network error**: CORS, URL configuration
+
+### Database Issues
+- **Connection refused**: Check DATABASE_URL, server running
+- **Unique constraint**: Duplicate data, check upsert logic
+- **Foreign key violation**: Related record doesn't exist
+
+### Build Issues
+- **Module not found**: Check dependencies, imports
+- **Out of memory**: Increase Node memory, check for loops
+- **Type errors**: Run `pnpm typecheck` for details
+
+---
+
+## Output Format
+
+After investigation, provide a structured diagnosis:
+
+```markdown
+# Diagnosis Report
+
+**Issue**: [One-line summary]
+**Severity**: [Critical/High/Medium/Low]
+**Category**: [TypeScript/Runtime/Database/Network/Configuration]
+
+---
+
+## Summary
+
+[2-3 sentence overview of what's happening and why]
+
+---
+
+## Root Cause
+
+**Location**: `path/to/file.ts:123`
+
+**Problem**: [Detailed explanation of the root cause]
+
+**Evidence**:
+- [Finding 1 that supports this diagnosis]
+- [Finding 2]
+- [Relevant code snippet or error message]
+
+---
+
+## Investigation Trail
+
+1. **Checked**: [What was investigated]
+   - **Finding**: [What was found]
+
+2. **Checked**: [Next investigation step]
+   - **Finding**: [Result]
+
+3. **Conclusion**: [How findings led to root cause]
+
+---
+
+## Recommended Fix
+
+### Option 1: [Primary fix] (Recommended)
+
+**File**: `path/to/file.ts:123`
+
+**Current Code**:
+```typescript
+// problematic code
+```
+
+**Fixed Code**:
+```typescript
+// corrected code
+```
+
+**Why This Works**: [Explanation]
+
+### Option 2: [Alternative fix]
+
+[If there's a reasonable alternative approach]
+
+---
+
+## Verification Steps
+
+1. [ ] Apply the fix
+2. [ ] Run `pnpm typecheck` - should pass
+3. [ ] Run `pnpm lint` - should pass
+4. [ ] Test the specific scenario that was failing
+5. [ ] Run related tests: `pnpm test [pattern]`
+
+---
+
+## Prevention
+
+- [ ] Add test case for this scenario
+- [ ] Consider adding validation at [location]
+- [ ] Update documentation if behavior was unclear
+
+---
+
+## Related Files
+
+- `path/to/related.ts` - [Why relevant]
+- `path/to/another.ts` - [Why relevant]
+```
+
+---
+
+## Investigation Strategies by Issue Type
+
+### "It was working before"
+1. Check `git log` for recent changes
+2. Use `git bisect` to find breaking commit
+3. Review dependency updates in package.json
+
+### "It works locally but not in production"
+1. Compare environment variables
+2. Check build output differences
+3. Review deployment logs
+4. Verify database state
+
+### "It works sometimes"
+1. Look for race conditions
+2. Check for timing-dependent logic
+3. Review caching behavior
+4. Check for data-dependent paths
+
+### "The error message doesn't make sense"
+1. Find where the error is thrown
+2. Check what condition triggers it
+3. Add logging to trace the path
+4. Look for error transformation/wrapping
+
+---
+
+Begin systematic investigation based on the issue description provided. Use Read to examine files, Grep to search for patterns, and Bash for diagnostics. Ask clarifying questions if the issue description is insufficient.