Initial commit

skills/ts-quality/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: ts-quality
+description: Enforce TypeScript quality standards immediately after writing or modifying .ts/.tsx files. Run type checking and linting on each changed file for instant feedback. Use after creating/editing TypeScript files, or when quality checks, typecheck, lint, or validate are mentioned.
+---
+
+# TypeScript Quality Enforcement
+
+This skill helps maintain TypeScript code quality by running instant checks on each file after it's written or modified.
+
+## What This Skill Does
+
+When activated, this skill ensures TypeScript code meets quality standards by:
+
+1. **Type Checking** - Runs `pnpm exec tsc --noEmit <file>` to ensure zero TypeScript type errors
+2. **Linting** - Runs `pnpm lint <file>` to enforce code style consistency
+
+Checks run on the SPECIFIC FILE that was just written/modified, not the entire project.
+
+## When to Use This Skill
+
+Activate this skill:
+
+- **Immediately after writing or modifying any .ts or .tsx file**
+- After creating new TypeScript files
+- After editing existing TypeScript files
+- When user mentions: "quality checks", "typecheck", "lint", "validate code"
+- Before creating git commits
+- During code review processes
+
+## Quality Standards
+
+**ZERO TOLERANCE POLICY**: No lint errors or type errors are acceptable.
+
+### Required Checks (in sequence):
+
+1. **Type Checking** - File-scoped typecheck
+   - Must pass with zero errors
+   - Validates TypeScript type safety for the specific file
+
+2. **Linting** - File-scoped lint
+   - Must pass with zero errors
+   - Enforces consistent code formatting and style
+
+## Instructions
+
+When this skill is active, follow these steps:
+
+### 1. Announce Activation
+
+Immediately inform the user that quality checks are running:
+
+```
+🔍 Checking {filename}...
+```
+
+Replace `{filename}` with the actual file path (e.g., `src/utils/auth.ts`).
+
+### 2. Identify the File to Check
+
+Determine which TypeScript file was just written or modified. This is the file to check.
+
+### 3. Run File-Scoped Quality Checks
+
+Execute checks sequentially on the SPECIFIC FILE ONLY:
+
+```bash
+# Type check the specific file
+pnpm exec tsc --noEmit path/to/file.ts
+
+# Lint the specific file
+pnpm lint path/to/file.ts
+```
+
+**Important**:
+- Only check the file that was written/modified
+- Do NOT run project-wide checks
+- Each command must succeed before the next runs
+
+### 4. Report Results
+
+**If all checks pass:**
+Report success clearly:
+```
+✓ {filename}: typecheck and lint passed
+```
+
+**If any check fails:**
+- Report the specific errors with line numbers
+- Format: `✗ {filename}: found N errors`
+- Show the actual error messages
+- DO NOT proceed to subsequent checks
+- DO NOT allow commits with failing checks
+- Fix the errors before continuing
+
+## Type Safety Guidelines
+
+### DO:
+
+- Use explicit types for function parameters and return values
+- Leverage TypeScript's type inference for simple variable assignments
+- Use `unknown` instead of `any` when the type is truly unknown
+- Define interfaces for object shapes
+- Use type guards for runtime validation of external data
+- Document complex types with JSDoc comments
+
+### DO NOT:
+
+- Use `any` without explicit justification in comments
+- Ignore TypeScript errors (no `@ts-ignore` without explanation)
+- Skip typecheck before committing
+- Commit code with lint errors
+- Use `@ts-expect-error` to suppress valid errors
+- Bypass quality checks "just this once"
+
+## Examples
+
+### Example 1: Creating New TypeScript File
+
+**User**: "Create a new TypeScript component for user authentication"
+
+**Actions**:
+1. Create the file with proper types (explicit parameter and return types)
+2. Avoid using `any` types
+3. After file creation, immediately run quality checks:
+   - Announce: `🔍 Checking src/components/Auth.tsx...`
+   - Run: `pnpm exec tsc --noEmit src/components/Auth.tsx`
+   - Run: `pnpm lint src/components/Auth.tsx`
+   - Report: `✓ src/components/Auth.tsx: typecheck and lint passed`
+4. Only consider the task complete when checks pass
+
+### Example 2: Modifying Existing Code
+
+**User**: "Update the session processing logic to handle new event types"
+
+**Actions**:
+1. Make changes to the file maintaining type safety
+2. After saving the file, immediately run quality checks:
+   - Announce: `🔍 Checking packages/session/src/processor.ts...`
+   - Run: `pnpm exec tsc --noEmit packages/session/src/processor.ts`
+   - Run: `pnpm lint packages/session/src/processor.ts`
+   - Report results:
+     - If passed: `✓ packages/session/src/processor.ts: typecheck and lint passed`
+     - If failed: `✗ packages/session/src/processor.ts: found 2 errors` (then show errors)
+
+### Example 3: File with Errors
+
+**User**: Writes a file with type errors
+
+**Actions**:
+1. Announce: `🔍 Checking src/utils/helper.ts...`
+2. Run typecheck: `pnpm exec tsc --noEmit src/utils/helper.ts`
+3. Detect errors and report:
+   ```
+   ✗ src/utils/helper.ts: found 3 errors
+
+   src/utils/helper.ts:15:5 - error TS2322: Type 'string' is not assignable to type 'number'.
+   src/utils/helper.ts:22:10 - error TS2339: Property 'foo' does not exist on type 'User'.
+   src/utils/helper.ts:35:3 - error TS2345: Argument of type 'null' is not assignable to parameter of type 'string'.
+   ```
+4. Do NOT proceed to lint
+5. Wait for user to fix errors
+
+## Integration with pnpm Workspaces
+
+This skill works with pnpm workspace monorepos by checking individual files in their packages.
+
+File-scoped checks work across packages without needing to change directories.
+
+## Quick Reference Commands
+
+```bash
+# File-scoped typecheck (fast, targeted)
+pnpm exec tsc --noEmit path/to/file.ts
+
+# File-scoped lint
+pnpm lint path/to/file.ts
+
+# Both checks in sequence
+pnpm exec tsc --noEmit path/to/file.ts && pnpm lint path/to/file.ts
+```
+
+## Error Handling
+
+When errors occur:
+
+1. **Type Errors**: Show the file, line number, and error message
+2. **Lint Errors**: Show the file, line number, rule violated, and how to fix
+
+Always provide actionable information to help fix the errors.
+
+## Best Practices
+
+- **Check after every file write** - Instant feedback prevents accumulating errors
+- **Fix errors immediately** - Don't accumulate technical debt
+- **Type errors first** - Must be resolved before linting
+- **Never commit failing code** - No exceptions
+- **File-scoped only** - Don't run project-wide checks
+- **Pragmatic quality** - Focus on correctness, not perfection
+
+## Requirements
+
+This skill requires projects to have:
+
+- **pnpm** installed
+- **TypeScript** installed and configured
+- **Linter** (Biome, ESLint, or similar) configured
+
+The skill uses:
+- `pnpm exec tsc --noEmit <file>` for type checking
+- `pnpm lint <file>` for linting