# Instruction-Design Glossary

Use these terms when they clarify a discussion about agent instructions. They are concepts, not a requirement to avoid ordinary synonyms. [SKILL.md](SKILL.md) owns the workflow and Codex invocation mechanics.

## Discovery and cost

- **Predictability:** comparable situations lead to consistent, task-appropriate decisions.
- **Model-invoked:** available for automatic selection as well as explicit invocation.
- **User-invoked:** explicitly selected; an explicit-only policy disables automatic selection, not required metadata.
- **Description:** required frontmatter that summarizes capability and applicability; it is not the invocation-policy toggle.
- **Context pointer:** a reference plus the condition for reaching its target.
- **Context load:** tokens and attention spent on available metadata and loaded instructions.
- **Cognitive load:** what the human must remember or decide to use the system.
- **Router skill:** selects among genuinely distinct workflows or resources.
- **Granularity:** how finely instructions are divided; each split must justify its discovery and maintenance cost.

## Information hierarchy

- **Steps:** ordered actions where sequence matters to the task.
- **Reference:** definitions, constraints, or procedures consulted when relevant.
- **External reference:** material outside the entrypoint, reached through an appropriate pointer.
- **Information hierarchy:** the placement of essential actions and constraints versus conditional detail.
- **Progressive disclosure:** loading supporting detail only when the task needs it.
- **Co-location:** keeping a concept's definition, rules, and caveats together.
- **Branch:** a distinct case or mode handled by the skill.

## Execution and maintenance

- **Leading word:** a compact, familiar concept that conveys a useful decision principle without repeated explanation.
- **Completion criterion:** evidence that the requested outcome has been reached; it should be checkable and cover the important requirements.
- **Legwork:** investigation needed to meet that criterion rather than transferring discoverable work to the user.
- **Post-completion steps:** later actions that may distract from an unfinished prerequisite.
- **Premature completion:** declaring a step or task done without meeting its criterion. Clarify the criterion before adding process.
- **Negation:** wording framed around what to avoid. Prefer a clear positive target where possible while retaining necessary safety prohibitions.
- **Single source of truth:** one authoritative home for a rule or fact.
- **Duplication:** repeated meaning that must be maintained in several places.
- **Relevance:** whether material still supports the skill's actual task.
- **Sediment:** stale assumptions accumulated through updates.
- **Sprawl:** more instruction volume than the task usefully needs.
- **No-op:** wording that does not materially change the agent's decisions or work.