toml

Table of Contents

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

When to use

• Use for TOML config creation, review, or schema-safe fixes.
• Inputs: target files, owning tool, expected key paths, and compatibility constraints.
• Deliver valid TOML with minimal key-path churn and notes for schema-impacting edits.

Required inputs

• Target TOML file path and owning tool or schema.
• Intended key paths, value types, and compatibility constraints.
• Validation command or parser expected to consume the file.

Deliverables

• Minimal TOML edit preserving existing comments and order where possible.
• Validation evidence from parser, schema, or owning tool.
• Notes for any type, key-path, 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.

TOML Guidelines

• Preserve key order where tool owners expect readability.
• Prefer explicit scalars and arrays over ambiguous shapes.
• Keep one responsibility per table and use dotted keys consistently.
• Do not mix inline tables and expanded tables for the same object path.

Editing Rules

• Change only the smallest required key path.
• Retain existing comments unless provably outdated.
• Keep trailing commas out of arrays and inline tables.

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 ownership is unclear, pause before adding keys.
• Redact secrets and do not run destructive or network commands unless explicitly approved.