Recovery Strategies

// Before
export function formatDate(date: Date): string {  // Unused
  return date.toISOString();
}
export function parseDate(str: string): Date {  // Used
  return new Date(str);
}
 
// After (fixer removes unused function)
export function parseDate(str: string): Date {
  return new Date(str);
}

# Fixer deletes entire file
rm src/components/OldWidget.tsx
 
# Removes imports from other files
# Updates barrel exports

# Detects with depcheck
npx depcheck
 
# Removes from package.json
npm uninstall lodash

// Original code (untested)
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}
 
// Fixer generates test
describe('capitalize', () => {
  it('should capitalize first letter', () => {
    expect(capitalize('hello')).toBe('Hello');
  });
 
  it('should handle empty string', () => {
    expect(capitalize('')).toBe('');
  });
 
  it('should handle single character', () => {
    expect(capitalize('a')).toBe('A');
  });
});

// Before
async function login(email: string, password: string) {
  console.log('Login attempt:', email);  // Remove
  console.debug('Password:', password);  // Remove
  const user = await authenticate(email, password);
  return user;
}
 
// After
async function login(email: string, password: string) {
  const user = await authenticate(email, password);
  return user;
}

// Before
// export function oldMethod() { ... }  // Remove this
export function newMethod() { ... }
 
// After
export function newMethod() { ... }

// Before
// TODO: Implement validation  // Fixer implements or removes
function process(input: string) {
  return input;
}
 
// After (fixer implements basic validation)
function process(input: string): string {
  if (!input || input.trim().length === 0) {
    throw new Error('Invalid input');
  }
  return input.trim();
}

// Before
function calculate(a, b) {  // Implicit any
  return a + b;
}
 
// After
function calculate(a: number, b: number): number {
  return a + b;
}

// Before
interface User {
  name: string;
}
 
const user: User = { name: 'John', age: 30 };  // Error: age not in interface
 
// After
interface User {
  name: string;
  age?: number;  // Made optional
}
 
const user: User = { name: 'John', age: 30 };

# Detects missing types
# import express from 'express'  // No @types/express
 
# Installs automatically
npm install --save-dev @types/express

// Before
const unused = 5;
const used = 10;
console.log(used);
 
// After
const used = 10;
console.log(used);

// Before (wrong order)
import { internal } from './internal';
import React from 'react';
import lodash from 'lodash';
 
// After (correct order)
import React from 'react';
import lodash from 'lodash';
import { internal } from './internal';

// Before
const obj ={key:'value'};  // Spacing issues
 
// After
const obj = { key: 'value' };

// Before
const API_KEY = "sk-1234567890abcdef";  // ❌ Never commit
 
// After
const API_KEY = process.env.API_KEY;
 
// Fixer also updates .env.example
echo "API_KEY=your_api_key_here" >> .env.example

# npm audit shows vulnerability
# lodash@4.17.15 has high severity vulnerability
 
# Fixer updates
npm update lodash
 
# If breaking changes, creates decision for manual review

// Before
// @ts-ignore
const data = JSON.parse(maybeInvalid);
 
// After (fixer adds proper validation)
const data = JSON.parse(maybeInvalid) as unknown;
if (isValidData(data)) {
  return data;
}
throw new Error('Invalid data');

{
  "passed": false,
  "mustFix": [
    "Remove unused export: formatDate in src/utils/date.ts",
    "Add tests to reach 80% coverage (currently 72%)",
    "Remove console.log from src/auth/login.ts:45"
  ]
}

// Priority 1: Quick fixes
// - Remove console.log (line 45)
// - Remove unused export
 
// Priority 2: Medium effort
// - Generate tests for coverage
 
// Priority 3: Complex fixes
// - Refactor if needed

{
  "passed": true,
  "summary": "All issues resolved"
}

{
  "current_task": null,
  "current_phase": "idle"
}

// Fixer detects circular dependency
// src/a.ts imports from src/b.ts
// src/b.ts imports from src/a.ts
 
// Can't auto-fix - requires refactoring decision
// Creates decision in decisions.json

{
  "id": "arch-decision-001",
  "question": "How to resolve circular dependency between a.ts and b.ts?",
  "options": [
    "Extract shared code to c.ts",
    "Combine into single module",
    "Use dependency injection pattern"
  ],
  "blocking": ["feature-x"],
  "timestamp": "2026-01-18T00:00:00Z"
}

// Fixer can't update major version
// package.json: "package": "1.0.0"
// Vulnerability fixed in "package": "2.0.0"
 
// Creates decision for manual approval

// Fixer can generate basic tests
// But complex integration tests need manual design
 
