Troubleshooting Guide

# 1. Check agentful state
/agentful-status
 
# 2. Check validation status
/agentful-validate
 
# 3. Check for decisions
cat .agentful/decisions.json
 
# 4. Check for TypeScript errors
npx tsc --noEmit
 
# 5. Check tests
npm test

Running iteration 25...
Working on: User authentication
No changes in last 10 iterations

# Check what's happening
/agentful-status
 
# Check state file
cat .agentful/state.json
 
# Check if decisions are blocking
cat .agentful/decisions.json | jq '.pending'

{
  "pending": [
    {
      "id": "decision-003",
      "question": "Should auth use JWT or sessions?",
      "blocking": ["authentication", "user-profile"]
    }
  ]
}

/agentful-decide
 
# Provide your answer:
Option 1: JWT (stateless, scalable)

# Check last validation
cat .agentful/last-validation.json
 
# Check what's failing
jq '.checks | to_entries[] | select(.value.passed == false)'

// Export is marked unused, but it IS used
export function utilityFunction() { ... }
 
// ts-prune says unused, but dynamic import uses it:
const module = await import('./utils');
module.utilityFunction();

**Technical Notes**:
- utilityFunction in src/utils/index.ts is dynamically imported
- Ignore dead code warnings for this function

## Dead Code Whitelist
- src/utils/index.ts:utilityFunction (dynamically imported)

Coverage at 72%, needs 80%
Coverage at 75%, needs 80%
Coverage at 77%, needs 80%
[Stuck here]

npm test -- --coverage --reporters=json
# Check coverage report for uncovered files

# Let agentful handle easy tests, you write complex ones
# Then re-run:
/agentful-validate

### 6. Coverage Check
 
**FAIL if:** Coverage < 70%  # Temporarily lowered

// Error: Property 'userId' does not exist on type 'Session'
const userId = session.userId;

npx tsc --noEmit
 
# Output:
src/app/api/auth/route.ts:15:25 - error TS2339:
Property 'userId' does not exist on type 'Session'.

// Add missing property
interface Session {
  userId: string;
  token: string;
}

/agentful-start

# See what agentful is trying to understand
# Look in conversation history for:
# "Reading PRODUCT.md..."
# "Analyzing feature X..."
# "Need clarification on..."

# Before (vague)
### 3. User Profile - HIGH
Users can see their profile.
 
# After (specific)
### 3. User Profile - HIGH
**Description**: Users can view and edit their profile information
 
