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.