describe('user authentication flow', () => {
  // Fixer creates simple test
  it('should authenticate valid user', async () => {
    // ... basic test
  });
 
  // Manual test needed for:
  it('should handle rate limiting', async () => {
    // Complex scenario with timing
  });
 
  it('should handle concurrent logins', async () => {
    // Race condition testing
  });
});

// Fixer can implement validation
// But business rules need human input
 
// Example: Discount calculation
function calculateDiscount(total: number, customer: Customer): number {
  // Fixer can add basic validation
  if (total <= 0) throw new Error('Invalid total');
 
  // But business rule needs human:
  // "VIP customers get 15% discount on orders over $100
  //  but only on Tuesdays, and not during sale periods"
 
  // Creates decision for business logic clarification
}

// Fixer can't set up external services
// Database connections, API keys, etc.
 
// Creates decision with setup instructions
{
  "question": "Database configuration needed",
  "context": "Add DATABASE_URL to .env",
  "instructions": "1. Create database at Supabase\n2. Add URL to .env\n3. Run migrations"
}

# User runs decision command
/agentful-decide
 
# agentful presents options
❓ How to resolve circular dependency?
 
[1] Extract shared code to c.ts
[2] Combine into single module
[3] Use dependency injection pattern
 
Your choice: 1
 
✅ Decision recorded. Continuing development...

// Issue found
console.log in src/auth.ts:45
 
// Immediate fix
// Fixer removes line
// Re-validate
// Pass

// Issue found
Coverage at 65%, need 80%
 
// Iteration 1: Fixer adds tests for untested functions
// Coverage: 72%
 
// Iteration 2: Fixer adds edge case tests
// Coverage: 78%
 
// Iteration 3: Fixer adds integration tests
// Coverage: 82%
 
// Pass

// Issue found
Circular dependency detected
 
// Can't fix
// Create decision
 
// User answers
// Extract shared code
 
// Fixer implements
// Re-validate
// Pass

// Issue 1 found
Unused export in utils.ts
 
// Fixer removes export
// But now tests fail (they imported the export)
 
// Issue 2 found
Test failures
 
// Fixer removes dead tests
// But now coverage drops
 
// Issue 3 found
Coverage below 80%
 
// Fixer adds new tests
// Pass

# View what fixer is doing
tail -f .agentful/fixer.log
 
# Check recent fixes
cat .agentful/last-fix.json
 
# View fix history
cat .agentful/completion.json | jq '.fix_history'

{
  "timestamp": "2026-01-18T00:00:00Z",
  "fixed": [
    "Removed unused export: formatDate in src/utils/date.ts",
    "Deleted unused file: src/components/OldWidget.tsx",
    "Removed console.log from src/auth/login.ts:45"
  ],
  "remaining": [
    "Coverage at 78% (added tests, need 2 more%)"
  ],
  "blocked": []
}

{
  "auto_fix_rate": 0.85,  // 85% of issues auto-fixed
  "manual_decision_rate": 0.15,  // 15% need human input
  "avg_fix_iterations": 2.3,  // Average 2.3 loops to resolve
  "critical_fixes": 12,  // Number of critical issues fixed
  "quality_fixes": 45  // Number of quality issues fixed
}

# Check what's blocking
cat .agentful/last-review.json | jq '.mustFix'
 
# Check fix attempts
cat .agentful/last-fix.json | jq '.remaining'

# Always run tests after fixes
npm test
 
# Check git diff before commit
git diff
 
# If suspicious, reset and fix manually
git reset --hard HEAD

// Mark intentionally unused exports
// eslint-disable-next-line unused-imports/no-unused-vars
export { experimentalFeature } from './experimental';
 
// Or use barrel exports selectively
// public.ts - exports for external use
// internal.ts - exports for internal use only

# Restore from git
git log --find-renames --name-status  # Find deletion
git checkout <commit> -- path/to/file

# Daily review
git log --author="fixer" --since="1 day ago" --patch

// Bad: Giant decision
{
  "question": "How to refactor entire authentication system?"
}
 
// Good: Small decisions
{
  "question": "Use JWT or sessions?"
}
{
  "question": "Store tokens in localStorage or cookies?"
}

{
  "resolved": [
    {
      "id": "auth-001",
      "question": "JWT or sessions?",
      "answer": "JWT with httpOnly cookies",
      "reasoning": "Scalability for future microservices",
      "timestamp": "2026-01-18T00:00:00Z"
    }
  ]
}

## Custom Fix: Add Error Logging
 
When adding try/catch, also add logging:
 
```typescript
try {
  await operation();
} catch (error) {
  logger.error('Operation failed', { error });
  throw error;
}

 
### Recovery Hooks
 
Add custom recovery steps:
 
```markdown
## After Database Connection Failure
 
1. Check DATABASE_URL in .env
2. Test connection: npm run db:test
3. Run migrations: npm run db:migrate
4. Retry operation