**Acceptance Criteria**:
- [ ] Display user name, email, avatar
- [ ] Edit form for name and avatar URL
- [ ] Email is read-only (can't change)
- [ ] Save button updates user in database
- [ ] Cancel button reverts changes

Feature complete: User authentication (100%)
[agentful exits]

# Check completion
cat .agentful/completion.json
 
# Check state
cat .agentful/state.json

/ralph-loop "/agentful-start" --max-iterations 50

/ralph-loop "/agentful-start" --max-iterations 100

/ralph-loop "/agentful-start"

# Edit .agentful/completion.json
# Change feature status from "complete" to "in_progress"
# Then resume:
/agentful-start

Test: User login
  Expected: 200 status
  Received: 401 status
  ❌ FAIL

# Run tests manually to see full output
npm test
 
# Check test file
cat src/__tests__/auth.test.ts

// Test expects:
expect(response.status).toBe(200);
 
// But code returns:
return NextResponse.json({ error: "Unauthorized" }, { status: 401 });

**Technical Notes**:
- Regenerate all tests for this feature to match current implementation

// Test expects:
const user = await createUser({ email: "test@example.com" });
 
// But createUser not mocked or doesn't exist

beforeEach(async () => {
  await setupTestData();
});
 
afterEach(async () => {
  await cleanupTestData();
});

// Wrong (missing await):
act(() => {
  render(<Login />);
});
expect(screen.getByText("Welcome")).toBeInTheDocument();
 
// Correct:
await act(async () => {
  render(<Login />);
});
expect(await screen.findByText("Welcome")).toBeInTheDocument();

error TS2322: Type 'string' is not assignable to type 'number'

npx tsc --noEmit

// Function expects number, receives string
function setId(id: number) { ... }
setId("123");  // Error: string not assignable to number

setId(parseInt("123"));
// OR update function to accept string
function setId(id: string | number) { ... }

// Using library without types
import { someLibrary } from 'untyped-library';
 
// Error: Could not find namespace for someLibrary

npm install --save-dev @types/untyped-library

declare module 'untyped-library';

// Might be undefined
const user = users.find(id);
 
// Error: Object is possibly 'undefined'
console.log(user.name);

const user = users.find(id);
if (!user) {
  throw new Error("User not found");
}
console.log(user.name);

Unused export: validateEmail in src/utils/auth.ts
But export IS used!

# Check where it's used
grep -r "validateEmail" src/
 
# Might be dynamically imported
# Or used in way tool can't detect

// Export seems unused
export function validateEmail() { ... }
 
// But imported dynamically
const module = await import('./auth');
module.validateEmail();

// Used dynamically - don't remove
export function validateEmail() { ... }

// Function not called, but has side effects when imported
export function setupLogging() {
  configureGlobalLogger();
}
 
// Import triggers side effects
import './utils/logging';

// Side effect - don't remove
export function _setupLogging() { ... }

# Check what's taking time
# Look for repeated operations:
# - Running tests many times
# - Reading same files repeatedly
# - Checking dead code over and over

# In .claude/agents/orchestrator.md
 
## Search Scope
Only search these directories:
- src/
- tests/
 
Ignore:
- node_modules/
- .next/
- build/
- dist/
- public/

# Quick test mode during agentful runs
npm test -- --passWithNoTests --maxWorkers=4
 
# Full test suite only on final validation
npm test -- --coverage

# Skip dead code check during iteration
# Only run on final validation
 
# In reviewer.md, comment out:
# ### 3. Dead Code Detection

# In agent instructions:
 
## File Reading Limits
- Only read files directly related to current task
- Don't read entire directories at once
- Use Glob to find files, Read only what's needed
- Limit file size: skip files > 10KB unless necessary

# Let context flush
# Exit and restart every 20-30 iterations

cat .agentful/state.json
# Parse error: Invalid JSON

# Check git history
git log .agentful/state.json
 
# Restore last good version
git checkout abc123 -- .agentful/state.json
 
# OR reset to initial state
rm .agentful/state.json
/agentful-start  # Will recreate file

Feature complete, but state.json still shows "in_progress"

# Edit .agentful/completion.json
{
  "features": {
    "authentication": {
      "status": "complete",  # Change from "in_progress"
      "score": 100
    }
  }
}

git pull
CONFLICT (content): Merge conflict in .agentful/state.json

# Decide which state to keep
# Usually: Keep local (your work takes precedence)
 
git checkout --ours .agentful/state.json
git add .agentful/state.json
git commit
 
# Or for remote changes
git checkout --theirs .agentful/state.json
git add .agentful/state.json
git commit

Error: process.env.DATABASE_URL is undefined

DATABASE_URL="postgresql://..."
NEXT_PUBLIC_API_URL="https://..."

## Environment Variables Required
 
- `DATABASE_URL` - PostgreSQL connection string
- `NEXT_PUBLIC_API_URL` - API base URL
- `JWT_SECRET` - Secret for token signing

### 1. User Management - CRITICAL
Users can manage their accounts.
 
# agentful might build:
# - Account creation
# - Profile editing
# - Account deletion
 
# But you wanted:
# - Login/Logout only

### 1. User Authentication - CRITICAL
**Description**: Users can login and logout
 
**Acceptance Criteria**:
- [ ] Login form with email/password
- [ ] JWT token generation
- [ ] Logout functionality
- [ ] Protected routes
 
**Out of Scope**:
- User registration (use admin panel)
- Profile editing (feature #2)
- Account deletion (feature #3)

// Human-modified: Added custom error handling for edge case
// Date: 2026-01-18
// Reason: Needed to handle malformed responses from API
// Do not modify without consulting team
 
function handleApiResponse(response: Response) {
  // Custom logic here...
}

**Technical Notes**:
- src/app/api/handler.ts has custom error handling
- Do NOT modify the try/catch block (lines 25-40)
- Build around it

cat .agentful/completion.json

# Mark complete manually
# Edit .agentful/completion.json:
{
  "overall": 100,
  "features": {
    "all": "complete"
  }
}
 
# Then stop agentful
# Don't let it continue looping

# 1. Backup current work
cp -r .agentful .agentful.backup
git add .
git commit -m "Backup before reset"
 
# 2. Remove agentful state
rm -rf .agentful/
 
# 3. Start fresh
/agentful-start
 
# agentful will re-analyze PRODUCT.md and start over

# 1. Find last good commit
git log --oneline
 
# 2. Reset to that commit
git reset abc123 --hard
 
# 3. Remove bad state
rm -rf .agentful/
 
# 4. Restart from good point
/agentful-start

# 1. Stop agentful
# Let it finish current task, then exit
 
# 2. Complete feature yourself
# Write remaining code, tests, etc.
 
# 3. Update completion.json
{
  "features": {
    "your-feature": {
      "status": "complete",
      "score": 100,
      "completedManually": true
    }
  }
}
 
# 4. Validate
/agentful-validate
 
# 5. Resume agentful for next feature
/agentful-start

## agentful Issue Report
 
### What I was doing
Running `/agentful-start` on authentication feature
 
### What happened
agentful entered validation loop, stuck at 78% coverage
 
### Steps to reproduce
1. Run `/agentful-start`
2. Wait for authentication feature
3. Coverage stuck at 78%
 
### Environment
- Node.js: v20
- Framework: Next.js 14
- Database: PostgreSQL + Prisma
- Testing: Vitest
 
### State files
[Attach .agentful/state.json, completion.json, last-validation.json]
 
### PRODUCT.md
[Attach relevant feature section]
 
### Error logs
[Paste relevant errors]