Documentation First

Documentation First

Use this skill to turn ambiguous work into durable, executable context before implementation.

Workflow

1. Identify whether the task is trivial. If it is trivial, do not create ceremony.
2. Read ~/.codex/standards/agent-native-standard.md when the work affects coordination, memory, delegation, tests, or delivery.
3. Read ~/.codex/standards/engineering-standard.md when the work affects architecture, schemas, APIs, data, security, observability, or TypeScript/Effect boundaries.
4. Use the repository's existing doc convention. If none exists, create the smallest fitting artifact:
   • docs/adr/NNNN-kebab-title.md for architectural, stack, product, data, security, or operational decisions.
   • docs/specs/YYYY-MM-DD-kebab-feature.md for feature or workflow specifications.
   • Tests, schemas, fixtures, OpenAPI, tool contracts, or evals when executable documentation is clearer than prose.
5. Keep the artifact short enough to guide implementation, not replace it.

Required Content

Include only sections that change implementation quality:

• Goal and non-goals
• Domain vocabulary and invariants
• Contracts, schemas, tools, APIs, events, and permissions
• State, persistence, migrations, failure modes, observability, rollout, and recovery
• Acceptance criteria and validation plan
• Decision, alternatives, and consequences for ADRs

Rules

• Prefer machine-readable contracts over duplicated prose.
• Do not create parallel sources of truth.
• Do not document obvious code behavior.
• Use the document to brief subagents; it must stand without hidden conversation context.