1---2name: troubleshoot-163description: This skill should be used when the user reports "macstack lint fails", "prototype does not resolve", "env keys missing", "scaffold broke my files", "cross-stack reference does not work", or any macstack-dev skill errors out. Diagnoses the common failure modes of the macstack.json toolchain.4---56# Troubleshoot macstack-dev78## Lint failures910| Symptom | Cause → fix |11|---|---|12| `entity master problem` | master does not appear in stores exactly once with role=master → add a store with the master role or fix the `master` field |13| `category not in registry` | typo or a new niche → check `references/software-categories.json`; a new category = a kebab-case slug + a registry proposal (PR), never a silent custom value |14| `rating mismatch` | agentic.rating disagrees with the channels → rule: 3×true=full, 2=good, 1=basic, only "partial"=partial |15| `trigger unknown` | a workflow references a trigger code missing from `triggers[]` → triggers live ONLY in the collection, never inline |16| `delegation not downward` | an orchestrator appears in a worker's delegates_to → the hierarchy is strictly control_plane → orchestrator → worker |17| `cross-stack not declared` | the `foo:` prefix is not declared → add the stack to `stacks.root/substacks/links` |18| `lint red on rule 12.24` | a table exceeds the format budget (>4 columns, a cell >80 chars, <3 rows, or `<br>`/bold/code/pipes in a cell) → convert it to a list, see `documents/references/format-rules.md` |19| `lint red on rule 12.25` | prose is not in `docs.language` → translate the prose; identifiers (ids, YAML keys, anchors, statuses, file paths) always stay English, see `documents/references/format-rules.md` |2021## Prototype resolution2223- `github:owner/repo` fails to clone → check `gh auth status` / repo visibility;24 private repos need a PAT. Fallback: ask the user for a local absolute path.25- The repo has no `macstack.json` → it is a legacy prototype (only `stack.json`):26 use its files for scaffolding, but there is nothing to inherit — open a27 `client/OPEN-QUESTIONS.md §B` row and point at it by id from `lifecycle.open_questions`28 (prose in the markdown, pointer in the JSON).29- A prototype cycle (A→B→A) → an error by design; break the chain.30- A local path inside a cloud-synced folder (iCloud/Drive) may hang on first read31 (file materialization) — retry, or copy the prototype to a regular folder.3233## Infisical / env3435- `infisical secrets` reads the wrong instance → the CLI ignores `--domain` on36 authenticated reads; only one instance is active — run37 `infisical login --domain=…` first.38- `.env` got wiped empty → setup.sh lacks the guard: fetch into a temp file, mv39 only on success. Restore by pulling from Infisical again.40- A required key exists in macstack.json but is empty after sync → it is missing in41 Infisical: create it there; `provided_by: client` → move to42 `lifecycle.needs_from_client`.43- Values with `$`/spaces break `source .env` → render `KEY='value'` in single44 quotes (embedded quote → `'''`).4546## Scaffold4748- A user file got overwritten → an idempotency violation: an existing file with49 differences = diff + question, never a silent overwrite. Restore from git.50- Generated files contradict the architecture → the source order was violated:51 prototype → stack plugins → dev plugins; redo starting from the prototype.52- `${VAR}` from .mcp.json does not resolve → values must live in the env block of53 `.claude/settings.local.json` (filled by scripts/setup.sh), not inside .mcp.json.5455## The `macstack/` folder5657| Symptom | Cause → fix |58|---|---|59| Two `macstack.json` (root and folder) | lint errors on both → keep the folder copy, `git rm` the root one via `/macstack-dev:start` (migration mode) |60| Lint red on a document that reads fine | anchors were stripped (client returned an edited copy, or someone pasted through a WYSIWYG) → re-insert anchors idempotently; never rewrite the document |61| A cross-reference check reports a missing ID that is visibly present | a Cyrillic homoglyph in the ID token — Latin and Cyrillic A B E K M H O P C T Y X are indistinguishable on screen. Do not try to spot it; find it with `grep -RPn "[^\x00-\x7F]-[0-9]" macstack/`, which matches a non-ASCII letter directly before the hyphen-number of an ID, then retype the token in ASCII |62| A client PDF reads as empty | not-yet-materialized iCloud file → size/first-bytes check before reading; refuse rather than guess |63| `.xlsx` cannot be opened by any file tool | ask for a CSV export beside it and write NO log entry, so the file stays in the unprocessed set |64| `D<n>` cited but nowhere to be found | the rulings file was written without allocating in `history/DECISIONS.md` first |65| A script prints in the wrong language | it never wired in `documents/references/i18n.py` → report it via `/macstack-dev:feedback` |6667## Discovery6869- `curl raw.githubusercontent.com/...marketplace.json` → 404: the branch is not70 `main` or the repo is private → use71 `gh api repos/agents-store/claude-plugins/contents/...`.72- No plugin exists for a software → open a §B row (pointer from73 `lifecycle.open_questions`, never prose in the JSON) + suggest74 creating it via plugin-creator; do NOT put a non-existent name into75 context.plugins.
agents-store