Troubleshooting

Skills are not showing up in Codex

Symptom: You invoke a skill and Codex does not recognize it.

Fix:

1. Run the installer:

   npm run install-codex-skills -- --force

2. Restart Codex so the skill picker reloads.
3. Verify the skills are in ~/.codex/skills/.

If you want edits to the repo-local skills/ to reflect live, use --link instead of copying:

npm run install-codex-skills -- --link --force

npm run doctor reports missing keys

Symptom: The doctor says FIRECRAWL_API_KEY or COMPOSIO_API_KEY is missing.

Fix:

1. Confirm .env exists in the repo root.
2. Confirm the variable name is exact — FIRECRAWL_API_KEY and COMPOSIO_API_KEY.
3. Confirm there is no trailing whitespace or surrounding quotes on the value.
4. If you keep keys in .env.local or process.env, confirm you are running Codex from the repo root.

Skill returns lots of assumptions and few citations

Symptom: The Account Intel Brief or Demo Scenario Builder returns with most of its content in the assumptions section.

Fix:

• Confirm FIRECRAWL_API_KEY is present (npm run doctor).
• If the key is present, the most likely cause is that Firecrawl did not find enough public information about the account. This is not a bug. The assumptions section is then the TODO list for your discovery call.
• If you have known docs URLs, pass them — this is most useful for the Integration Fit Gap Analyzer.

Fit-gap matrix has too many unknown rows

Symptom: Most rows come back unknown.

Fix:

• This is working as intended when vendor docs cannot be grounded.
• Pass explicit notes.vendorDocs URLs for the vendor systems you care about.
• Do not pressure the skill into marking rows supported. Freehanding integration claims is the exact failure mode Solutioneer is designed to prevent.

Connect now does not open a browser

Symptom: You pick Connect now but nothing opens.

Fix:

• If you are running Codex in a sandboxed environment, browser tooling may be unavailable. Codex should provide the login link in chat instead. Copy it into your browser and finish the flow there.
• Codex polls the connected account for up to five minutes. If you take longer, the connection times out and you will need to retry.

Composio connection stays pending

Symptom: You finished OAuth but Codex says the connection is not active.

Fix:

• Refresh the Composio dashboard and confirm the connection shows as Active.
• Some OAuth flows require a second grant (for example, org-level access on GitHub). Make sure you granted every requested scope.
• If the connection is stuck, disconnect it in the Composio dashboard and reconnect.

Writeback fails with a permission error

Symptom: Codex tried the external write and the provider returned a permission error.

Fix:

• Confirm the account you authed with has write access to the target resource (Confluence space, Linear team, GitHub repo).
• For Linear, confirm the team slug matches the connected workspace.
• For GitHub org repos, confirm the OAuth app has the org scope.

Routing picks the wrong skill

Symptom: A natural-language request routes to a skill you did not want.

Fix:

• Use the explicit form. $account-intel-brief, $demo-scenario-builder, $integration-fit-gap-analyzer, or $poc-handoff-orchestrator always win over inferred routing.
• If intent is genuinely ambiguous across two skills, Codex should ask one routing question before intake. If it does not, use the explicit form on retry.

Output is saved without confirmation

Solutioneer should never save without confirmation. If it did, file an issue — this would be a violation of the save rule in AGENTS.md. The expected behavior is:

• Default output is chat-only.
• Before saving, Codex asks for confirmation.
• Saving only happens after confirmation.

Writeback executed before I confirmed

Same — writeback is always confirmation-based. Expected behavior:

1. Codex confirms the external write.
2. Codex confirms the destination.
3. Codex verifies the toolkit is connected.
4. Only then does Codex execute the write.

If any step is skipped, file an issue.