tlc-claude-code 0.6.4 → 0.7.0

package/autofix.md

@@ -0,0 +1,327 @@
+# /tlc:autofix - Automatic Test Failure Recovery
+
+Automatically fix failing tests with AI-powered debugging.
+
+## Usage
+
+```
+/tlc:autofix [test-file]
+```
+
+If no file specified, fixes all failing tests.
+
+## What This Does
+
+1. Runs tests to identify failures
+2. Analyzes failure reasons
+3. Attempts fixes with reasoning
+4. Retries up to max attempts
+5. Reports results with explanations
+
+## Process
+
+### Step 1: Identify Failing Tests
+
+Run test suite and capture failures:
+
+```bash
+npm test 2>&1
+```
+
+Parse output:
+```
+Failing Tests:
+
+1. login.test.js
+   ✗ throws ValidationError for null email
+     Expected: ValidationError
+     Actual: TypeError: Cannot read property 'toLowerCase' of null
+
+2. users.test.js
+   ✗ returns empty array when no users
+     Expected: []
+     Actual: null
+```
+
+### Step 2: Analyze Each Failure
+
+For each failing test:
+
+```
+Analyzing: "throws ValidationError for null email"
+
+Test Code:
+  it('throws ValidationError for null email', async () => {
+    await expect(login(null, 'password'))
+      .to.be.rejectedWith(ValidationError);
+  });
+
+Error:
+  TypeError: Cannot read property 'toLowerCase' of null
+  at login (src/auth/login.ts:15)
+
+Source Code (line 15):
+  const normalizedEmail = email.toLowerCase();
+
+Analysis:
+  - Test expects ValidationError for null input
+  - Code tries to call .toLowerCase() on email before validation
+  - Null check should happen BEFORE string operations
+
+Proposed Fix:
+  Add null check at start of function, before any string operations.
+```
+
+### Step 3: Generate Fix
+
+```typescript
+// BEFORE (line 12-20 of src/auth/login.ts)
+async function login(email: string, password: string): Promise<User> {
+  const normalizedEmail = email.toLowerCase();
+
+  if (!normalizedEmail || !password) {
+    throw new ValidationError('Email and password required');
+  }
+  // ...
+}
+
+// AFTER
+async function login(email: string, password: string): Promise<User> {
+  if (!email || !password) {
+    throw new ValidationError('Email and password required');
+  }
+
+  const normalizedEmail = email.toLowerCase();
+  // ...
+}
+```
+
+### Step 4: Apply Fix and Retry
+
+```
+Applying fix to src/auth/login.ts...
+
+Running test: "throws ValidationError for null email"
+  ✓ PASSED
+
+Fix successful!
+
+Commit this fix? (Y/n)
+```
+
+### Step 5: Handle Complex Failures
+
+If simple fix doesn't work, try alternative approaches:
+
+```
+Attempt 1: Move null check before toLowerCase()
+  Result: ✗ Still failing
+
+Analyzing deeper...
+  The test expects ValidationError but we throw generic Error
+
+Attempt 2: Change throw to ValidationError
+  Result: ✗ Still failing - ValidationError not imported
+
+Attempt 3: Import ValidationError and use it
+  Result: ✓ PASSED
+
+Fix required 3 attempts:
+  1. Moved null check (insufficient)
+  2. Changed error type (missing import)
+  3. Added import (success)
+```
+
+### Step 6: Report Results
+
+```
+╭─────────────────────────────────────────────────────────────╮
+│  AutoFix Results                                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Failing tests found: 6                                     │
+│  Successfully fixed: 5                                      │
+│  Could not fix: 1                                           │
+│                                                             │
+│  Fixed:                                                     │
+│    ✓ login.test.js - null email handling                    │
+│    ✓ login.test.js - empty password handling                │
+│    ✓ users.test.js - empty array return                     │
+│    ✓ users.test.js - pagination bounds                      │
+│    ✓ api.test.js - timeout handling                         │
+│                                                             │
+│  Could not fix:                                             │
+│    ✗ integration.test.js - database connection              │
+│      Reason: Requires external service configuration        │
+│      Suggestion: Check DATABASE_URL environment variable    │
+│                                                             │
+│  Files modified:                                            │
+│    - src/auth/login.ts (2 changes)                          │
+│    - src/api/users.ts (1 change)                            │
+│    - src/api/index.ts (1 change)                            │
+│                                                             │
+╰─────────────────────────────────────────────────────────────╯
+
+Commit all fixes? (Y/n)
+```
+
+## Fix Strategies
+
+### Strategy 1: Direct Fix
+Simple issues with obvious solutions:
+- Missing null checks
+- Wrong return types
+- Missing imports
+- Typos
+
+### Strategy 2: Pattern Matching
+Recognize common error patterns:
+```
+TypeError: Cannot read property 'X' of null/undefined
+→ Add null check before accessing property
+
+Expected X but got undefined
+→ Add return statement or default value
+
+Timeout exceeded
+→ Increase timeout or add async handling
+```
+
+### Strategy 3: Test-Driven Fix
+Use the test assertion to guide the fix:
+```
+Test expects: throws ValidationError
+Code does: throws Error
+Fix: Change Error to ValidationError
+```
+
+### Strategy 4: Contextual Analysis
+Read surrounding code for patterns:
+```
+Similar function handles null this way...
+Following project's error handling pattern...
+Using existing validation utility...
+```
+
+## Configuration
+
+In `.tlc.json`:
+
+```json
+{
+  "autofix": {
+    "maxAttempts": 5,
+    "strategies": ["direct", "pattern", "test-driven", "contextual"],
+    "autoCommit": false,
+    "excludePatterns": ["integration.test.*", "e2e.*"],
+    "timeout": 30000
+  }
+}
+```
+
+## Limitations
+
+AutoFix works best for:
+- ✓ Simple logic errors
+- ✓ Missing null/undefined checks
+- ✓ Type mismatches
+- ✓ Missing imports
+- ✓ Wrong return values
+
+AutoFix struggles with:
+- ✗ Complex business logic bugs
+- ✗ Architecture issues
+- ✗ External service problems
+- ✗ Race conditions
+- ✗ Performance issues
+
+When AutoFix can't solve it:
+```
+Could not fix: "handles concurrent requests"
+
+Analysis:
+  This appears to be a race condition in the request handler.
+  Multiple requests modify shared state without synchronization.
+
+This requires manual investigation:
+  1. Review shared state in src/api/handler.ts
+  2. Consider adding mutex/lock
+  3. Or redesign to avoid shared state
+
+Would you like to:
+  1) Log this as a bug (/tlc:bug)
+  2) Create a task for manual fix
+  3) Skip for now
+```
+
+## Example Session
+
+```
+> /tlc:autofix
+
+Running tests...
+  12 passing
+  4 failing
+
+Analyzing failures...
+
+[1/4] login.test.js - "throws for null email"
+  Error: TypeError: Cannot read property 'toLowerCase' of null
+  Fix: Add null check before string operation
+  Applying... ✓ Fixed
+
+[2/4] login.test.js - "rejects empty password"
+  Error: Expected ValidationError, got nothing
+  Fix: Add validation for empty string
+  Applying... ✓ Fixed
+
+[3/4] users.test.js - "returns empty array"
+  Error: Expected [], got null
+  Fix: Return [] instead of null when no results
+  Applying... ✓ Fixed
+
+[4/4] integration.test.js - "connects to database"
+  Error: ECONNREFUSED 127.0.0.1:5432
+  Cannot fix: External service issue
+  Suggestion: Start PostgreSQL or set DATABASE_URL
+
+Results: 3/4 fixed
+
+Modified files:
+  - src/auth/login.ts
+  - src/api/users.ts
+
+Commit fixes? (Y/n) y
+
+Committed: fix: resolve 3 failing tests (null checks, empty returns)
+
+1 test still failing - requires manual attention.
+```
+
+## Integration with Build
+
+AutoFix runs automatically during `/tlc:build` when tests fail:
+
+```
+/tlc:build
+
+Writing tests... ✓
+Running tests...
+  ✗ 2 tests failing
+
+AutoFix enabled. Attempting repairs...
+  ✓ Fixed 2/2 failures
+
+Re-running tests...
+  ✓ All tests passing
+
+Continuing with implementation...
+```
+
+## Notes
+
+- AutoFix modifies source code - review changes before committing
+- Use `--dry-run` to preview fixes without applying
+- Fixes are atomic - each fix is a separate change
+- If fix breaks other tests, it's rolled back
+- Works best with good test descriptions

