skill-intent-contract

# Intent Contract System

## Purpose

The intent contract creates a **persistent record of user intent** that:
- Captures what the user is trying to accomplish
- Defines success criteria upfront
- Establishes boundaries and constraints
- Travels through the entire workflow
- Validates final outputs against original intent

This closes the loop between intention and delivery.

---

## Intent Contract Structure

The intent contract is stored in `.claude/session-intent.md` and follows this format:

```markdown
# Intent Contract

**Created**: [ISO timestamp]
**Workflow**: [discover/embrace/review/etc.]
**Status**: [active/validating/completed]

## Job Statement
What the user is trying to accomplish (JTBD framework).

[User's goal in plain language]

## Success Criteria

### Good Enough
- [Minimum viable success criterion 1]
- [Minimum viable success criterion 2]

### Exceptional
- [Excellence criterion 1]
- [Excellence criterion 2]

## Boundaries
What this should NOT be:
- [Boundary 1: What to avoid]
- [Boundary 2: What's out of scope]

## Context & Constraints

**Stakeholders**: [Who needs this to work for them]
**Existing Assets**: [What to build on]
**Timeline**: [Time constraints if any]
**Technical Constraints**: [Platform, language, dependencies]

## Clarifying Context
[Any answers from the 3-question pattern]

## Task Allocation
**Risk**: [low | intermediate | high]
**Initiative**: [human | AI | shared] — who starts and proposes
**Control**: [human | AI | shared] — who oversees execution as it runs
**Decision rights**: [human | AI] — who has final say on the outcome
**AI role**: [none | executor | collaborator | challenger]
**Execution disposition**: [AI-assisted | human-only | pending-user-decision]
**Escalation decision**: [not-needed | pending | user's recorded resolution]
**Resolved AUTONOMY_MODE**: [supervised | semi-autonomous | loop-until-approved | autonomous | not-applicable (contract-only sentinel)]

## Validation Checklist
- [ ] Meets "good enough" criteria
- [ ] Respects all boundaries
- [ ] Works for all stakeholders
- [ ] Builds on existing assets appropriately
- [ ] Allocation still fits what the task turned out to be
```

---

## Implementation Instructions

### When to Create Intent Contract

Create an intent contract when:
- User invokes a major workflow (`/octo:embrace`, `/octo:discover`, `/octo:plan`)
- User explicitly asks to "plan" or "set goals" for a task
- A workflow requires multiple phases and validation

**Do NOT create for:**
- Quick, single-action commands
- Simple file reads or searches
- Conversational questions

### Step 0: Allocate the work before scoping it

Run this before capturing intent. The question is not how to run the task across
agents but whether it should be delegated at all, and if so, which parts of the
authority go where. Framework: Afroogh, Varshney & D'Cruz (2025), *A Task-Driven
Human-AI Collaboration* ([arXiv:2505.18422](https://arxiv.org/abs/2505.18422)).

**Classify risk.** Complexity is already scored elsewhere — defer to
`estimate_complexity` and `classify_cynefin` in `scripts/lib/routing.sh` rather
than re-deriving it. Risk is a separate axis that nothing in the codebase
measures, so judge it here on three questions:

- **Irreversibility** — can the effect be undone, and at what cost?
- **Consequence** — is anything material at stake: safety, money, data, users?
- **Accountability** — is a specific person expected to answer for the outcome?

| Risk | Reading |
|------|---------|
| **Low** | Reversible, no material consequence, no named accountability. |
| **Intermediate** | Reversible only at real cost, or consequence is unclear. |
| **High** | Irreversible, materially consequential, or someone must answer for it. |

**Allocate the three dimensions separately.** They are independent, and treating
them as one axis is the mistake this step exists to prevent. People readily hand
AI the *initiative* on unfamiliar work while keeping control and decision rights
— an allocation a single autonomy slider cannot express.

- **Initiative** — who starts, proposes, drafts.
- **Control** — who oversees execution while it runs.
- **Decision rights** — who has final say on the result.

Record every outcome explicitly:

| Risk / complexity | Initiative | Control | Decision rights | AI role | Execution disposition | Escalation decision | Mode |
|---|---|---|---|---|---|---|---|
| Low / low | AI | AI | AI | executor | AI-assisted | not-needed | `autonomous` |
| Low / high | shared | human | human | collaborator | AI-assisted | not-needed | `loop-until-approved` |
| High / low | human | human | human | executor | AI-assisted | not-needed | `supervised` |
| High / high | human | human | human | challenger | AI-assisted | not-needed | `supervised` |

The High / high allocation is adversarial: the human leads while AI attacks the
proposed decision as a deliberate counterweight to the human's own bias. In High /
low work, AI may execute only the bounded actions the human directly approves.

**The rule that inverts.** For **intermediate-risk** work where uncertainty is
highest, the cited evidence says avoid AI entirely — "neither as a gatekeeper nor
as a second opinion". This contradicts the smooth intuition that middling risk
implies middling involvement, and it also sits in tension with the same paper's
broader claim that complete human autonomy is rarely justified. That tension is
real and unresolved; surface it to the user and let them decide rather than
quietly picking a side.

**Resolve to a setting.** The workflow engine reads one variable,
`AUTONOMY_MODE`, with four values:

| Allocation | `AUTONOMY_MODE` |
|---|---|
| Human holds control and decision rights, approving each phase | `supervised` |
| AI runs; human is pulled in on failures and quality gates | `semi-autonomous` |
| AI runs and iterates; human holds final decision rights | `loop-until-approved` |
| AI holds all three | `autonomous` |

Record the three dimensions *and* the resolved