FAQ

Why is my score lower than I expected?

The score is a single quality verdict, not a tally of findings. It measures how strongly your instructions are written — how specific, direct, and well-structured they are, and how little they compete with one another — so a file with vague, buried, or conflicting instructions scores low even when the finding count is small, and a long file with many cosmetic findings can still score well. The Findings line is a separate worklist; clearing low-severity findings will not move the number much.

To see what's pulling it down, run ails check -v and read the per-surface bars (Main, Rules, Skills, …) — the lowest-scoring surface is where the weak instructions live. See Score Guide for how the number is built.

If you disagree with a specific finding, open an issue so we can review the rule, and / or disable the rule locally — see How do I disable a rule I disagree with? below.

How do I make an agent write rule-compliant skills on the first try?

Use ails rules list --capability=skill -f md to fetch the workflow-ordered rule set, then paste it into the agent's authoring prompt. The agent reads the constraints first and writes a compliant SKILL.md instead of patching findings after ails check. Same flow for --capability=agent, --capability=rule, --capability=main. --no-examples strips Pass/Fail blocks for a shorter context payload. See Rules CLI.

How do I disable a rule I disagree with?

Add it to .ails/config.yml:

disabled_rules:
  - CORE:C:0010   # Build And Test Commands

Run ails explain CORE:C:0010 first to read the rule body and pass / fail examples. Understand what the rule is checking before you decide whether to comply with it. Disabling is the right call when the rule's intent doesn't fit your project. Complying is the right call when the intent matches your project, but you weren't reaching it before.

What changes when I sign in?

Anonymous mode is enough to see what's wrong and how many cross-file conflicts exist. Signing in gives you the full diagnostic: the exact line each finding refers to, the fix text the rule recommends, and the coordinates of every cross-file conflict — what to change to satisfy the rule, not just that something is off. Signing in also raises the per-request payload cap and hourly rate.

Sign in with ails auth login (browser-based GitHub Device Flow — the CLI exchanges your GitHub token for a Reporails API key). Credentials are stored in ~/.reporails/credentials.yml (chmod 0600 on POSIX); remove them with ails auth logout. To capture the key for CI, run ails auth token.

Full breakdown of what each mode includes: Tiers and Limits.

Does Reporails read my source code?

No. The CLI reads only the instruction-file types listed in Agent Support — CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md, plus the rule / skill / agent / hook files associated with each. It does not scan your repo's src/, tests/, or any other application code.

See reporails.com/privacy-policy for the data-handling specifics on what is sent to the diagnostic backend, how long it is retained, and what is logged.

Can I use this offline?

The local rules (mechanical and structural) run fully offline. The semantic rules (reinforcement patterns, content-quality checks, cross-file analysis) require a request to the diagnostic backend. There is no offline-only mode for those, the analysis and diagnostics runs server-side.

When the analysis backend is unreachable, the run degrades gracefully: the headline reads Quality n/a and the per-surface and per-item score bars are suppressed (there's no single quality score without the analysis service). You still get the findings from the local rules, the scope summary, and the local (mechanical and structural) rule results — just no score.

Is my instruction file ever stored on the diagnostic backend?

No. Instruction file contents never leave your machine. The CLI parses your files locally and computes embeddings on-device; the diagnostic backend receives only analysis metadata (embeddings, structural counts, cluster IDs, file paths) — never the prose, examples, or reasoning text in your instruction files.

See reporails.com/privacy-policy for the full data-handling specifics.

I run a polyglot monorepo. Should I have one CLAUDE.md or many?

Different agents handle this differently — see Agent Support for the per-agent layout. For Claude, use one root CLAUDE.md for project-wide identity and constraints, and per-directory child CLAUDE.md files for path-specific guidance — Claude Code loads them automatically when you cd into the directory. For Cursor, use .cursor/rules/*.mdc for per-directory guidance. Codex and Gemini read a single root file (AGENTS.md or GEMINI.md).

If you only have a root file but a large repo, you'll likely trip CORE:E:0002 (Instruction File Size Limit) and / or CORE:E:0001 (Total Instruction Size Limit). Split the content into the agent's native child-file mechanism, listed per-agent on Agent Support.

Why does my CI run say "anonymous" even though I'm authenticated locally?

CI runs in a fresh environment without the credentials file at ~/.reporails/credentials.yml that ails auth login writes locally. Capture your key with ails auth token, store it as a secret in your CI provider, and pass it via the action input or environment variable:

- uses: reporails/cli/action
  with:
    api-key: ${{ secrets.REPORAILS_API_KEY }}

See the GitHub Actions section in the README.

Is the rule set the same for every agent?

No. Reporails ships CORE rules that are agent-neutral (file size, heading hierarchy, reinforcement patterns, credential handling, cross-file consistency) and per-agent rules that target each agent's own config formats (Claude hooks, Cursor .mdc rule frontmatter, Copilot instructions, Codex AGENTS.md conventions, Gemini commands and extensions). See Agent Support → Cross-agent rules for the breakdown of which rules fire universally.

When you run ails check --agent claude, only CORE plus Claude-scoped rules fire. Without --agent, Reporails auto-detects which agents are present by looking for each agent's base config file and runs the corresponding rule sets.

How do I auto-fix findings?

Run ails check --heal — it applies the deterministic fixes (missing sections, formatting) after validation. Preview what would change first with ails check --heal --dry-run. --fix is an alias for --heal (matching the eslint / ruff convention), so ails check --fix works the same way.

What's the right way to file a bug?

Open an issue at github.com/reporails/cli/issues. Include the version (ails version), your OS / Python version, the command you ran, and the unexpected output. JSON output (ails check -f json) is the most useful format for bug reports.

← Capability Levels · FAQ