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.

Anti-patterns

• Redefining key paths, mixing table styles for one object, or skipping validation.

Failure mode

If the owning schema, value type, or validation command cannot be identified, stop and report the missing contract before editing.

Gotchas

• Quoting numeric values can silently change type semantics.

See Also

Topic map: [[agent-ops]]

References

• Deep guidance: references/deep-guidance.md