Handling Blocked Tasks

How to help Claude when it gets stuck

Handling Blocked Tasks

Sometimes Claude needs your help to continue. This is the "human in the loop" feature that makes Clotion practical for real development work.

When Does Claude Get Blocked?

Claude will pause and ask for help when:

• Missing information - The task description is unclear
• Access issues - Can't access a file or resource
• Design decisions - Multiple valid approaches exist
• Permission errors - Needs credentials or API keys
• Ambiguous requirements - Needs clarification

How It Works

1. Claude Detects a Blocker

When Claude encounters an issue, it outputs:

BLOCKED: Need clarification on the authentication flow.
Should we use JWT tokens or session cookies?

2. Clotion Updates Notion

Your Notion card is updated:

• Blocked checkbox → ✓ (checked)
• Current Status → The blocking reason
• Card appears highlighted/red if you have conditional formatting

3. You Respond

Add a comment to the Notion card with your guidance:

Use JWT tokens. Store them in httpOnly cookies for security. The refresh token endpoint is at /api/auth/refresh.

4. Claude Resumes

Clotion detects your comment and:

1. Sends your response to Claude
2. Claude continues the task
3. Blocked checkbox is unchecked
4. Current Status updates to "Resuming..."

Best Practices

Writing Good Unblock Responses

Be specific:

Use the existing UserService class in src/services/user.ts.
The createUser method should validate email format.

Provide examples:

Follow the pattern in src/api/products.ts for the new endpoint.
Error responses should use the format: { error: string, code: number }

Reference files:

See the auth flow in docs/AUTHENTICATION.md for context.
Use the same approach as the login endpoint.

What to Avoid

• Vague responses like "make it work" or "figure it out"
• Changing requirements mid-task
• Referencing external docs without summarizing

Visual Indicators

Set up your Notion database to highlight blocked tasks:

1. Click ... → Properties
2. Click on Blocked property
3. Enable Highlight when checked

Now blocked cards will have a red indicator, making them easy to spot.

Automatic Detection

Clotion detects blocks through keyword matching:

• BLOCKED:
• I need clarification
• I cannot proceed
• permission denied
• missing information

Claude is trained to use these phrases when stuck.

Timeout Handling

If you don't respond within the timeout period (default: 1 hour):

1. Task enters FAILED state
2. Comment posted with timeout message
3. Worktree preserved for debugging

To adjust the timeout:

BLOCKED_TIMEOUT=7200  # 2 hours

Monitoring Blocked Tasks

In Notion

Create a filtered view:

1. Add new view → Table or Board
2. Filter: Blocked is checked
3. Sort: By last edited (newest first)

From Command Line

Check blocked tasks:

clotion status --blocked

Output:

Blocked Tasks:
  CLO-123: Add user authentication (blocked 15m ago)
           Reason: Need API endpoint specification

Manual Unblocking

If the polling misses your comment:

clotion unblock CLO-123

This forces Clotion to check for new comments and resume.

Multiple Blocked Tasks

If several tasks get blocked:

1. Each appears with Blocked checkbox checked
2. Handle them in any order
3. Comment on each card individually
4. Claude resumes each as you respond

Tasks don't block each other - other non-blocked tasks continue running.