For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/shared/documentation/troubleshooting.md.
Quick start

Troubleshooting

A troubleshooting page starts from a symptom the reader can recognize. Its job is to return the reader to a working task safely.

Failure-to-fix mapping

Why

An exact lock-drift message is easier to find than a heading called “installation problems.” A fix should preserve edited files instead of turning diagnosis into data loss.

Rules

  • MUST use H2 issue headings that work as direct links. [review]
  • MUST state Symptom, Fix, and Verification for each issue. [review]
  • MUST include the exact error text when it is stable and useful for searching. [review]
  • MUST distinguish changed intent, changed source bytes, and edited destination bytes. [review]
  • MUST explain prerequisites or data effects before a destructive recovery action. [review]
  • MUST avoid presenting an unsupported command as a fix. [review]
  • SHOULD keep causes brief and link conceptual explanations elsewhere. [review]
  • SHOULD group related symptoms without hiding them behind generic headings. [review]

Example issue

## Pack already exists

**Symptom:** `add` reports that the pack already exists in project configuration.

**Fix:** Use the existing recorded installation; adding it again is not an update operation.

```sh
pnpm cli install
```

**Verification:** `pnpm cli list` still reports the original identity and selected groups.

[review]

Component-content tests check standard metadata and heading structure. Review checks symptom/fix/verification labels and verifies that recovery preserves user-owned data and uses supported commands.

See Runbooks for longer operating procedures and References for error contracts.

Enforcement

Component-content tests check standard metadata and heading structure. Review checks symptom/fix/verification labels and verifies that recovery preserves user-owned data and uses supported commands.

See Runbooks for longer operating procedures and References for error contracts.