package/bin/install.js

@@ -28,20 +28,41 @@ ${c.cyan}  ████████╗██╗     ██████╗
 const VERSION = require('../package.json').version;
 
 const COMMANDS = [
+  // Core workflow
   'tlc.md',
   'new-project.md',
   'init.md',
   'import-project.md',
-  'coverage.md',
   'discuss.md',
   'plan.md',
   'build.md',
   'verify.md',
-  'status.md',
   'progress.md',
   'complete.md',
   'new-milestone.md',
   'quick.md',
+  // Quality & Testing
+  'status.md',
+  'coverage.md',
+  'quality.md',
+  'edge-cases.md',
+  'autofix.md',
+  'config.md',
+  // Team Collaboration
+  'claim.md',
+  'release.md',
+  'who.md',
+  'bug.md',
+  'server.md',
+  // CI/CD & Integration
+  'ci.md',
+  'issues.md',
+  // Documentation
+  'docs.md',
+  // Multi-Tool & Deployment
+  'export.md',
+  'deploy.md',
+  // Help
   'help.md'
 ];
 

package/bug.md

@@ -0,0 +1,255 @@
+# /tlc:bug - Log a Bug or Feedback
+
+Report issues discovered during development or QA verification.
+
+## Usage
+
+```
+/tlc:bug [description]
+```
+
+Or interactive:
+```
+/tlc:bug
+```
+
+## Process
+
+### Step 1: Gather Bug Information
+
+If description provided as argument, use it. Otherwise prompt:
+
+```
+What's the issue?
+> Login fails when email contains a + symbol
+
+Where did you find this?
+1) During development
+2) During /tlc:verify (QA)
+3) From automated tests
+4) User reported
+> 2
+
+Severity?
+1) Critical - blocks release
+2) High - major feature broken
+3) Medium - workaround exists
+4) Low - cosmetic/minor
+> 2
+```
+
+### Step 2: Identify Context
+
+Automatically detect:
+- Current user: `git config user.name` or `$TLC_USER`
+- Current phase: from `.planning/ROADMAP.md`
+- Current task: from any `[>@user]` marker in PLAN.md
+- Git branch: `git branch --show-current`
+- Last commit: `git log -1 --oneline`
+
+### Step 3: Generate Bug ID
+
+Format: `BUG-{NNN}` where NNN is sequential.
+
+Read `.planning/BUGS.md` to find highest existing ID, increment.
+
+### Step 4: Create Bug Entry
+
+Append to `.planning/BUGS.md`:
+
+```markdown
+---
+
+### BUG-007: Login fails with + symbol in email
+
+**Status:** Open
+**Severity:** High
+**Reporter:** @alice
+**Date:** 2024-01-26
+**Phase:** 2 - Authentication
+**Task:** Task 3 - Email validation
+**Branch:** feature/auth
+**Commit:** a1b2c3d
+
+**Description:**
+Login fails when email contains a + symbol (e.g., user+test@example.com)
+
+**Steps to Reproduce:**
+1. Go to login page
+2. Enter email: user+test@example.com
+3. Enter valid password
+4. Click Login
+
+**Expected:** Should accept valid email and log in
+**Actual:** Shows "Invalid email format" error
+
+**Notes:**
+Plus addressing is valid per RFC 5321. Regex validation is too strict.
+```
+
+### Step 5: Commit Bug Report
+
+```bash
+git add .planning/BUGS.md
+git commit -m "bug: BUG-007 - Login fails with + symbol (@alice)"
+```
+
+### Step 6: Link to Task (Optional)
+
+If bug relates to a specific task, offer to add reference:
+
+```
+Link this bug to Task 3 in the current phase? (Y/n)
+```
+
+If yes, add to task in PLAN.md:
+```markdown
+### Task 3: Email validation [>@bob]
+
+**Bugs:** BUG-007
+```
+
+### Step 7: Notify
+
+```
+Bug logged: BUG-007
+File: .planning/BUGS.md
+Committed: bug: BUG-007 - Login fails with + symbol (@alice)
+
+Push to share with team? (Y/n)
+```
+
+## Bug Status Workflow
+
+| Status | Meaning |
+|--------|---------|
+| Open | New, not yet addressed |
+| In Progress | Someone is fixing |
+| Fixed | Code fixed, needs verification |
+| Verified | Fix confirmed working |
+| Closed | Resolved |
+| Won't Fix | Declined with reason |
+
+## Updating Bug Status
+
+To update an existing bug:
+
+```
+/tlc:bug --update BUG-007 --status "Fixed"
+```
+
+Or interactive:
+```
+/tlc:bug --update
+
+Which bug?
+  BUG-005: Session timeout too short (Open)
+  BUG-006: Missing loading spinner (Open)
+  BUG-007: Login fails with + symbol (Open)
+> BUG-007
+
+New status?
+1) In Progress
+2) Fixed
+3) Verified
+4) Closed
+5) Won't Fix
+> 2
+
+Add resolution notes?
+> Fixed regex in src/auth/validate.ts to allow + in local part
+
+Updated BUG-007: Open → Fixed
+```
+
+## Viewing Bugs
+
+To see all open bugs:
+
+```
+/tlc:bug --list
+
+Open Bugs (3):
+
+| ID | Severity | Description | Reporter | Phase |
+|----|----------|-------------|----------|-------|
+| BUG-005 | Medium | Session timeout too short | @alice | 2 |
+| BUG-006 | Low | Missing loading spinner | @bob | 2 |
+| BUG-007 | High | Login fails with + symbol | @alice | 2 |
+
+Critical: 0 | High: 1 | Medium: 1 | Low: 1
+```
+
+## Integration with /tlc:verify
+
+During `/tlc:verify`, QA is prompted to log bugs:
+
+```
+Testing Task 3: Email validation
+
+Did you find any issues? (Y/n) y
+
+/tlc:bug (interactive mode)
+...
+```
+
+## Example Session
+
+```
+> /tlc:bug "Button color doesn't match design spec"
+
+Gathering context...
+  User: @alice
+  Phase: 3 - Dashboard
+  Branch: feature/dashboard
+
+Severity?
+1) Critical
+2) High
+3) Medium
+4) Low
+> 4
+
+BUG-008 created:
+  "Button color doesn't match design spec"
+  Severity: Low
+  Phase: 3 - Dashboard
+
+Committed: bug: BUG-008 - Button color doesn't match design spec (@alice)
+
+Push? (Y/n) y
+Pushed to origin/feature/dashboard
+```
+
+## BUGS.md Format
+
+The bugs file has a header and entries:
+
+```markdown
+# Bug Tracker
+
+## Summary
+
+| Status | Count |
+|--------|-------|
+| Open | 3 |
+| In Progress | 1 |
+| Fixed | 2 |
+| Closed | 5 |
+
+## Open Bugs
+
+### BUG-007: Login fails with + symbol in email
+...
+
+### BUG-006: Missing loading spinner
+...
+
+## Closed Bugs
+
+### BUG-001: App crashes on startup
+**Status:** Closed
+**Resolution:** Fixed null check in main.ts
+**Closed:** 2024-01-25 by @bob
+...
+```