# Learn Mode

Use Learn Mode when a material widget, flow, protocol, or API behavior does not map confidently to CARBON’s library, or when the user explicitly asks CARBON to learn or discover the product.

## Entry and exit

Enter Learn Mode when:

- no existing item or flow matches with confidence `0.75` or greater;
- the visible label hides custom behavior, such as a canvas control, compound picker, bespoke editor, or multi-step state machine;
- an API lacks a reliable contract, has polymorphic behavior, or exposes unfamiliar authentication, pagination, streaming, or job semantics;
- selected library tests need an oracle that cannot be inferred safely from code or specifications.

Announce the target, learning budget, isolation boundary, and actions CARBON may take. A normal Quick or Medium run may spend a bounded discovery slice in Learn Mode; do not let open-ended exploration consume the whole run.

Exit when the surface’s states, transitions, inputs, observable outputs, failure/recovery behavior, and remaining unknowns are sufficient to create decisive tests; when additional probes stop changing the model; or when the next probe crosses an authorization or side-effect boundary.

## Learning loop

1. Create a durable session with `scripts/carbon_learn.py init`.
2. Inventory without mutation: labels, roles, accessible names, DOM or rendered structure, navigation, network calls, source contracts, API descriptions, and existing examples.
3. Form the smallest discriminating hypothesis about what the surface does.
4. Choose one reversible probe that separates competing hypotheses.
5. Record state before, action/request shape, state after/response shape, evidence, and uncertainty with `observe`.
6. Record candidate behavior with `hypothesize`; resolve it only after direct evidence.
7. Vary one dimension at a time: valid value, empty/null, exact boundary, malformed value, retry, cancellation, role/state, transport, or recovery.
8. When a new flow is discovered, read [learn-flow-generation.md](learn-flow-generation.md), model its states, transitions, inputs, actors, effects, and cleanup, then run `generate-flow` to automatically create test data and candidate cases.
9. Promote supported hypotheses into target-specific test definitions with `promote`.
10. Complete the session with explicit unknowns, unsafe untried transitions, staleness anchors, and a recommended next run size.

Do not call a convention a product requirement. Distinguish:

- **Observed behavior:** the target did it during this session.
- **Supported contract:** multiple observations or source/spec plus runtime agree.
- **Working hypothesis:** plausible and useful, but not yet decisive.
- **Unknown:** evidence conflicts or the safe learning budget ended.

## Persistence and reuse

Write sessions beneath `<state-root>/.carbon/learning/<session-id>/`:

- `learn.json`: durable current learning model;
- `events.jsonl`: append-only observations and decisions;
- `learned-tests.json`: promoted tests plus automatically generated flow candidates in normal test-plan shape;
- `report.html`: clickable self-refreshing learning report.

Before a later plan, search the target’s `.carbon/learning/` sessions. Reuse a learned test only when its target, environment, identity/role, relevant revision or contract fingerprint, and staleness anchors still apply. Re-observe at least one anchor behavior before treating old learning as current. Mark stale knowledge as a hypothesis, never a pass.

Keep learned knowledge target-specific by default. Update CARBON’s shared item/flow library only when the user explicitly asks, the behavior generalizes beyond one product, and the new cases have stable evidence.

## Safety

Use the isolated browser, API, credential, synthetic-data, and destructive boundaries in [execution-and-safety.md](execution/execution-and-safety.md).

Safe default learning actions include read-only navigation, opening and closing reversible UI, entering synthetic data without committing, inspecting accessibility and network metadata, bounded `GET`/`HEAD`/documented safe requests, and canceling before an external side effect.

Stop before payment/order commits, real notifications, destructive actions, privilege changes, production/shared-data mutation, unbounded crawling or load, undocumented non-idempotent API calls, or any step whose rollback is uncertain. Preserve the hypothesis as planned and name the required authorization.
