--- name: arc-fix description: Resolve contract drift in an Arc-managed project. Use when arc check reports drifts, when implementing changes that touch components or schemas, or when a user asks to "fix the drift" / "make arc check pass". Drives the arc_check → arc_explain → arc_propose_fix → edit → arc_validate_patch loop. --- # arc-fix Resolve contract drift in an Arc-managed project. Arc is a contract-driven codegen + drift detector; this skill drives the standard agent fix loop using the five MCP tools the Arc server exposes. ## When to use Trigger this skill when any of the following is true: - The user asks to "fix arc check", "fix the drift", "make arc green", or similar. - `arc check` (CLI or `arc_check` MCP tool) reports a non-empty `drifts` array. - You are about to edit a file under a bonded path (anything that appears in a component's `bonds.endpoints.*.handlers` / `clients` / `tests`, or any `.arc/` contract file) and you want to know which contracts constrain the edit before you write code. - A pre-commit / CI run failed on `arc check`. Do **not** trigger when: - The project has no `.arc/` directory (Arc is not installed). - The user is asking to *change the contract itself* with no relation to drift — that's a contract authoring task, not a fix loop. ## Setup check This skill assumes the Arc MCP server is configured for the agent host and its tools are reachable (`arc_check`, `arc_explain`, `arc_propose_fix`, `arc_validate_patch`, `arc_scope`). If the tools aren't available: 1. Confirm `arc` is installed in the target repo (look for `node_modules/.bin/arc` or a global `arc` binary; the stdio entry point is `arc mcp`). 2. Point the user at the integration docs under `docs/integrations/` in the Arc repo (VS Code forks, Cline, Continue all have copy-paste configs). 3. Stop. Don't try to invoke `arc` via shell as a fallback — the wire contract assumes you'll read the structured payloads. ## The loop The fix loop is intentionally tight. Do not skip steps; the validation step is the only thing that prevents you from confidently shipping a patch that trades one drift for another. ### Step 1 — call `arc_check` ``` arc_check() → { drifts: Drift[] } ``` - Input: no args (or `{ strict: true }` if the user wants warnings to count). - Output: `drifts` is an array of `Drift` objects. Each carries: - `id` — stable identifier; pass to `arc_explain` / `arc_propose_fix`. - `kind` — one of: `signature_mismatch`, `route_mismatch`, `forbidden_import`, `import_outside_depends_on`, `generated_file_stale`, `no_generated_files`, `unresolved_ref`, `bond_unresolved`, `fastapi_pattern_unsupported`, `parse_error`. - `severity` — `error` | `warning` | `info`. - `bond` — dotted path (`.endpoints..handlers`), when applicable. The terminal segment (`handlers`, `clients`, `tests`, `bonded_file:`) matches the key shape in `arc_scope.bonds`. - `expected` / `actual` — `{ description, source }` pairs. - `fix_hint` — one-line, often enough on its own to act. **If `drifts` is empty, you're done.** Report success. **If there are drifts, do not start editing yet.** Inventory them first: - Group by `kind`. Fixes are kind-shaped, not file-shaped. - Within a group, sort by `severity` (`error` > `warning` > `info`) so you attack blockers first. - A `no_generated_files` drift is a setup signal, not a correctness failure — the fix is to run `arc compile` once, which collapses many would-be drifts at once. Handle it before anything else. ### Step 2 — `arc_scope` before multi-file edits If your planned edit touches more than one file, **call `arc_scope` first** with the list of files you intend to touch: ``` arc_scope({ files: ["backend/routes/tasks.py", "backend/services/db.py"] }) → { components, schemas, bonds, forbidden_paths, tests } ``` Use the result to: - Confirm which `components` claim the files (anything outside this set is unbonded — Arc has no opinion). - Note `forbidden_paths`. **Treat these as hard constraints.** If your fix would introduce an import into a forbidden path, you have the wrong fix. - Note `tests`. After applying the fix, those test files are the natural smoke-test surface — read them before patching the handler to make sure your change doesn't break the test's expectations. - The `bonds` keys use the same `.endpoints..` vocabulary as `Drift.bond`, so you can navigate between scope and drift with one namespace. For single-file edits, you can skip `arc_scope` if the drift's `bond` already names the component and you understand the area. ### Step 3 — per drift, call `arc_explain` and `arc_propose_fix` For each drift, in order, both calls take the same `drift_id`: ``` arc_explain({ drift_id }) → { source_excerpt, code_excerpt, related_schemas, dependency_chain, why_it_matters } arc_propose_fix({ drift_id }) → { drift_id, fix_strategy, target_file?, target_symbol?, guidance } ``` Read all of: - `why_it_matters` — the per-kind rationale. If you don't agree with the rationale, you may be about to apply a fix that papers over a deeper contract bug. Pause and reconsider. - `source_excerpt` — the YAML chunk of the `.arc.yaml` contract this drift is rooted in. Empty string is possible (e.g. `generated_file_stale` has no single source contract). - `code_excerpt` — ~5-line window around the code-side location. Empty string for contract-only drifts (`unresolved_ref`, `no_generated_files`). - `related_schemas` — schema ids reachable from the drift's primary schema via `ref:` (capped at 10). These are likely places your fix has ripple effects. - `dependency_chain` — the `bond` split on `.` (or `[]` when no bond). - `fix_strategy` — coarse-grained label; see the table below. - `target_file` / `target_symbol` — where to edit, when knowable. May be absent for `manual` / `unresolved_ref` / `no_generated_files`. - `guidance` — the actionable one-liner (mirrors `drift.fix_hint`, often enriched for route mismatches). ### Step 4 — choose the edit shape from `fix_strategy` | `fix_strategy` | What to do | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `update_annotation` | Edit `target_file` at the signature of `target_symbol`. Fix the parameter type, return type, or both per `guidance`. Don't touch the body unless `guidance` says so. | | `update_decorator` | Edit `target_file`; rewrite the route decorator on `target_symbol` (path, method, or both) to match `expectedMethod` / `expectedPath` (read these off the drift payload from Step 1). | | `add_import` | Add the missing import at the top of `target_file`. (Reserved on the wire; no v0.1 drift currently produces this — if you see it, treat as `manual`.) | | `update_generated_file` | **Do not hand-edit.** Run `arc compile` from the project root. Generated files are derived from `.arc/` contracts; hand-edits get clobbered on the next compile. | | `update_bond_path` | Edit `.arc/components/.arc.yaml`; rewrite the bond ref (`::`) so it points at the real symbol. (Reserved; `bond_unresolved` currently falls back to `manual` in v0.1.) | | `manual` | Read `guidance` and `why_it_matters`. Decide between alternatives (e.g. "remove the import" vs "widen `depends_on`"). If the choice isn't obvious, surface it to the user before patching. | Per-kind notes: - `forbidden_import` / `import_outside_depends_on` — architectural decisions. Arc deliberately won't auto-fix these. Default to removing the offending import; only widen the contract (`depends_on` or `forbidden_paths`) when the user explicitly opts in. - `bond_unresolved` — Arc found a bond ref pointing at a symbol that doesn't exist. Either the symbol moved (update the bond) or it was never created (create it). Use `target_file` / `target_symbol` from the propose-fix payload — they're parsed straight from the bond ref. - `no_generated_files` — banner severity is `info`. Run `arc compile`; do not patch anything else until you re-run `arc_check`. - `parse_error` — Arc couldn't parse a bonded source file. Fix the syntax error first; everything downstream is unreliable until parsing succeeds. ### Step 5 — call `arc_validate_patch` before touching the working tree This is the rule that distinguishes "good fix loop" from "bad fix loop". Construct the unified diff for your proposed edit, then validate it against an overlay of the working tree: ``` arc_validate_patch({ diff: "" }) → { drifts: Drift[] } ``` The tool copies the working tree to a temp dir, applies the diff there, runs `arc check`, and returns the resulting drifts. **Your working tree is not modified.** That's the safety guarantee. Interpret the result: - Empty `drifts` array → the patch is clean against the contract. Apply it for real via the Edit tool. - The original drift is gone but new drifts appeared → your fix traded one bug for another. Go back to Step 3 (or Step 4) with the new drift IDs. Don't apply. - The original drift is still present → your fix didn't land. Re-read `arc_explain`'s `code_excerpt` and `source_excerpt`, or call `arc_propose_fix` again for fresh `target_*` values, then revise the diff. - The tool returns `isError: true` with a git stderr message → your diff doesn't apply cleanly (whitespace, missing context, wrong line numbers). Regenerate the diff against the current file contents. Only after a clean validation should you apply the change via the Edit tool. ### Step 6 — re-run `arc_check` After applying, call `arc_check` again to confirm. If new drifts appeared (e.g. because a generated file is now stale), loop back to Step 1. ## Iteration policy - Bound per-drift effort at **3 iterations** of `arc_propose_fix` → `arc_validate_patch`. If the third validate still produces drifts, stop guessing — surface the situation to the user with the drift payload and what you've tried. - Bound the outer loop at **5 passes** over `arc_check`. If `arc check` still isn't clean after 5 passes, something structural is wrong (the contract may itself be incorrect, not the code). Surface, don't grind. - A successful pass of `arc_validate_patch` does **not** mean "tests pass" — it means "the contract is satisfied". After the loop is green, run the project's normal test suite if the user expects test-level verification. ## Red flags When you notice yourself thinking any of these, stop and re-read the relevant step. | Thought | What's actually going on | Correct next action | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | "I already know what the fix is; I'll skip `arc_propose_fix`." | You're rationalizing skipping the cheapest oracle Arc gives you. Its `guidance` often catches edge cases. | Call `arc_propose_fix`. It's one MCP round-trip. | | "I'll just edit the file and re-run `arc_check`." | You're skipping `arc_validate_patch` and gambling that the edit lands clean. | Build the diff, validate it, *then* apply via Edit. | | "The generated file looks wrong; I'll patch it." | You're about to introduce a hand-edit that the next `arc compile` will overwrite. | Run `arc compile`. Fix the contract or the source, not the generated artifact. | | "The `forbidden_import` is annoying; I'll add the path to `depends_on`." | You're widening the contract to fit the code instead of considering whether the code is wrong. | Default to removing the import. Only widen with explicit user buy-in. | | "I'll fix all 8 drifts in one big edit, then validate once." | Bulk edits make a failed validation impossible to diagnose. You won't know which sub-fix broke it. | One drift, one diff, one validation pass at a time. | | "The drift `bond` is `tasks.endpoints.create_task.handlers` — I'll grep for that string in the code." | Bond paths are contract namespace, not code identifiers. Grep will miss. | Use `arc_propose_fix.target_file` / `target_symbol`, or read `arc_explain.code_excerpt`. | | "`arc_validate_patch` failed with `does not apply` — I'll force-apply via Edit anyway." | The diff is stale or has wrong line numbers. Forcing the edit will land it in the wrong place. | Regenerate the diff against current file contents, validate again. | | "There's only one drift and the `fix_hint` is obvious. I'll edit and ship." | One-shot edits without validation work ~80% of the time. The 20% is silent regressions. | One round-trip through `arc_validate_patch` is cheap. Take it. | ## Reference: tool wire shapes The exact field names below match what the MCP server emits — don't paraphrase, the agent host parses them literally. ``` arc_check → { drifts: Drift[] } arc_explain → { source_excerpt: string, code_excerpt: string, related_schemas: string[], dependency_chain: string[], why_it_matters: string } arc_propose_fix → { drift_id: string, fix_strategy: "update_annotation" | "update_decorator" | "add_import" | "update_generated_file" | "update_bond_path" | "manual", target_file?: string, target_symbol?: string, guidance: string } arc_validate_patch({ diff }) → { drifts: Drift[] } // or isError + stderr arc_scope({ files }) → { components: string[], schemas: string[], bonds: Record, forbidden_paths: string[], tests: string[] } ``` `Drift` core fields you'll touch most often: `id`, `kind`, `severity`, `bond?`, `expected: {description, source}`, `actual: {description, source}`, `fix_hint`. Kind-specific fields (e.g. `importer`/`imported` on `forbidden_import`, `expectedMethod`/`expectedPath` on `route_mismatch`, `expectedRequest`/`expectedResponse` on `signature_mismatch`, `schemaId`/`field` on `unresolved_ref`) appear on top of those.

arc-fix

Install this skill

Comments