> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Use charter fix Safely

> The correct workflow for reviewing and applying Charter's auto-fixes without surprises.

`charter fix` has a hard guarantee: it never mutates a file without showing you the diff first. This guide makes sure you never skip that step.

<Warning>
  Never run `charter fix` without `--dry-run` first. The diff is the contract — read it before accepting it. Applying a fix you haven't reviewed defeats the purpose of a diff-first tool.
</Warning>

<Steps>
  <Step title="Always dry-run first">
    Before writing anything, preview every change:

    ```bash theme={null}
    charter fix --dry-run
    ```

    Charter prints a unified diff for each affected file. Each hunk shows you the exact before/after — the file path, the rule being addressed, and whether the change is a create, append, or replacement.

    Read every diff. If a diff looks wrong for your repo, stop and make the change manually instead.
  </Step>

  <Step title="Understand what you're applying">
    Charter's safe fixers are narrow by design. Here's exactly what each one does:

    <AccordionGroup>
      <Accordion title="AE-CTX-001 — AGENTS.md creation">
        Creates `AGENTS.md` using a template populated with your detected language, CI platform, and toolchain. The template is a starting point — review it and fill in repo-specific context before committing. Charter will not overwrite an existing `AGENTS.md`.
      </Accordion>

      <Accordion title="AE-CTX-004 — .gitignore entries">
        Appends agent artifact patterns to your `.gitignore` (`.charter/`, `*.charter-session`, `.claude/local/`, `.cursor/cache/`). Review before committing to confirm no existing entries conflict and no paths you intend to track are being excluded.
      </Accordion>

      <Accordion title="AE-CI-002 — Charter GitHub Actions workflow">
        Creates `.github/workflows/charter.yaml` with a standard Charter gate workflow. Check the `threshold` value and verify the `actions/checkout` SHA pin matches the version you want before committing.
      </Accordion>

      <Accordion title="AE-MCP-001 — MCP package version bump">
        Updates floating `@latest`, semver ranges, or missing version pins in your MCP config to the exact version from Charter's catalog. Verify the resolved version is the one you want — especially for packages where the catalog version may lag the latest release.
      </Accordion>
    </AccordionGroup>

    <Note>
      `charter fix` does **not** delete files, silently mutate files, auto-fix secret findings, or auto-fix rules outside the four safe fixers above. That narrow scope is intentional.
    </Note>
  </Step>

  <Step title="Apply the fixes">
    Once the diffs look right, apply:

    <CodeGroup>
      ```bash Apply all safe fixes theme={null}
      charter fix
      ```

      ```bash Apply a single rule only theme={null}
      charter fix --rule AE-CTX-004
      ```
    </CodeGroup>

    When Charter updates an existing file, it writes the prior version to `.charter/backups/<timestamp>/` before making any changes. Create-only operations (new files) don't produce a backup because there's nothing to restore.
  </Step>

  <Step title="Re-scan to verify">
    Never assume a fix is good just because the diff looked right. Always verify:

    ```bash theme={null}
    charter doctor
    ```

    Confirm:

    * the targeted finding no longer appears in the active findings list
    * the score moved in the right direction
    * the fix didn't reveal a new problem elsewhere
  </Step>

  <Step title="Commit the result">
    Review the staged changes with `git diff --staged` before committing:

    ```bash theme={null}
    git diff --staged
    git commit -m "fix: apply Charter safe repairs"
    ```
  </Step>
</Steps>

## Recovery

<AccordionGroup>
  <Accordion title="Recovering from an unwanted fix">
    If you applied a fix and want to revert, Charter's backups are in `.charter/backups/`:

    ```bash theme={null}
    # List available backups
    ls .charter/backups/

    # Restore a specific file
    cp .charter/backups/20260610T074200Z/AGENTS.md ./AGENTS.md
    ```

    You can also use `git checkout` if the change has been staged but not committed:

    ```bash theme={null}
    git checkout -- AGENTS.md
    ```
  </Accordion>

  <Accordion title="When to skip charter fix entirely">
    Use a manual edit instead of `charter fix` when:

    * the file already exists and the repair needs repo-specific judgment
    * the change is outside the four safe fixers
    * the finding is about secrets or another manual-only rule
    * the generated template content needs substantial customization before it would be accurate

    `charter fix` is best when the safe path is obvious and mechanical.
  </Accordion>
</AccordionGroup>

## Recommended workflow

```bash theme={null}
charter doctor
charter fix --dry-run
charter fix
charter doctor
```

## Next steps

<CardGroup cols={2}>
  <Card title="Fix Engine" icon="settings" href="/docs/concepts/fix-engine">
    Why only four rules have fixers, and why secrets never do.
  </Card>

  <Card title="charter fix" icon="wrench" href="/cli/fix">
    Every flag the fix command accepts.
  </Card>

  <Card title="Suppress a Finding" icon="ban" href="/docs/how-to/suppress-a-finding">
    When a finding can't be fixed, record a governed exception.
  </Card>

  <Card title="Add Charter to an Existing Repo" icon="rocket" href="/docs/how-to/adopt-in-existing-repo">
    The full adoption loop from first scan to committed baseline.
  </Card>
</CardGroup>