abpai/harness-doctor/doctor-explain

Doctor Explain

Explains Harness Doctor rules and edits harness.config.* safely. Use this when a user wants to understand a rule or change which rules run — not for fixing diagnostics (that is the harness-doctor skill / /doctor).

Triggers: /doctor-explain, /doctor-config, "why did this rule fire", "I disagree with this rule", "turn this rule off", "stop flagging X", "too noisy", "disable design rules".

Workflow

1. Identify the rule key from the diagnostic (e.g. harness-doctor/docs-structure/spec-contract-exists).
2. Explain it before changing anything:

bunx --bun @andypai/harness-doctor@latest rules explain docs-structure/spec-contract-exists

1. Pick the narrowest control that matches the user's intent (see decision guide).
2. Apply it with a rules subcommand (edits your harness.config.* or package.json#harnessDoctor in place, preserving other fields and formatting).
3. Validate the change did what they wanted:

bunx --bun @andypai/harness-doctor@latest --verbose --diff

Commands

bunx --bun @andypai/harness-doctor@latest rules list                         # every rule + its effective severity
bunx --bun @andypai/harness-doctor@latest rules list --configured            # only what your config changed
bunx --bun @andypai/harness-doctor@latest rules list --category Security      # filter by category
bunx --bun @andypai/harness-doctor@latest rules explain <rule>               # why it matters + how to configure
bunx --bun @andypai/harness-doctor@latest rules disable <rule>               # rule never runs
bunx --bun @andypai/harness-doctor@latest rules enable <rule>                # turn back on at its recommended severity
bunx --bun @andypai/harness-doctor@latest rules set <rule> warn              # off | warn | error
bunx --bun @andypai/harness-doctor@latest rules category "Maintainability" off   # whole category
bunx --bun @andypai/harness-doctor@latest rules ignore-tag dead-code         # skip a rule family
bunx --bun @andypai/harness-doctor@latest rules unignore-tag dead-code

Rule references accept the full key (harness-doctor/docs-structure/spec-contract-exists) or the bare id (docs-structure/spec-contract-exists).

Decision guide

Match the control to the intent — prefer the narrowest one:

• User disagrees with one rule / it's a false positive for them → rules disable <rule> (sets rules.<key> = "off"; the rule stops running everywhere). This is the default for "I don't want this rule".
• Rule is fine but wrong severity → rules set <rule> warn or rules set <rule> error.
• A disabled-by-default rule they want on → rules enable <rule>.
• A whole area is unwanted (e.g. all Maintainability rules) → rules category "<Category>" off.
• A behavioral family is noisy (e.g. docs, dead-code, supply-chain) → rules ignore-tag <tag>.
• Keep it locally but hide from PR comment / score / CI gate only → do NOT disable. Edit surfaces in your config (surfaces.prComment.excludeRules, surfaces.score.excludeTags, surfaces.ciFailure.excludeCategories). The rule still shows in local cli output.

How the layers combine: ignore.tags drops every diagnostic from rules carrying that tag, so a tagged rule stays silent even if rules/categories set it to warn/error (a rule-level override cannot re-enable a tag-ignored rule). For rules that aren't tag-disabled, rules overrides categories overrides the rule's default. surfaces is visibility-only and never changes whether a rule runs.

Config shape

Config lives in harness.config.ts (or .js/.mjs/.cjs/.json/.jsonc), or the harnessDoctor key in package.json. The rules commands edit whichever exists — TS/JS edits preserve formatting (via magicast) — and create harness.config.json when none does, stamping $schema:

// harness.config.ts
export default {
  rules: { "harness-doctor/docs-structure/spec-contract-exists": "off" },
  categories: { Maintainability: "warn" },
  ignore: { tags: ["dead-code"] },
};

Educating the user

When explaining a rule, lead with the "Why it matters" guidance from rules explain (it works offline and is the source of truth). Only after they understand it should you offer to disable it — many "bad" rules are catching real issues.