--- name: skillsaw-fix description: "Fix skillsaw lint violations — apply deterministic autofixes, then resolve the remaining violations with targeted edits guided by `skillsaw explain`. Use when skillsaw reports violations, when asked to clean up lint findings, or after `skillsaw fix` leaves violations behind." compatibility: "Requires skillsaw (uvx skillsaw or pip install skillsaw)." metadata: author: stbenjam version: "1.0" --- # skillsaw Fix You are fixing **skillsaw** lint violations in this repository. skillsaw lints agentic contextual building blocks (CLAUDE.md, skills, plugins, agents, hooks, etc.). Deterministic fixes are applied by the tool itself; everything else is your job — you read the violation, load the rule's how-to-fix guidance, and make a targeted edit. Work through the steps in order. Report progress to the user at each stage. ## Step 1: Locate skillsaw Run `skillsaw --version`. If the command is missing, use `uvx skillsaw` as the prefix for every command below (or `pip install skillsaw` if uvx is unavailable). ## Step 2: Lint and inventory Run `skillsaw` (lint) from the repository root and capture the output. Each violation line includes the severity, file path, line number, message, and rule ID. If the lint exits 0 with no violations, tell the user the repository is clean and stop. Build an inventory: group the violations by rule ID and note how many files each rule touches. Show the user this summary before making changes. ## Step 3: Apply deterministic autofixes Run `skillsaw fix`. This applies safe, structural fixes (missing frontmatter, kebab-case names, plugin registration, and similar). Then preview the suggested tier with `skillsaw fix --suggest --dry-run`. Suggested fixes (e.g. updating stale references after a rename) are mechanically derived but may over-match. Evaluate each hunk in the diff individually: for a stale-reference rewrite, decide whether the flagged text is really a reference to the skill or just the same word used generically — "the `data-parser` skill" is a reference; "our data parser" is not. If every hunk is correct, apply the tier with `skillsaw fix --suggest`. If any hunk is wrong, skip the tier entirely and handle those violations manually in Step 5, applying only the edits you judged correct. Re-run `skillsaw` and report how many violations the autofixer resolved. ## Step 4: Load fix guidance for each remaining rule For every rule ID still in the inventory, run: ```sh skillsaw explain ``` The output includes the rule's rationale and a "How to fix" section — this is the authoritative guidance for what a correct fix looks like. Read it before editing anything. Do not guess at what a rule wants from its message alone. ## Step 5: Fix the remaining violations Work file by file. For each violation: 1. Read the file and understand the context around the flagged line 2. Apply the `skillsaw explain` guidance with a targeted edit — change only the text that triggers the violation, preserving the author's meaning, structure, and formatting 3. Keep edits minimal — never rewrite a whole file to fix one line After finishing a file, re-run `skillsaw` scoped to confirm the violations are gone and your edit introduced no new ones. Common cases: - **content-weak-language**: replace hedges ("try to", "consider", "if possible") with direct imperatives or explicit conditions. - **content-tautological**: delete empty truisms ("follow best practices") or replace them with the specific, actionable instruction the author meant. - **content-negative-only**: keep the prohibition, add what to do instead. - **agentskill-rename-refs**: single-word skill names are flagged but never rewritten automatically — the word is too ambiguous. Check each flagged line yourself: rewrite it only if the mention actually refers to the skill (`/name` invocations, `skills/name/` paths, "the name skill"), and leave generic uses of the word unchanged. - **Missing or invalid frontmatter fields**: derive names from directory names and descriptions from the body content. - **content-embedded-secrets**: replace the secret with an environment variable placeholder and tell the user to rotate the credential — removing it from the file does not remove it from git history. ## Step 6: Escalate what you cannot decide Some violations need decisions only the user can make — for example, which of two contradictory instructions is correct, or whether a flagged reference is intentional. Do not invent an answer. List these violations with your recommendation and ask the user. If the user wants to accept some violations for now, run `skillsaw baseline` so only new violations fail future lints, and remind them to commit `.skillsaw-baseline.json`. ## Step 7: Verify and summarize Run the repository's own lint entry point if it defines one — check the Makefile (or equivalent task runner) for a skillsaw target such as `lint` or `lint-fix` and use that, since it may pin a version or pass flags like `--strict`. Otherwise run `skillsaw` directly. If the repository has a grade badge (`.skillsaw-badge.json` exists, or the lint target depends on a `badge` target), refresh it: run `make badge` if defined, else `skillsaw badge`. The badge reflects committed state, so include the updated `.skillsaw-badge.json` in the files to commit. Report: - Violations fixed automatically (Step 3) - Violations fixed by edits (Step 5) - Violations escalated or baselined (Step 6) - Files modified - Final exit status If the lint still fails, show the remaining violations and explain why each one is still open.