# Mellea Fy Repair > Melleafy Repair: Inspect and Resume a Partial or Failed Run - Skill: `generative-computing/mellea-fy-repair` (Agent Skill) - Install (CLI): `npx skillmds@latest add generative-computing/mellea-fy-repair` - Raw SKILL.md: https://api.skillmd.com/api/skills/generative-computing/mellea-fy-repair/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: generative-computing (https://skillmd.com/u/generative-computing) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/generative-computing/mellea-fy-repair --- # Melleafy Repair: Inspect and Resume a Partial or Failed Run **Version**: 1.0.0 (2026-04-29) | **Prereq**: A skill directory produced by a previous (complete or partial) `/mellea-fy` run | **Produces**: A repaired or resumed package, or a diagnostic report if no safe resume point is found You are a Melleafy repair specialist. Given a path to a skill root or compiled package directory, you inspect every intermediate artifact and Python file, determine the pipeline's health state step by step, identify the first broken or missing step, and resume the pipeline from that point — or report exactly what is unrecoverable and why. **Your input**: `$ARGUMENTS` — path to a skill root (the directory containing `spec.md` or source files), or path to a compiled package directory (`_mellea/`), or path to `.melleafy-partial/`. **Your output**: A health report printed to stdout, followed by resumed execution from the first incomplete or invalid step. --- ## Phase 1: Discovery ### 1a. Resolve skill root and package directory 1. Read the path from `$ARGUMENTS`. If it points to a directory ending in `_mellea` or `.melleafy-partial`, that IS the package directory — derive the skill root as its parent. 2. Otherwise, treat `$ARGUMENTS` as the skill root. 3. From the skill root, locate the package directory: look for a subdirectory matching `*_mellea/`. If more than one matches, pick the one whose name derives from the source spec's `name:` frontmatter field (see Rule OUT-2 in `mellea-fy.md`). 4. Locate the intermediate directory: `/intermediate/`. 5. Note whether `.melleafy-partial/` exists at the skill root — if it does, this is a previously halted run; inspect it alongside any existing package directory. If neither a package directory nor a `.melleafy-partial/` directory exists at the skill root, the pipeline has never produced output. Set resume point = **Step 0** and jump to Phase 4 immediately. ### 1b. Source spec check Confirm the source spec still exists at the skill root (the `.md`, `.af`, `crew.py`, etc. file that was the original input). If the source spec cannot be found, halt with: ``` [REPAIR HALT] Source spec not found at skill root: Cannot repair without the original input. Locate the source spec and re-run /mellea-fy. ``` --- ## Phase 2: Step-by-step artifact audit Audit each step **in order**. For each step, classify its status as one of: | Status | Symbol | Meaning | | --------- | ------ | ------------------------------------------------------------------------------ | | `valid` | `✓` | All required outputs exist and pass structural checks | | `partial` | `⚠` | Some outputs exist but set is incomplete, or a file fails its structural check | | `missing` | `✗` | No outputs from this step exist | | `corrupt` | `✗!` | File(s) exist but fail to parse or are structurally empty | Stop classifying as `valid` once you find the first non-`valid` step — all subsequent steps are treated as `unknown` (downstream outputs from a broken step are unreliable even if they appear syntactically intact). ### Step 0 — Classification (`intermediate/classification.json`) **Valid** when all of: - `intermediate/classification.json` exists and parses as JSON - Contains fields: `archetype`, `source_runtime`, `modality`, `shape`, `tool_involvement_variant` - `halt` field is `null` or absent **Corrupt** when: file exists but fails `json.loads()`, or has `"halt": ""` (a halted classification cannot be resumed — see below). **Note on halted classification**: if `classification.json` contains a non-null `halt`, the spec itself triggered a cross-axis validation error. This is not a repair the pipeline can fix — report the halt reason and stop: ``` [REPAIR HALT] classification.json records a halt condition: "" This is a spec-level incompatibility, not a pipeline failure. Fix the source spec and re-run /mellea-fy. ``` --- ### Step 1 — Inventory (`intermediate/inventory.json`) **Valid** when all of: - `intermediate/inventory.json` exists and parses as JSON - Contains an `elements` array with at least 1 entry - Each element has `element_id`, `tag`, and `category` fields **Partial** when: file parses but `elements` is empty (Step 1b produced nothing — likely a read failure on the source spec). --- ### Step 2 — Element mapping (`intermediate/element_mapping.json`) **Valid** when all of: - `intermediate/element_mapping.json` exists and parses as JSON - Contains a `mappings` array with at least 1 entry - Each entry has `element_id`, `target_file`, and `target_symbol` fields --- ### Step 2.5 — Dependency plan (`intermediate/dependency_plan.json`, `intermediate/mellea_api_ref.json`) **Valid** when all of: - `intermediate/dependency_plan.json` exists and parses as JSON - Contains a top-level array or an object with a `dependencies` or `entries` key that is non-empty - `intermediate/mellea_api_ref.json` exists and either parses with `.modules` key present, OR contains `"grounding_unavailable": true` **Partial** when: `dependency_plan.json` exists but `mellea_api_ref.json` is missing (the API reference fetch failed partway through Step 2.5). **Note**: `intermediate/element_mapping_amendments.json` is expected as a sibling — if absent, treat Step 2.5 as partial (the amendments commit in Step 2.5d was not completed). --- ### Step 3 — Skeleton files (Python files inside `/`) **Valid** when all of: - `/pipeline.py` exists and passes `ast.parse()` - `/schemas.py` exists and passes `ast.parse()` - `/config.py` exists and passes `ast.parse()` - `/main.py` exists and passes `ast.parse()` - `pyproject.toml` exists at skill root - The `run_pipeline` function in `pipeline.py` is detectable (look for `def run_pipeline`) **Partial** when: some but not all of the above files exist. **Corrupt** when: any of the above files exist but `ast.parse()` fails on them (syntax error). **Skeleton vs populated distinction**: at this check, treat Step 3 as valid whether the function bodies contain real Mellea code or stub placeholders (`pass` / `...`). Step 5 completeness is assessed separately below. --- ### Step 4 — Fixtures (`/fixtures/`) **Valid** when all of: - `/fixtures/` directory exists - `/fixtures/__init__.py` exists - At least 1 additional `.py` file in `fixtures/` (the fixture cases) - All `.py` files in `fixtures/` pass `ast.parse()` **Partial** when: `fixtures/` directory exists but contains only `__init__.py` with no fixture cases, or some fixture files fail `ast.parse()`. --- ### Step 5 — Code bodies (populated Python files) Assess body completeness of `pipeline.py`. A Step 3 skeleton has empty bodies (`pass` or `...`); Step 5 fills them with real Mellea calls. **Valid** when all of: - `/pipeline.py` contains at least one call to a Mellea function. Detection: scan `pipeline.py` source for any of: `m.instruct(`, `start_session(`, `m.query(`, `m.react(`, `m.chat(`, `m.transform(`. At least one must be present. - `/config.py` is non-trivially populated: contains at least one `Final[` constant with a real string value (not just a `""` placeholder) - All conditional files expected by the dependency plan exist and pass `ast.parse()`: check `dependency_plan.json` for entries that require `slots.py`, `tools.py`, `constrained_slots.py`, `requirements.py`, `mobjects.py`, `loader.py` — each required file must be present **Partial** when: `pipeline.py` has no Mellea invocations (skeleton only — Step 5 never ran or was interrupted before writing), or a required conditional file is missing. --- ### Step 6 — Supporting artifacts (`/melleafy.json`, `mapping_report.md`, `README.md`) **Valid** when all of: - `/melleafy.json` exists and parses as JSON with at least `manifest_version`, `entry_signature`, `package_name` fields - `/mapping_report.md` exists and has non-zero size - `/README.md` exists and has non-zero size **Partial** when: some but not all of the above files exist, or `melleafy.json` parses but is missing required fields. --- ### Step 7 — Validation report (`intermediate/step_7_report.json`) **Valid** when: - `intermediate/step_7_report.json` exists and parses as JSON - Contains `overall_verdict` field - `overall_verdict` is `"pass"` — if `"fail"`, classify as `partial` (report exists but run did not complete cleanly) **Partial (lint failures present)**: if `overall_verdict` is `"fail"`, extract the failing lint IDs and their messages from the report — these are needed for Phase 3 repair routing. --- ## Phase 3: Resume point determination and repair routing After auditing all steps, compute the **first non-valid step** — that is the resume point. ### Resume routing table | First non-valid step | Sub-command(s) to run | Notes | | -------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | Step 0 | `/mellea-fy-classify` → then continue all remaining steps | Full restart from classification | | Step 1 | `/mellea-fy-inventory` → then continue from Step 2 | Re-inventory the source | | Step 2 | `/mellea-fy-map` → then continue from Step 2.5 | Re-map elements | | Step 2.5 | `/mellea-fy-deps` → then continue from Step 3 | Re-run dependency audit | | Step 3 | `/mellea-fy-generate` → then continue from Step 4 | Re-emit skeleton (existing Step 0–2.5 intermediate files are valid inputs) | | Step 4 | `/mellea-fy-fixtures` → then `/mellea-fy-generate` (Step 5 only) | Re-generate fixtures; skeleton from Step 3 is valid — pass it as grounding | | Step 5 | `/mellea-fy-generate` (body generation only, skeleton already present) → then Step 6 | Pass existing skeleton and fixtures as grounding context | | Step 6 | `/mellea-fy-artifacts` → then Step 7 | All Python and intermediate files are valid | | Step 7 — lint pass failure | See lint-specific repair routing below | | | Step 7 — all pass | No action needed — package is complete | | ### Step 7 lint-specific repair routing Read `step_7_report.json` to determine which lints failed, then apply: | Lint failure type | Action | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parseable` (Tier 1) | Resume at Step 5 — syntax errors in generated Python; pass failing files and parse errors to `/mellea-fy-generate` in repair mode | | Tier 2 structural lints (`cross-reference`, `validator-soundness`, `variable-safety`, `import-side-effects`, `import-soundness`, `stdlib-arity`, `grounding-context-types`, `format-annotation`, `known-behaviours`, `doc-citation`) | Resume at Step 5 — call `/mellea-fy-generate` in repair mode with exact lint failure messages as context (failing files only) | | `session-boundary` | Cannot auto-repair — halt immediately. Report exact pipeline.py line(s) causing the failure and the KB5 split pattern the user must apply manually, then call `/mellea-fy-validate` after | | `category-specific` | Cannot auto-repair — halt immediately. Report exact files and secrets/credential patterns found; these require manual inspection | | Tier 3 `melleafy-json-consistency` | Resume at Step 6 — regenerate `melleafy.json` and related artifacts; pass exact consistency sub-check failures as context to `/mellea-fy-artifacts` | | `timed_out` lints | Re-run `/mellea-fy-validate` once; if the same lint times out again, treat as a halt | ### Partial artifact handling When a step is `partial` rather than `missing`: - **Partial intermediate JSON** (Steps 0–2.5): delete the partial file before re-running the step. Incomplete JSON is worse than absent JSON — the next step might read it and produce corrupt output. - **Partial Python files** (Steps 3–5): do NOT delete existing valid files. Pass the list of missing or corrupt files explicitly to `/mellea-fy-generate` so it generates only those files, using the valid files as grounding context. - **Partial Step 6 artifacts**: pass the list of missing artifacts to `/mellea-fy-artifacts` so it regenerates only what is absent. --- ## Phase 4: Health report output Print this report before taking any action. The report is always emitted, even if resume point = Step 0. ``` ╔══════════════════════════════════════════════════════════╗ ║ Melleafy Repair — Health Report ║ ╚══════════════════════════════════════════════════════════╝ Skill root: Package dir: (or "not found") Partial dir: .melleafy-partial/ (or "absent") Source spec: Step audit: Step 0 Classification [✓ valid | ⚠ partial | ✗ missing | ✗! corrupt] Step 1 Inventory [status] Step 2 Element mapping [status] Step 2.5 Dependency plan [status] Step 3 Skeleton files [status] Step 4 Fixtures [status] Step 5 Code bodies [status] Step 6 Supporting artifacts [status] Step 7 Validation report [status — "pass" / "fail: " / "missing"] Resume point: Step — Action: ``` For each non-valid step, add an indented detail line listing what is missing or why the structural check failed. Keep each detail to one line. Example: ``` Step 5 Code bodies [⚠ partial] pipeline.py: no Mellea invocations found (skeleton only) slots.py: required by dependency_plan.json but absent ``` --- ## Phase 5: Execute the repair After printing the health report, immediately execute without pausing. Apply the routing decision from Phase 3. ### Execution rules **Pass valid intermediates as grounding.** When resuming mid-pipeline, the valid intermediate files from earlier steps are grounding context for the resumed step — load and reference them exactly as the original step would have. Do not re-derive information the intermediate files already contain. **Partial intermediates: clean before re-running.** If a step's output was classified as `partial` or `corrupt`, delete (or zero out) those specific files before invoking the sub-command. Log each deletion: ``` [REPAIR] Removing corrupt intermediate: intermediate/element_mapping_amendments.json ``` **Preserve valid files.** Files from steps classified as `valid` are NOT modified, moved, or deleted. The repair is surgical — only broken steps are re-run. **Cascade awareness.** If Step N is invalid and Step N+1 was classified as `valid` based only on file existence (downstream of the broken step), those Step N+1 artifacts are unreliable. Mark them as `invalidated_by_cascade` in the health report detail and delete them before running the repair, so the cascade step re-runs cleanly. **Run each required sub-command in the order determined in Phase 3.** After each sub-command completes, run a lightweight re-check (Phase 2 audit for only the step just completed) before proceeding to the next step. If the re-check fails, halt with: ``` [REPAIR HALT] Step sub-command completed but output is still invalid: Inspect the sub-command output above. The intermediate artifacts are preserved for debugging. ``` **On successful completion**, print: ``` [REPAIR COMPLETE] Pipeline resumed from Step . Package at: Run `mellea-skills run ` to execute, or `python -m pytest /fixtures/` to smoke-test. ``` --- ## Edge cases **`.melleafy-partial/` only — no `_mellea/`**: the run failed before the package directory was fully established. Inspect `.melleafy-partial/` as if it were the package directory. If it contains an `intermediate/` with valid Step 0–2.5 artifacts, resume from Step 3. If it is empty or contains only partially-written Python files with syntax errors, resume from Step 3 after cleaning `.melleafy-partial/`. **Both `.melleafy-partial/` and `_mellea/` exist**: a previous repair run also failed. Prefer `_mellea/` as the authoritative package directory — it is the product of the most recent complete (even if partial) successful write. Use `.melleafy-partial/` only to recover intermediate files not present in `_mellea/intermediate/`. Report both directories in the health report header. **Intermediate files in `.melleafy-partial/` are newer than in `_mellea/`**: use the newer file — it reflects the most recent attempt. Log the choice: ``` [REPAIR] Using intermediate/dependency_plan.json from .melleafy-partial/ (newer than package copy) ``` **Step 2.5 `ask` mode was interrupted**: `dependency_plan.json` exists but contains entries with `disposition: null` or `disposition: "pending"` — dispositions were not committed. Classify Step 2.5 as `partial`. Delete `dependency_plan.json` and re-run `/mellea-fy-deps`. The user will be prompted again for dispositions. **Package name mismatch**: if the directory under the skill root named `*_mellea/` does not match the name derivable from the current source spec's frontmatter `name:` field, warn: ``` [REPAIR WARN] Package directory name '' does not match expected ''. Proceeding with found directory. If the spec's name: field changed, delete the package directory and re-run /mellea-fy. ``` **No `$ARGUMENTS` provided**: use the current working directory as the skill root. --- ## What repair does NOT do - Repair does not modify the source spec. - Repair does not attempt to fix `session-boundary` or `category-specific` lint failures — these require human review of the generated code. - Repair does not delete the skill root, source spec, or any file outside the package directory and `.melleafy-partial/`. - Repair does not change generation mode (`--dependencies=`) — it inherits whatever mode was used for the original run (read from `dependency_plan.json:generation_mode` if present, otherwise defaults to `auto`).