Name

ai-dlc:fail - Return to the previous hat in the AI-DLC workflow.

Synopsis

code

/fail

Description

Internal command - Called by the AI during /construct, not directly by users.

Goes back to the previous hat in the workflow. Typically used when:

•Reviewer finds issues -> return to builder
•Builder hits fundamental blocker -> return to planner
•Planner realizes requirements unclear -> return to elaborator

If already at the first hat (elaborator by default), this command is blocked.

Implementation

Step 1: Load Current State

bash

# Intent-level state is stored on current branch (intent branch)
STATE=$(han keep load iteration.json --quiet)

Step 2: Determine Previous Hat

javascript

const workflow = state.workflow || ["elaborator", "planner", "builder", "reviewer"];
const currentIndex = workflow.indexOf(state.hat);
const prevIndex = currentIndex - 1;

if (prevIndex < 0) {
  // Already at first hat - cannot go back
  return "Cannot fail before the first hat (elaborator).";
}

const prevHat = workflow[prevIndex];

Step 3: Document Why

Before updating state, save the reason for failing:

bash

# Append to blockers (unit-level state - saved to current branch)
REASON="Reviewer found issues: [describe issues]"
han keep save blockers.md "$REASON"

Step 4: Update State

bash

# Update hat to previous hat
# Intent-level state saved to current branch (intent branch)
# state.hat = prevHat
han keep save iteration.json '<updated JSON with hat set to previous>'

Step 4b: Re-spawn Teammate (Agent Teams)

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is enabled and a reviewer rejects work:

bash

AGENT_TEAMS_ENABLED="${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}"

If AGENT_TEAMS_ENABLED is set:

•Read unitStates from iteration.json
•Increment unitStates.{currentUnit}.retries
•
Check retry limit:
- •If retries >= 3: Mark unit as blocked, save blocker documentation
- •If retries < 3: Update unitStates.{currentUnit}.hat = "builder"
•Spawn new builder teammate with reviewer feedback:

javascript

Task({
  subagent_type: getAgentForDiscipline(unit.discipline),
  description: `builder (retry): ${unitName}`,
  name: `builder-${unitSlug}-retry${retries}`,
  team_name: `ai-dlc-${intentSlug}`,
  mode: modeToAgentTeamsMode(intentMode),
  prompt: `
    Re-execute the builder role for unit ${unitName}.

    ## Reviewer Feedback
    ${reviewerFeedback}

    ## Retry ${retries}/3
    Address the reviewer's feedback and fix the identified issues.
    ...same worktree and criteria context...
  `
})

•Save updated unitStates to iteration.json

Without Agent Teams: The existing behavior (update hat to previous, continue in sequential loop) remains unchanged.

Step 5: Confirm

Output:

code

Returning to **{prevHat}** hat.

**Reason:** {reason}

Continuing construction with the previous hat...

Guard

If already at the first hat (elaborator by default), output:

code

You are at the first hat (elaborator).

Cannot go back further. Continue elaboration or use `/reset` to start over.