anvil-dev-framework 0.1.6

package/global/commands/verify.md

@@ -0,0 +1,251 @@
+# /verify - Verification Feedback Loop
+
+> Run verification suite with automatic iteration on failure. This is the highest-impact technique from Boris Cherny's methodology.
+
+## When to Use
+- After implementing a feature or fix
+- Before committing changes
+- When tests, lint, or types are failing
+- As part of any completion workflow
+
+## Why This Matters
+> Boris Cherny: "Verification is #1... 2-3x quality improvement"
+
+Traditional workflow: Code → Commit → Find errors later
+Verification workflow: Code → Verify → Fix → Verify → Commit clean
+
+The iteration loop catches issues immediately, reducing rework.
+
+## Arguments
+- (none) - Run full verification suite
+- `--test-only` - Run tests only, skip lint/types
+- `--lint-only` - Run lint only
+- `--quick` - Skip type checking (faster iteration)
+- `--max N` - Override max iterations (default: 3)
+
+## Execution Steps
+
+### Step 1: Run Verification Suite
+Execute all configured verification commands in order:
+
+```bash
+# Detect project type and run appropriate commands
+# Node.js projects
+npm test
+npm run lint
+npm run typecheck
+
+# Python projects
+pytest
+ruff check .
+mypy .
+
+# Or custom commands from .claude/settings.yaml
+```
+
+### Step 2: Analyze Results
+**If ALL pass:**
+```
+✅ Verification passed
+   Tests: 47 passed
+   Lint: clean
+   Types: clean
+
+Ready for commit.
+```
+
+**If ANY fail:**
+```
+❌ Verification failed - 3 test failures
+
+Analyzing failures...
+- src/auth/login.test.ts:45 - Expected 200, got 401
+- src/auth/login.test.ts:67 - Timeout after 5000ms
+- src/utils/format.test.ts:12 - undefined is not a function
+```
+
+### Step 3: Iterate on Failures (max 3 times)
+For each failing file:
+1. **Re-read** the failing file to get current state
+2. **Analyze** the specific error message and location
+3. **Apply** a targeted fix (minimal change)
+4. **Re-run** only the failing command
+5. **Repeat** until pass or max iterations reached
+
+```
+Attempting fix (iteration 1/3)...
+→ Reading src/auth/login.test.ts
+→ Issue: Mock not returning expected status
+→ Fix: Update mock return value
+→ Re-running tests...
+
+Attempting fix (iteration 2/3)...
+→ Reading src/utils/format.test.ts
+→ Issue: Function renamed but test not updated
+→ Fix: Update test to use new function name
+→ Re-running tests...
+
+✅ Verification passed after 2 iterations
+```
+
+### Step 4: Report Final State
+
+**Success:**
+```
+✅ Verification passed
+   Iterations: 2
+   Tests: 47 passed
+   Lint: clean
+   Types: clean
+
+All checks passed. Ready for commit.
+```
+
+**Failure after max iterations:**
+```
+⚠️ Verification failed after 3 attempts
+
+Remaining issues:
+1. src/auth/login.test.ts:67 - Timeout (may need mock adjustment)
+2. Integration test requires live database
+
+These issues need manual intervention.
+Suggested actions:
+- Review timeout configuration
+- Check if test requires external dependencies
+```
+
+## Configuration
+
+Project-specific settings in `.claude/settings.yaml`:
+
+```yaml
+verification:
+  commands:
+    test: "npm test"          # or "pytest", "cargo test"
+    lint: "npm run lint"      # or "ruff check .", "cargo clippy"
+    types: "npm run typecheck" # or "mypy .", "cargo check"
+  max_iterations: 3
+  required_for_completion: true
+  timeout_seconds: 300
+```
+
+## Detecting Project Type
+
+If no config exists, auto-detect:
+
+| File Exists | Project Type | Commands |
+|-------------|--------------|----------|
+| `package.json` | Node.js | npm test, npm run lint, npm run typecheck |
+| `pyproject.toml` | Python | pytest, ruff check, mypy |
+| `Cargo.toml` | Rust | cargo test, cargo clippy, cargo check |
+| `go.mod` | Go | go test ./..., golangci-lint run |
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| ❌ Make broad changes during fix | ✅ Make minimal, targeted fixes |
+| ❌ Continue past max iterations | ✅ Escalate and ask for help |
+| ❌ Ignore failing checks | ✅ Address every failure |
+| ❌ Change unrelated code | ✅ Only fix the specific error |
+| ❌ Skip verification to save time | ✅ Always verify before commit |
+| ❌ Commit with failing tests | ✅ Fix all issues first |
+
+## Examples
+
+### Basic Usage
+```
+User: /verify
+
+Claude: Running verification suite...
+✅ Verification passed
+   Tests: 47 passed
+   Lint: clean
+   Types: clean
+```
+
+### With Failures
+```
+User: /verify
+
+Claude: Running verification suite...
+❌ 2 test failures detected
+
+Attempting fix (iteration 1/3)...
+→ Fixed missing mock in auth.test.ts
+
+Re-running tests...
+✅ Verification passed after 1 iteration
+```
+
+### Quick Mode
+```
+User: /verify --quick
+
+Claude: Running quick verification (no type check)...
+✅ Tests: 47 passed
+✅ Lint: clean
+⏭️ Types: skipped (--quick mode)
+```
+
+### Max Iterations Exceeded
+```
+User: /verify
+
+Claude: Running verification suite...
+❌ Test failure detected
+
+Attempting fix (iteration 1/3)... failed
+Attempting fix (iteration 2/3)... failed
+Attempting fix (iteration 3/3)... failed
+
+⚠️ Could not fix automatically after 3 attempts.
+
+Issue: Integration test requires database connection
+File: src/db/connection.test.ts:34
+
+This needs manual review. Possible causes:
+- Missing test database setup
+- Environment variable not set
+- Network connectivity issue
+```
+
+## State File
+
+Verification state is persisted at `.claude/verification-state.json`:
+
+```json
+{
+  "last_run": "2026-01-04T14:30:00Z",
+  "status": "passed",
+  "iterations": 2,
+  "results": {
+    "tests": { "passed": true, "count": 47 },
+    "lint": { "passed": true, "errors": 0 },
+    "types": { "passed": true, "errors": 0 }
+  }
+}
+```
+
+This state is used by:
+- Stop hook gate (block exit if verification required)
+- Ralph Wiggum mode (track iteration progress)
+- Statusline (show verification status)
+
+## Integration Points
+
+| Component | Integration |
+|-----------|-------------|
+| Stop Hook Gate | Reads verification state to allow/block exit |
+| Ralph Wiggum Mode | Uses verify as completion gate |
+| `/evidence` | Captures verification output as proof |
+| Statusline | Shows pass/fail indicator |
+
+## Key Behaviors
+
+1. **Always run all checks** - Don't skip steps even if early ones fail
+2. **Parse errors precisely** - Extract file paths and line numbers
+3. **Fix targeted** - Minimal changes to address specific errors
+4. **Track iterations** - Know when to stop and escalate
+5. **Report clearly** - User should always know current state

