Skip to main content

Chapter 19: Lumen Troubleshooting

Chapter 19: Lumen Troubleshooting

The workflow stopped unexpectedly

Most likely cause: A Level 2 or Level 3 gate is waiting for a response.

Run /lumen:status to check for pending gates:
/lumen:status
[LUMEN] Pending approvals:
  W4 Feature Validation — AI ethics clearance [Level 3]
  Waiting for: Head of Compliance
  Timeout in: 54 hours

If a gate is pending and you need to respond now, run /lumen:approve and provide the outcome tracking ID. If you are waiting for a named approver (Level 3), you cannot proceed until they respond.

If no gate is pending, check whether a required slot was missing. Look at the last agent output in the session. It will state which required slot was absent and which agent wrote it.

Evidence quality is always LOW

Most likely cause: PostHog is not connected or has insufficient data.

Run /lumen:status to confirm PostHog is connected. If it shows ✗ not connected, run /lumen:setup posthog and add your API key to .env.

If PostHog is connected but evidence is still LOW, check:

  • How much data is available? Less than 30 days of event data produces LOW evidence for retention signals.
  • Whether the event schema has gaps. EventIQ will flag missing critical events. Add them to your PostHog tracking before re-running.
  • Whether the interview count is below the threshold. DiscoveryOS requires at least 10 interviews for MEDIUM evidence. Below 10, it rates the opportunity tree as LOW.

W1 runs in PARTIAL mode even though PostHog is connected

Most likely cause: The PostHog API key is set, but lumen-setup.json still shows "posthog": { "enabled": false }.

Fix: Run /lumen:setup posthog. SetupGuide will test the connection and update lumen-setup.json to "enabled": true.

Second cause: The PostHog host URL is wrong. EU-hosted PostHog projects use https://eu.posthog.com, not https://app.posthog.com. Check the host in lumen-setup.json.

MCP credentials are not working

Checklist:

  1. Check that the credential is in .env, not lumen-setup.json. API keys belong in .env. URLs and enabled flags belong in lumen-setup.json.
  2. Check for extra spaces or line breaks around the credential. A copied token with a trailing space will fail silently.
  3. For Slack: confirm the bot has been invited to the channel. Pasting xoxb-... is not enough — the bot needs /invite @YourBotName in the Slack channel.
  4. For HubSpot: confirm the private app has the correct read scopes (crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read). Missing scopes cause a permissions error that looks like a connection failure.
  5. For Stripe: if you are testing, use sk_test_... not sk_live_.... Live keys in a test environment may not return useful data.
Run /lumen:setup [mcp-name] after any fix to re-test.

A Level 2 gate never arrived in Slack

Most likely cause: Slack is not connected, or the bot is not in the configured channel.

Run /lumen:status to confirm Slack shows ✓ connected. If it shows ✗ not connected, run /lumen:setup slack.

If Slack shows connected but the notification did not arrive, check:

  • The channel name in lumen-setup.json. It must match exactly, including the # prefix: "ops_channel": "#product-ops".
  • Whether the bot was invited to the channel. In the Slack channel, type /invite @Lumen.
  • Whether your Slack workspace has notification delivery delays for bot messages (rare, but possible for compliance-restricted workspaces).

The gate will still be visible in Claude Code regardless of Slack status. You do not need Slack to respond to a gate.

DecideWell keeps recommending options I have already tried

Cause: You did not include previously tried interventions in your prompt.

DecideWell reads the intake_context you provide and explicitly excludes options already attempted. If you do not mention what you have tried, it does not know.

Fix: Add a "Previously tried" section to your prompt:

Previously tried:

  - 2-email re-engagement sequence (Weeks 4–5) — no measurable impact

  - Personal outreach to top 3 at-risk accounts — mixed results (1 retained, 2 churned)

DecideWell will exclude these from the recommendation and state that exclusion explicitly in the decision memo.

The report sections have no data (all blank or UNAVAILABLE)

Most likely cause: A required upstream agent could not write its context slots, so all downstream agents have nothing to read.

Look at the first UNAVAILABLE section in the report. The Limitations section will tell you which slot was missing and which agent failed to write it.

The most common blank-report cause: PostHog not connected → SignalMonitor cannot run → pmf_score_by_segment is never written → DiscoveryOS and MarketIQ have reduced context → report sections are thin or UNAVAILABLE.

Fix: Connect PostHog and re-run. If PostHog is connected and sections are still blank, run /lumen:setup to verify all connections and check for credential errors.

The outcome tracking follow-up produced no comparison data

Cause: Supabase was not connected during the original workflow run, so no baseline was stored.

If Supabase is not connected, outcome tracking IDs exist only for the current session. They cannot be retrieved in a future session. The follow-up run will produce a fresh report with no delta comparison.

Fix: Connect Supabase before your next workflow run. All future outcome tracking IDs will persist. You cannot retroactively store baseline data from a prior run.

DataLayer issued BLOCKED, and the workflow stopped

This is expected behavior, not an error. BLOCKED means the feature as designed, cannot proceed under the applicable regulatory or ethics constraints.

What to do:

  1. Read the BLOCKED status explanation. DataLayer always states the specific reason.
  2. Redesign the feature to address the blocking condition. Common changes: remove personal data from the AI model input, add a mandatory human-override mechanism, restrict the feature to an explicit opt-in cohort.
  3. Re-run W4 with the redesigned feature description. DataLayer will re-assess.

You cannot override a BLOCKED status. It is the only Lumen output that has no override path. This is intentional.

The session context was lost after restarting Claude Code

Cause: Upstash is not connected. Without Upstash, session context lives only in the current Claude Code session.

Fix: Connect Upstash via /lumen:setup upstash. After connection, the session context will survive restarts.

If you lost context mid-workflow and need to continue, re-run the workflow with the same prompt. If Supabase is connected, the prior agent outputs may still be in the Knowledge Graph, and the run will be faster.

Lumen is not appearing as an option in Claude Code

Cause: The plugin was not properly registered, or Claude Code was not restarted after installation.

Fix:
Confirm the plugin directory exists:
$ ls ~/.claude/plugins/lumen/
Confirm the agent stub exists:
$ ls ~/.claude/agents/lumen.md
If either is missing, re-run the installer:
$ curl -fsSL https://raw.githubusercontent.com/ishwarjha/lumen-product-management/main/install.sh | bash
Restart Claude Code after reinstalling.
If the agent stub exists but Lumen still does not appear, check ~/.claude/settings.json for:
"enabledPlugins": {
  "lumen@lumen-marketplace": true
}

If this entry is absent, add it and restart Claude Code.