# Confidence Model Reference

> Machine-readable counterpart: `.ao/references/confidence-policy.yaml`

**Authority**: This document defines the canonical confidence levels used throughout AO workflows. All skills, agents, and prompts MUST reference these definitions.

## Confidence Levels

### LOW Confidence

**Definition**: Uncertainty about approach, requirements, or implementation. Limited prior experience with the domain or technology. Complex changes with significant risk of regressions.

**Triggers**:
- First-time implementation in unfamiliar codebase
- Requirements are unclear or ambiguous
- High-risk changes (security, data, core logic)
- Complex multi-system integration
- User explicitly marks as low confidence

**Workflow Constraints**:
| Aspect | Constraint |
|--------|------------|
| Batch size | **1 issue only** — no batching |
| Planning | **3+ iterations** required |
| Baseline | **MANDATORY** — must exist before implementation |
| Validation | **Tier 2+ only** — Tier 1 (quick) forbidden |
| Review | **Human-review hard gate** — cannot auto-close |
| Retrospective | **Mandatory** — must capture learnings |

**Behaviors**:
1. Focus-scan refuses to select more than 1 issue
2. Implementation stops if baseline is missing
3. Validation uses Tier 2 or Tier 3 depth
4. Critical review uses exhaustive depth
5. Agent STOPS and ASKS user before marking done

### NORMAL Confidence

**Definition**: Standard confidence for routine work. Familiar domain, clear requirements, moderate complexity. Default level when not specified.

**Triggers**:
- Routine maintenance or feature work
- Clear acceptance criteria exist
- Similar work completed successfully before
- Medium complexity changes
- Default when confidence not explicitly set

**Workflow Constraints**:
| Aspect | Constraint |
|--------|------------|
| Batch size | **Up to 3 issues** — user confirmation for >1 |
| Planning | **2 iterations** recommended |
| Baseline | **Recommended** — refresh if stale |
| Validation | **Tier 2 preferred** — Tier 1 acceptable for trivial parts |
| Review | **Standard depth** — human review recommended |
| Retrospective | **Recommended** — especially if surprises encountered |

**Behaviors**:
1. Focus-scan may select 2-3 related issues (with confirmation)
2. Implementation proceeds with standard validation
3. Review at standard depth
4. Agent can auto-close with user notification

### HIGH Confidence

**Definition**: High certainty about approach and outcome. Trivial changes, well-understood domain, minimal risk.

**Triggers**:
- Trivial changes (typos, formatting, comments)
- Well-documented procedures being followed
- Repeat of proven approach
- User explicitly marks as high confidence
- Quickfix path (automatically sets high)

**Workflow Constraints**:
| Aspect | Constraint |
|--------|------------|
| Batch size | **Up to 5 issues** — can bundle related work |
| Planning | **1 iteration** sufficient |
| Baseline | **Optional** — compare if exists |
| Validation | **Tier 1 acceptable** — but Tier 2 for code changes |
| Review | **Brief review** — spot-check sufficient |
| Retrospective | **Optional** — skip for truly trivial |

**Behaviors**:
1. Focus-scan can select up to 5 trivial issues
2. Can skip planning iterations for obvious work
3. Soft approval gates only
4. Agent can auto-close without explicit confirmation

---

## Confidence Transitions

Confidence can change during the workflow:

### Increasing Confidence
When outcomes are good (validation passes, no surprises), confidence MAY increase for next iteration:
- `low` → `normal` — if first iteration succeeded cleanly
- `normal` → `high` — if work is clearly repeatable

### Decreasing Confidence
When outcomes are bad (regressions, surprises), confidence MUST decrease:
- `high` → `normal` — if unexpected issues found
- `normal` → `low` — if significant regressions or blockers
- Any → `low` — if user expresses uncertainty

### Documenting Transitions
When confidence changes, update:
1. Issue metadata: `confidence: {new_level}`
2. Issue log: `- YYYY-MM-DD: Confidence changed {old}→{new} — {reason}`
3. focus.json: Include current confidence in active work section

---

## Where to Set Confidence

### Issue Creation
Use the `confidence:` field in issue frontmatter:
```yaml
id: FEAT-0001@abc123
title: "Implement feature"
confidence: low | normal | high
```

### Constitution Default
Project default confidence is set in `.agent/ops/constitution.md`:
```yaml
confidence:
  default: low | normal | high
```

### Override Hierarchy
1. Issue-level `confidence:` field (highest priority)
2. Constitution default
3. Skill/prompt default (lowest priority)

---

## Skills Referencing This Document

The following skills MUST use these canonical definitions:

- `ao-planning` — iteration count based on confidence
- `ao-task` — setting confidence when creating issues
- `ao-focus-scan` — batch limits based on confidence
- `ao-implementation` — baseline requirement based on confidence
- `ao-validation` — tier selection based on confidence
- `ao-retrospective` — mandatory vs optional based on confidence
- `ao-critical-review` — review depth based on confidence
- `ao-quickfix` — automatically sets high confidence

**Reference link**: `.ao/references/confidence.md`

---

## Protocol Priority (MANDATORY)

**Safety protocols ALWAYS override user convenience requests.**

This is non-negotiable. When there is a conflict between:
- What the user asks for (speed, autonomy, skipping steps)
- What the safety protocol requires (validation, review, hard stops)

**The safety protocol wins.**

### Priority Hierarchy

1. **HARD BLOCKS** — Cannot be overridden under any circumstances
   - LOW confidence batch size (max 1 issue)
   - LOW confidence auto-close (human review required)
   - Protected branch push (main, master, develop, next, release/*)
   - Security-sensitive file changes without human review

2. **SOFT BLOCKS** — Can be overridden with explicit keyword
   - Autonomous mode for LOW confidence (override: "OVERRIDE-LOW")
   - Skip validation for HIGH confidence (override: explain why)

3. **WARNINGS** — Logged but do not block
   - Stale baseline for HIGH confidence
   - Missing documentation for trivial changes

### Conflict Detection Reference

See `.ao/references/conflict-detection.md` for full conflict detection and resolution procedures.

### Enforcement in Skills

All skills MUST check for conflicts before executing user requests:

```
# At the start of any user-requested action:
conflicts = detect_conflicts(user_request, active_issues)

IF conflicts:
    FOR conflict IN conflicts:
        IF conflict.is_hard_block:
            REFUSE with explanation
        ELIF conflict.is_soft_block:
            PROMPT for override keyword
            IF override_provided:
                LOG override and proceed
            ELSE:
                WAIT for user decision
```

---

*Last updated: 2026-01-27*