package/global/commands/weekly-review.md

@@ -0,0 +1,156 @@
+# /weekly-review - Generate Analytics and Recommendations
+
+> Weekly review of development process with metrics and improvement suggestions.
+
+## When to Use
+- End of each week (Friday recommended)
+- Before sprint planning
+- When process feels inefficient
+- Monthly/quarterly reviews
+
+## Execution Steps
+
+### Step 1: Gather Week's Data
+
+**From Linear**:
+- Issues completed this week
+- Issues created this week
+- Current backlog size
+- Blocked issues
+- Average cycle time
+
+**From Git**:
+```bash
+# Commits this week
+git log --oneline --since="7 days ago"
+
+# Files changed
+git diff --stat HEAD~7..HEAD 2>/dev/null || git log --stat --since="7 days ago"
+
+# PRs merged (if using GitHub)
+gh pr list --state merged --search "merged:>=$(date -v-7d +%Y-%m-%d)"
+```
+
+**From Handoffs**:
+- Sessions this week
+- Context switches
+- Discovered work filed
+
+### Step 2: Calculate Metrics
+
+| Metric | Calculation |
+|--------|-------------|
+| Velocity | Issues completed / week |
+| Throughput | PRs merged / week |
+| Cycle Time | Avg days from start to done |
+| Discovery Rate | Discovered issues / planned issues |
+| Block Rate | % of time spent blocked |
+
+### Step 3: Analyze Patterns
+
+Look for:
+- Repeated blockers
+- Scope creep patterns
+- Quality issues (reverts, hotfixes)
+- Estimation accuracy
+- Context switch frequency
+
+### Step 4: Generate Weekly Report
+
+Output:
+```markdown
+## Weekly Review: [Week of Date]
+
+### Velocity Metrics
+| Metric | This Week | Last Week | Trend |
+|--------|-----------|-----------|-------|
+| Issues Completed | 8 | 6 | ↑ |
+| PRs Merged | 5 | 4 | ↑ |
+| Commits | 23 | 18 | ↑ |
+| Discovered Issues | 3 | 5 | ↓ |
+
+### Cycle Time
+| Stage | Avg Time |
+|-------|----------|
+| Todo → In Progress | 1.2 days |
+| In Progress → Review | 2.3 days |
+| Review → Done | 0.5 days |
+| **Total** | **4.0 days** |
+
+### Quality Indicators
+| Indicator | Count |
+|-----------|-------|
+| Reverts | 0 |
+| Hotfixes | 1 |
+| Failed CI | 3 |
+| CodeRabbit Issues | 12 |
+
+### Backlog Health
+- **Active Issues**: 42 (target: <50) ✅
+- **Blocked Issues**: 5 (12%)
+- **Oldest Issue**: 14 days (ENG-89)
+
+### Session Analysis
+- **Sessions**: 8
+- **Avg Session Length**: 2.5 hours
+- **Context Switches**: 4
+- **Handoffs Created**: 6
+
+### Wins This Week 🎉
+1. [Significant accomplishment]
+2. [Significant accomplishment]
+
+### Challenges
+1. [Challenge encountered]
+2. [Challenge encountered]
+
+### Patterns Observed
+- [Pattern 1]: [Observation and impact]
+- [Pattern 2]: [Observation and impact]
+
+### Recommendations
+1. **[Area]**: [Specific recommendation]
+2. **[Area]**: [Specific recommendation]
+3. **[Area]**: [Specific recommendation]
+
+### Focus for Next Week
+1. [Priority 1]
+2. [Priority 2]
+3. [Priority 3]
+
+---
+*Review generated: [timestamp]*
+```
+
+### Step 5: Archive Report
+Save to: `.claude/analytics/weekly-[YYYY-WW].md`
+
+## Metrics Reference
+
+### Health Indicators
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Active Issues | <50 | 50-75 | >75 |
+| Blocked % | <10% | 10-25% | >25% |
+| Cycle Time | <5 days | 5-10 days | >10 days |
+| Discovery Rate | <30% | 30-50% | >50% |
+| Reverts/week | 0 | 1-2 | >2 |
+
+### Trend Indicators
+- ↑ Improving
+- → Stable
+- ↓ Declining
+
+## Key Behaviors
+- Consistent weekly cadence
+- Compare to previous weeks
+- Actionable recommendations
+- Celebrate wins
+- Be honest about challenges
+
+## Integration Points
+- Follows: Week's work
+- Precedes: Sprint planning
+- Creates: `.claude/analytics/weekly-*.md`
+- Triggers: `/decay-review` for cleanup