Diagnose and fix common issues with insight-wave plugins. Use this skill whenever the user reports something broken, a skill not working, an error from a plugin, needs debugging help, or says things like "something is wrong", "plugin error", "skill not responding", "it doesn't work", "fix my setup", "diagnose this issue", "why isn't X working", or mentions any plugin malfunction. Also trigger when the user encounters unclear errors during plugin use — even if they don't explicitly ask for troubleshooting.
From cogni-helpnpx claudepluginhub cogni-work/insight-wave --plugin cogni-helpThis skill is limited to using the following tools:
evals/evals.jsonreferences/known-issues.mdDispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Diagnose and resolve issues with insight-wave plugins. This complements
cogni-workspace's workspace-status skill, which checks infrastructure (env vars,
themes, settings). Troubleshoot focuses on plugin-level and cross-plugin problems.
Read the workspace language from .workspace-config.json in the workspace root
(language field — "en" or "de"). Present diagnostic findings, explanations,
and fix instructions in that language (Problem → Cause → Fix stays as a pattern,
but the content within each section uses the workspace language).
If the file is missing or unreadable, detect the user's language from their message. If still unclear, default to English.
Keep in English regardless of language setting:
OK, WARN, FAIL)| This skill owns | cogni-workspace owns |
|---|---|
| Plugin availability and integrity | Workspace env vars and settings |
| Skill file validation | Theme installation and config |
| Cross-plugin dependency checks | Plugin discovery/registry |
| Progress/state file health | Session hooks and lifecycle |
| Stale state from renames | Dependency tool versions (node, gh, etc.) |
If the issue is clearly infrastructure (missing env var, broken theme), suggest
the user run /workspace-status instead.
When a user reports a problem:
Identify the scope — is this about a specific plugin, a cross-plugin workflow, or something vague? Ask if unclear.
Run targeted checks based on what the user describes. Don't run everything every time — start with the most likely cause and expand if needed.
Report findings clearly — state what's wrong, why, and how to fix it. Use the format: Problem → Cause → Fix.
Verify the plugin directory exists and has a valid plugin.json:
# Check plugin exists in marketplace
cat .claude-plugin/marketplace.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
for p in data['plugins']:
print(f\"{p['name']}: {p['source']}\")
"
Then verify the source directory exists and contains .claude-plugin/plugin.json.
For a named plugin, check that all skill directories contain a valid SKILL.md
with YAML frontmatter (at minimum: name and description fields):
# List all skills for a plugin
ls -d <plugin-dir>/skills/*/SKILL.md 2>/dev/null
Read each SKILL.md and verify the frontmatter parses correctly.
Check .claude/*.local.md files for valid YAML frontmatter structure.
Common issues:
---, bad indentation)For cogni-help specifically:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/course-status.sh" .
Many plugins require others to function. Check that dependencies are installed:
| Plugin | Requires |
|---|---|
| cogni-marketing | cogni-trends, cogni-portfolio |
| cogni-sales | cogni-portfolio, cogni-narrative |
| cogni-consulting | most other plugins |
| cogni-help:teach | all plugins (for exercises) |
Verify by checking if the required plugin directories exist in the marketplace.
After plugin renames, orphaned files may linger:
# Check for old cogni-teacher progress file
ls .claude/cogni-teacher.local.md 2>/dev/null
# Check for old cogni-diamond state
ls **/diamond-project.json 2>/dev/null
If found, suggest renaming to the current filename.
.workspace-env.sh exists and is sourced.https://github.com and check login state.When /troubleshoot is invoked with no argument, run all checks and present a
summary table:
| Check | Status | Details |
|---|---|---|
| Marketplace | OK/WARN/FAIL | N plugins registered |
| Plugin integrity | OK/WARN/FAIL | Any missing SKILL.md files |
| State files | OK/WARN/FAIL | Any corrupted or stale files |
| Dependencies | OK/WARN/FAIL | Any missing cross-plugin deps |
| Environment | OK/WARN/FAIL | Key env vars and tools |
See references/known-issues.md for a maintained list of known issues and their fixes.