intent-confirmation

What this skill does

# Intent Confirmation

Structured intent disambiguation before executing non-trivial tasks. Gates on complexity tier from complexity-assessment. Makes branch, artifact, and approach decisions explicit before execution to prevent wrong-approach errors.

## Contextd Integration

If contextd MCP is available:
- `memory_record` to store confirmed intents for reference during execution
- `memory_search` to find past intent edits (user preferences)
- `memory_outcome` to track acceptance rate (accepted / edited / rejected)

If contextd is NOT available:
- Intent confirmation runs inline (still works)
- No persistence of intent decisions
- No preference learning across sessions

---

## When to Trigger

| Condition | Action |
|-----------|--------|
| complexity-assessment returns STANDARD (12-16) | Show intent preview, wait for confirmation |
| complexity-assessment returns COMPLEX (17-21) | Show detailed intent preview, require explicit "Yes" |
| complexity-assessment returns SIMPLE (7-11) | Auto-proceed, no confirmation needed |
| User request is ambiguous about branch, tool, or artifact type | Show intent preview regardless of tier |
| Before any multi-file modification | Show intent preview regardless of tier |
| User explicitly requests confirmation | Show intent preview regardless of tier |

**NEVER trigger for SIMPLE tasks unless ambiguity is detected.**

---

## Complexity Gating

### SIMPLE (Score 7-11)

- Auto-proceed with no confirmation
- No intent preview displayed
- Exception: show preview if user request is ambiguous

### STANDARD (Score 12-16)

- Show intent preview table
- Wait for user confirmation
- Accept "Yes", "Edit", or "I'll handle this"
- Proceed on "Yes" or after edits are confirmed

### COMPLEX (Score 17-21)

- Show detailed intent preview table with additional fields
- Require explicit "Yes" to proceed
- "Edit" loops back to preview with changes applied
- "I'll handle this" aborts automated execution

---

## Intent Preview Template

Present this table before execution:

```
## Intent Preview

| Aspect | Plan |
|--------|------|
| Goal | {one-line description of what will be accomplished} |
| Branch | {branch-name} (will create / exists) |
| Approach | {strategy description - how the goal will be achieved} |
| Files to create | {list of new files, or "None"} |
| Files to modify | {list of existing files to change, or "None"} |
| Artifact type | {skill / agent / command / hook / code / config} |
| Tests | {test strategy - what tests will be written/run} |
| Review | {consensus-review / single-agent / none} |

Proceed? [Yes / Edit / I'll handle this]
```

### Additional Fields for COMPLEX Tasks

For COMPLEX tier, add these rows to the preview:

| Aspect | Plan |
|--------|------|
| Decomposition | {subtask breakdown from complexity-assessment} |
| Worktree | {using worktree / inline} |
| Dependencies | {external services, APIs, or packages involved} |
| Risk factors | {key risks identified in complexity-assessment} |
| Estimated scope | {number of files, rough time estimate} |

---

## User Response Handling

### "Yes" - Proceed

- Record confirmed intent in contextd (if available)
- Begin execution following the stated plan
- Reference the intent during execution to stay on track

### "Edit" - Modify Plan

- Ask user which aspects to change
- Update the preview table with changes
- Re-present for confirmation
- Record the delta as a user preference in contextd

### "I'll handle this" - Abort

- Do not execute any changes
- Record the rejection in contextd (if available)
- Offer to assist with specific sub-tasks if asked

---

## Artifact Type Decision Matrix

Use this matrix to determine the default artifact type based on the request:

| Request Type | Default Artifact | Confirm If |
|-------------|-----------------|------------|
| "Add reusable behavior" | Skill | Always - skills are high-impact |
| "Create a one-time script" | Script | If the behavior could be a skill |
| "Add a new agent" | Agent | Always - agents are high-impact |
| "Fix a bug" | Code edit | Never - straightforward intent |
| "Add automation" | Hook | If the automation could be a skill |
| "Update configuration" | Config | If changes affect multiple environments |
| "Add a new command" | Command | Always - commands are user-facing |
| "Refactor code" | Code edit | If scope is unclear |
| "Add documentation" | Docs | Never - straightforward intent |

When the request is ambiguous between artifact types, present options:

```
AskUserQuestion(
  question: "This could be implemented as either a skill or a hook. Which fits better?",
  options: [
    "Skill - reusable across projects, referenced by LLM",
    "Hook - automatic, fires on specific lifecycle events",
    "Not sure - explain the trade-offs"
  ],
  allow_custom: true
)
```

---

## Wrong-Approach Recovery

If the user says "wrong approach", "stop", "that's not what I meant", or similar during execution:

### Step 1: Auto-Pause

Immediately stop the current operation. Do not continue writing or editing files.

### Step 2: Show State vs Intent

```
## Execution Paused

| Aspect | Confirmed Intent | Current State |
|--------|-----------------|---------------|
| Goal | {original goal} | {what has been done so far} |
| Branch | {intended branch} | {actual branch} |
| Files created | {planned} | {actually created} |
| Files modified | {planned} | {actually modified} |
| Divergence | {where execution diverged from intent} |
```

### Step 3: Offer Options

```
How would you like to proceed?

1. **Resume** - Continue from here with the original plan
2. **Re-plan** - Show a new intent preview with adjusted approach
3. **Abort** - Stop and revert changes (git checkout/reset)
```

### Step 4: Record Recovery

If contextd is available, record the recovery event:

```
mcp__contextd__memory_record(
  project_id: "<project>",
  title: "Wrong-approach recovery: <task summary>",
  content: JSON.stringify({
    original_intent: { <confirmed intent> },
    divergence_point: "<where it went wrong>",
    user_action: "resume|replan|abort",
    lesson: "<what to do differently next time>"
  }),
  outcome: "partial",
  tags: ["intent-confirmation", "wrong-approach", "recovery"]
)
```

---

## Decision Recording (Contextd)

### Record Confirmed Intent

```
mcp__contextd__memory_record(
  project_id: "<project>",
  title: "Intent confirmed: <goal summary>",
  content: JSON.stringify({
    goal: "<goal>",
    branch: "<branch>",
    approach: "<approach>",
    artifact_type: "<type>",
    files_create: [<list>],
    files_modify: [<list>],
    tests: "<strategy>",
    review: "<review type>",
    complexity_tier: "<SIMPLE|STANDARD|COMPLEX>",
    user_response: "accepted|edited|rejected"
  }),
  outcome: "success",
  tags: ["intent-confirmation", "<complexity-tier>", "<artifact-type>"]
)
```

### Record Intent Edits (User Preferences)

When user edits the intent preview, record what they changed:

```
mcp__contextd__memory_record(
  project_id: "<project>",
  title: "Intent preference: <what changed>",
  content: JSON.stringify({
    original: { <original plan> },
    edited: { <edited plan> },
    delta: "<what the user changed and why>"
  }),
  outcome: "success",
  tags: ["intent-confirmation", "preference", "<aspect-changed>"]
)
```

### Track Acceptance Rate

Over time, contextd accumulates data on:
- How often intents are accepted without edits
- Which aspects are most frequently edited
- Which artifact type decisions are overridden
- Whether wrong-approach events decrease over time

Search for patterns before presenting intent:

```
mcp__contextd__memory_search(
  project_id: "<project>",
  query: "intent preference <artifact-type>",
  tags: ["intent-confirmation", "preference"],
  limit: 5
)
```

Apply discovered preferences to pre-fill the intent preview more accurately.

---

## Integration with Other Skills

| Skill | Integration Point |
|-------|-------------------|
| `complexity-assessment` | Provides tier score that