mthds-fix

name	mthds-fix
description	Fix issues in MTHDS bundles. Use when user says "fix this workflow", "fix this method", "repair validation errors", "the pipeline is broken", "fix the .mthds file", after /mthds-check found issues, or when validation reports errors. Automatically applies fixes and re-validates in a loop.
min_mthds_version	0.17.0
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]

Fix MTHDS bundles

Automatically fix issues in MTHDS method bundles.

Process

Do not write .mthds files manually, do not do any other work. The CLI is required for validation, formatting, and execution — without it the output will be broken.

No backend setup needed: This skill works without configuring inference backends or API keys. You can start building/validating methods right away.

Step 1: Validate and Identify Errors

Always use -L pointing to the bundle's own directory to avoid namespace collisions:

mthds-agent validate bundle <file>.mthds -L <bundle-directory>/

Parse the JSON output:

• If success: true — nothing to fix, report clean status
• If error_type: "ValidateBundleError" — iterate through validation_errors array and fix each (Step 2)
• If model/config error — see Error Handling Reference (cannot be fixed by editing the .mthds file)

Step 2: Fix .mthds Validation Errors

Use the error_type field from each validation error to determine the fix:

Error Type	Fix Strategy
missing_input_variable	Add the missing variable(s) to the parent pipe's inputs line
extraneous_input_variable	Remove the unused variable(s) from the pipe's inputs line
input_stuff_spec_mismatch	Correct the concept type in inputs to match what the sub-pipe expects
inadequate_output_concept	Change the output field to the correct concept type
inadequate_output_multiplicity	Add or remove [] from the output concept
circular_dependency_error	Restructure the method to break the cycle
llm_output_cannot_be_image	Use PipeImgGen instead of PipeLLM for image generation
invalid_pipe_code_syntax	Rename the pipe to valid snake_case
unknown_concept	Add the concept definition to the bundle, or fix the typo
batch_item_name_collision	Rename input_item_name (or batch_as) to a distinct singular form of the list name. Also update the branch pipe's inputs to use the new item name.

For error type descriptions, see Error Handling — Validation Error Types.

Step 3: Fix TOML Formatting Issues

After applying semantic fixes, run mthds-agent plxt lint <file>.mthds as a quick TOML/schema correctness check. If lint passes, run mthds-agent plxt fmt <file>.mthds to auto-format the file before re-validating semantically in the next step.

Beyond what plxt catches, watch for these common issues:

Multi-line inputs — must be on a single line:

# WRONG
inputs = {
    a = "A",
    b = "B"
}

# CORRECT
inputs = { a = "A", b = "B" }

Pipe ordering — controllers before sub-pipes:

# CORRECT: main pipe first, then sub-pipes in execution order
[pipe.main_workflow]
type = "PipeSequence"
steps = [
    { pipe = "step_one", result = "intermediate" },
    { pipe = "step_two", result = "final" }
]

[pipe.step_one]
...

[pipe.step_two]
...

Missing required fields — add with sensible defaults:

• description on every pipe and concept
• type on every pipe
• output on every pipe

Step 4: Re-validate

After applying fixes, re-validate:

mthds-agent validate bundle <file>.mthds -L <bundle-directory>/

Continue the fix-validate loop until success: true is returned. Some fixes reveal new issues — for example, fixing a missing_input_variable may expose an input_stuff_spec_mismatch on the newly added input.

On the final successful validation, re-run with --graph to generate a flowchart:

mthds-agent validate bundle <file>.mthds -L <bundle-directory>/ --graph

Step 5: Report Results

• List all changes made (which pipes were modified and how)
• Show the final validation result
• Flag any remaining warnings or suggestions
• Mention the generated dry_run.html flowchart next to the bundle

Reference

• Error Handling — read when CLI returns an error to determine recovery
• MTHDS Agent Guide — read for CLI command syntax or output format details
• MTHDS Language Reference — read when writing or modifying .mthds TOML syntax
• Native Content Types — read when fixing type mismatches involving native concepts, to verify available attributes

---

Method summary (on request only)

After fixing the errors, do not volunteer a recap of what changed — no updated pipeline-flow diagram, no list of modified pipes, no prompt-by-prompt narration. The platform renders the method visually, so a written summary here is redundant noise.

Confirm completion in one line (e.g. "Fixed <name> — now valid."). Never hide problems: still surface any remaining errors or warnings plainly.

Give the full summary (flow + what changed) only when the user explicitly asks — "explain it", "summarize", "what changed", "walk me through".