SKILL.md
KPI: Verification Pass Rate
Definition: The percentage of times ./verify.sh passes on the first attempt.
Why This Matters
Every failed verification attempt:
- Wastes time re-running checks
- Indicates preventable issues
- Slows down the feedback loop
A high first-pass rate means fewer wasted cycles and faster development.
Metrics
Primary Metric
First-Pass Success Rate - Percentage of verification runs that pass without prior failures.
Formula:
Pass Rate = (Successful First Attempts) / (Total First Attempts) × 100%Target Benchmarks
| Performance | Pass Rate |
|---|---|
| Poor | <50% |
| Acceptable | 50-70% |
| Good | 70-90% |
| Excellent | >90% |
Measurement
Manual Tracking
Before each verify run, note:
- Is this the first attempt after changes?
- Did it pass or fail?
- What stage failed (format/lint/type/test/build)?
Automated (Future)
Track via CI metrics when available.
Improvement Strategies
1. Pre-flight Checks
Before running full verification, run quick checks:
# Quick lint check (fastest)
npm run lint:check
# Type check (catches most issues)
npm run typecheckThese catch ~80% of issues in seconds.
2. Incremental Testing
After each code change:
# Run affected tests only
npm run test -- --only-changed3. IDE Integration
Configure your editor to show:
- Lint errors inline
- Type errors inline
- Format on save
Catch issues before you even run verify.
4. Dependency Validation
Before importing a package:
# Check if it exists and exports what you need
ls packages/<package-name>/srcDon't assume a port exists - verify first.
5. Learn from Failures
Each failure is data:
- What stage failed?
- What was the root cause?
- How could this have been prevented?
Record patterns in typescript-coding skill.
Common Failure Patterns
| Stage | Common Causes | Prevention |
|---|---|---|
| Format | Forgot to format | Auto-format on save |
| Lint | Unused imports, missing types | Check lint before commit |
| Type | Wrong types, missing exports | Run typecheck frequently |
| Test | Logic errors, missing mocks | Write tests first |
| Build | Missing exports, circular deps | Check imports carefully |
Pre-Verification Checklist
Before running ./verify.sh:
- Code saved and formatted
- No lint errors in changed files
- Types look correct
- Tests updated for changes
- All imports resolve
Anti-Patterns
- "Verify and pray" - Running verify.sh as your only check
- Ignoring warnings - Warnings often become errors
- Mass changes - Large changes = more failure modes
- Skipping local verify - CI failures are slower to debug