Impeccable
82k

Fix setup problems

Check whether Impeccable’s setup still fits your project.

On this page 4 sections

A project can change while its Impeccable setup stays behind. Doctor checks the saved context, configuration, and hooks for problems such as an old file format, a setting that has no effect, or a hook pointing to a missing script.

Check your project

In your AI coding tool:

/impeccable doctor

You can also ask, “What’s out of date in this project’s Impeccable setup?”

How it works:

  1. Inspect the setup. Doctor checks the product record, visual record, config, saved page briefs, and design hooks.
  2. Repair mechanical issues. It applies migrations that require no design or product decision and reports what changed.
  3. Explain the remaining findings. It offers a specific fix or points to the command that needs your input. If nothing needs attention, you get a short confirmation.

Doctor maintains the setup. It does not redesign the interface or rewrite your product’s purpose as part of a repair.

A finding you can act on

In this example, a project folder was renamed but the config still points to its old name:

Folder on disk
apps/
└── store/
Saved project root
"projectRoots": [
  "apps/old-name"
]
Doctor foundThe configured folder does not exist.

Impeccable is using the repository root as the active project. Confirm which folder the setting should name before changing it.

From an actual diagnostic run on a small example project. The finding is summarized here; Doctor left the configuration unchanged.

What gets repaired automatically?

The finding’s category describes the next action, rather than how severe the problem is:

Category What happens
Mechanical Doctor applies a defined migration, such as moving a design companion file from a retired location, and reports it.
Worth knowing It explains the finding and offers a fix. Your work can continue.
Needs a command It names the gap and recommends a command such as init or document. That command runs when you ask for it.

An outdated file format may have a mechanical repair. Deciding whether the file still describes your product or design takes a review of its contents.

Notices at the start of a session

Impeccable also runs a lightweight check when a session begins. It can flag an older product-record format, a design companion file that needs refreshing, an unrecognized config key, or native app files paired with web-only context.

These notices do not block your task. The same finding is shown at most once a week per project. Run Doctor whenever you want the fuller report, including checks for broken hooks and changes since the visual record was last updated.

Show the report only when I ask

Set "stalenessCheck": false in .impeccable/config.json to turn off session-start notices for the project. Set IMPECCABLE_NO_STALENESS_CHECK=1 in the environment for a session-specific override.

You can still run /impeccable doctor with these notices disabled.

Reference details

Which files and settings are checked?
  • PRODUCT.md: older schema versions, retired fields, and conflicts between the recorded platform and native build files. A schema version describes the file format; a new Impeccable patch release does not by itself make the record stale.
  • DESIGN.md and .impeccable/design.json: gaps in the visual record, an outdated companion-file schema, a companion file older than the record, and retired file locations. DESIGN.md follows the external design.md format and does not carry Impeccable’s product-schema stamp.
  • Config: unrecognized top-level or detector keys, ignored rule IDs that no longer exist, exact ignored file paths that are gone, and project-root patterns that match no folder. Doctor also checks the saved mockup/code workflow choice when applicable.
  • Design hooks: missing script paths and conflicts between the installed hook and its enabled state.
  • Saved page briefs: records whose associated file or route can no longer be found.

If the rule registry is unavailable, the report says it could not validate the ignored rule IDs.

Does a lot of changed code mean DESIGN.md is wrong?

One check counts commits to visual source directories since DESIGN.md was last edited. That count is a reason to look, not proof that the record is wrong.

Ask Impeccable to compare the record with your current tokens and components if you want to know what has changed. Use document to update the visual record, or init to revisit product context.

Projects with several apps

Name the app you want checked:

/impeccable doctor --target apps/store

Without a target, the report describes the repository root. It also lists which apps have their own product and design records and which inherit them.

Inheritance is often useful. Check it when the apps differ: a native app inheriting a web product record may receive the wrong platform guidance. Give that app its own PRODUCT.md when it needs distinct product context.

Is this how I update Impeccable itself?

Use the updater for the installed tool version:

npx impeccable update

Doctor checks the project’s saved setup against what the installed version expects. An available tool update is reported separately.