adaptive-formalization

name	adaptive-formalization
description	Use when designing or changing AI/Agent-native product entities, schemas, database models, JSON schemas, DTOs, events, workspace artifacts, memories, profiles, plans, evaluations, or agent outputs; guides Codex to choose the right degree of formalization and freedom instead of defaulting to either rigid schema or unbounded text.
metadata	{"short-description":"Choose the right formalization level for AI-native entities"}

Adaptive Formalization

Use this skill to guide representation design in AI/Agent-native software systems. The goal is not to avoid schemas. The goal is to choose the degree of formalization that fits the entity's current product role, evidence maturity, consumer needs, and risk.

Core principle:

Choose the right degree of formalization for the entity's current product role. Preserve Agent semantic freedom where it creates product value, and add structure where system boundaries, consumers, validation, or auditability require it.

When To Use

Use this skill before creating or materially changing any durable representation such as:

• DB table, ORM model, API DTO, JSON schema, protobuf, event, config schema, state machine, enum, or validation rule.
• Agent workspace object such as profile, memory, plan, portfolio entry, mailbox item, reflection, evidence note, evaluation artifact, or semantic projection.
• Agent output format that may later become UI state, platform truth, workflow input, or cross-service contract.

Do not use it for routine internal refactors where no product entity or representation boundary changes.

Formalization Gradient

Treat schema objects and Agent artifacts as points on a gradient, not as opposing categories:

Level	Name	Use When
F0	Raw semantic note	The entity is exploratory, local, temporary, or mainly for Agent thinking.
F1	Guided semantic artifact	The entity needs light metadata, evidence links, uncertainty, or lifecycle hints while preserving natural language body.
F2	Semi-structured projection	The entity is consumed by a UI, workflow, or another Agent, but semantics are still evolving.
F3	Contracted schema object	The entity has stable consumers, repeatable fields, tests, versioning, and migration expectations.
F4	Audited platform truth	The entity affects authorization, submission, delivery, formal evaluation, billing, compliance, or irreversible user-visible state.

Prefer the lowest level that satisfies current product boundaries. Raise the level when risk, consumers, or evidence justify it. Lower the level when a schema compresses meaning, hides uncertainty, or narrows the Agent capability prematurely.

Decision Workflow

1. Name the entity. State what Codex is about to create or change.
2. Identify product role. Is it for Agent thinking, user-facing projection, workflow coordination, cross-service contract, or platform truth?
3. Map consumers. List current and near-term consumers: Agent only, UI, API, scheduler, evaluator, human reviewer, external system.
4. Assess evidence maturity. Use real scenarios, outputs, traces, examples, source refs, or repeated product behavior. Do not treat mock-only flows as product evidence.
5. Choose freedom level. Pick F0-F4 using the gradient. If uncertain, choose a higher-freedom representation with explicit promotion criteria.
6. Design representation. Define only the constraints required at that level.
7. Define evolution path. Add promotion criteria, demotion triggers, mutation rules, and validation loop.
8. Bind to capability evidence. For Agent-facing work, require a capability evidence pack before declaring the design product-complete.

Representation Decision

When this skill triggers, include a concise decision record before implementing representation changes:

Representation Decision
- Entity:
- Product role:
- Current maturity:
- Primary consumers:
- Truth status:
- Recommended freedom level:
- Recommended representation:
- Required evidence:
- Allowed mutations:
- Promotion path:
- Demotion trigger:
- Validation loop:

Keep the decision short. It should guide implementation, not become a design essay.

Default Patterns

• Agent reasoning, observations, hypotheses, drafts, reflections, and candidate profiles usually start as F1 guided semantic artifacts.
• UI previews and read models usually fit F2 until field stability is proven by repeated real scenarios.
• Durable APIs, shared event contracts, and persisted workflow state usually require F3.
• Authorization, formal submissions, evaluation decisions, delivery records, and audit logs require F4.
• If a field represents uncertainty, disagreement, weak evidence, or interpretive judgment, preserve sourceRefs, confidence, unresolved questions, or review status instead of collapsing it to a bare enum or boolean.

References

Load these only when needed:

• references/decision-rubric.md: detailed signals for F0-F4 decisions.
• references/optimization-controls.md: objective, loss, reward, and tuning heuristics.
• references/capability-evidence-pack.md: template for validating real Agent capability loops.