YAML

Table of Contents

• When to use
• Required inputs
• Deliverables
• Philosophy
• Procedure
• YAML Guidelines
• Editing Rules
• Validation
• Constraints
• Anti-patterns
• Failure mode
• Gotchas
• References

When to use

• Use for YAML authoring, review, or schema-safe fixes.
• Inputs: target files, consumer tool, required keys, and formatting conventions.
• Deliver valid YAML with stable indentation, key ordering, and scalar notes.

Required inputs

• Target YAML file path and consuming tool or schema.
• Required keys, scalar expectations, and formatting conventions.
• Validation command or parser expected to consume the file.

Deliverables

• Minimal YAML edit preserving meaningful ordering and comments.
• Validation evidence from parser, schema, or consuming tool.
• Notes for indentation, scalar coercion, or compatibility risk.

Philosophy

• Prefer schema truth and low-churn edits over clever rewrites.

Procedure

1. Confirm the consumer schema and current key paths.
2. Make the smallest compatible edit.
3. Validate before closeout.

YAML Guidelines

• Use spaces only; never use tabs for indentation.
• Keep indentation width consistent within a file.
• Quote values that could be misread as booleans, numbers, dates, or null.
• Prefer block style for complex mappings and sequences.

Editing Rules

• Minimize whitespace-only churn unless formatting is the task.
• Preserve key order when downstream tooling expects logical ordering.
• Avoid mixing flow style with block style in the same section.

Validation

• Run the relevant parser/schema/tool checks for touched files.
• Fail fast: stop at the first failed gate and report exact blocker evidence.

Constraints

• If schema compatibility is uncertain, stop and confirm constraints.
• Redact secrets and do not run destructive or network commands unless explicitly approved.

Anti-patterns

• Reindenting unrelated sections, changing scalar meaning, or skipping validation.

Failure mode

If the consuming schema, scalar expectations, or validation command cannot be identified, stop and report the missing contract before editing.

Gotchas

• Unquoted values like on, off, or no may coerce unexpectedly.

See Also

Topic map: [[agent-ops]]

References

• Deep guidance: references/deep-guidance.md