docs: add concrete Superpowers verification checklist for Claude Code#634
Conversation
📝 WalkthroughWalkthroughAdded a troubleshooting checklist to the README's Verify Installation section, documenting steps to confirm Claude Code Superpowers activation, including triggering skill tasks, inspecting transcript logs, using Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
README.md (1)
89-89: Consider clarifying when the CLAUDE.md workaround is appropriate.Step 4 suggests adding a reminder to
CLAUDE.mdwhen "behavior is inconsistent," but it might be helpful to clarify when this workaround is appropriate versus when users should report a bug or investigate further. For example, does "inconsistent" mean occasional non-compliance, or systematic failure after confirmed plugin loading?💡 Suggested refinement for clarity
-4. If hooks are loading but behavior is inconsistent, add a short project-level reminder in `CLAUDE.md` that planning/brainstorming tasks must invoke superpowers skills. +4. If hooks load successfully but the agent occasionally doesn't invoke skills, add a short project-level reminder in `CLAUDE.md` that planning/brainstorming tasks must invoke superpowers skills. If skills are never invoked despite confirmed hook loading, this may indicate a deeper issue worth reporting.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 89, Update the Step 4 text in README.md to clarify when adding a project-level reminder in CLAUDE.md is appropriate versus when to file a bug or investigate plugin loading; specifically, state that the CLAUDE.md reminder is for intermittent/non-deterministic behavior (occasional non-compliance despite confirmed plugin loading) and not for systematic failures (persistent non-responsiveness or confirmed plugin misconfiguration), and add guidance to report a bug or run the plugin-loading diagnostic steps when behavior is repeatable or reproducible.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 83-86: The fenced code block containing the transcript starting
with "Skill(superpowers:test-driven-development)" violates MD040 by missing a
language specifier; update that triple-backtick fence to include the language
identifier text (i.e., change ``` to ```text) so the block is explicitly marked
as plain text and preserves the transcript formatting.
- Line 88: Update the README guidance to recommend using the claude CLI debug
flag instead of the session skill: replace the reference to the `/debug` skill
with the CLI flag invocation `claude --debug` so users know to run Claude Code
with `claude --debug` to view hook matching, registration, and execution entries
(the `superpowers/hooks/hooks.json` path remains correct); ensure the sentence
explicitly contrasts the session `/debug` skill versus the CLI `claude --debug`
flag for hook-level troubleshooting.
---
Nitpick comments:
In `@README.md`:
- Line 89: Update the Step 4 text in README.md to clarify when adding a
project-level reminder in CLAUDE.md is appropriate versus when to file a bug or
investigate plugin loading; specifically, state that the CLAUDE.md reminder is
for intermittent/non-deterministic behavior (occasional non-compliance despite
confirmed plugin loading) and not for systematic failures (persistent
non-responsiveness or confirmed plugin misconfiguration), and add guidance to
report a bug or run the plugin-loading diagnostic steps when behavior is
repeatable or reproducible.
| ``` | ||
| Skill(superpowers:test-driven-development) | ||
| ⎿ Successfully loaded skill | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Read the README.md file to see the context around lines 80-90
cat -n README.md | sed -n '75,95p'Repository: obra/superpowers
Length of output: 1350
🏁 Script executed:
# Search for any Claude Code documentation or transcript examples in the repository
rg -n -C3 'Skill\(' --type=mdRepository: obra/superpowers
Length of output: 1577
🏁 Script executed:
# Look for other transcript or Claude Code related documentation
rg -n -C5 'Claude Code|transcript' --type=md | head -50Repository: obra/superpowers
Length of output: 3838
🏁 Script executed:
# Check what markdown linting rules are in place
fd -e '.md' -e 'markdownlint' -e '.markdown-lint' -e 'linting' 2>/dev/null | head -20Repository: obra/superpowers
Length of output: 720
Add language identifier to fenced code block.
The code block on line 83 is missing a language specifier (violates MD040). Add text to specify the block as plain text output:
Diff
2. Confirm you see an explicit skill load in the transcript, such as:
- ```
+ ```text
Skill(superpowers:test-driven-development)
⎿ Successfully loaded skill
```Note: The transcript format shown should be verified against actual Claude Code output to ensure users see this exact signal when skills load successfully.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| Skill(superpowers:test-driven-development) | |
| ⎿ Successfully loaded skill | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 83-83: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 83 - 86, The fenced code block containing the
transcript starting with "Skill(superpowers:test-driven-development)" violates
MD040 by missing a language specifier; update that triple-backtick fence to
include the language identifier text (i.e., change ``` to ```text) so the block
is explicitly marked as plain text and preserves the transcript formatting.
| ⎿ Successfully loaded skill | ||
| ``` | ||
|
|
||
| 3. If invocation seems flaky, run Claude Code `/debug` and look for SessionStart hook registration/execution entries from `superpowers/hooks/hooks.json`. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for hooks.json files in the repository
echo "=== Searching for hooks.json files ==="
fd -t f 'hooks\.json' --hidden
echo -e "\n=== Checking hooks directory structure ==="
fd -t f . hooks/ --type f 2>/dev/null | head -20
echo -e "\n=== Looking for documentation about /debug command ==="
find . -type f \( -name "*.md" -o -name "*.txt" -o -name "*.json" \) | xargs grep -l "/debug" 2>/dev/null | head -10
echo -e "\n=== Checking README files for debug references ==="
fd -t f 'README' | xargs grep -A 3 -B 3 "debug" 2>/dev/null | head -40Repository: obra/superpowers
Length of output: 2142
🌐 Web query:
Claude Code /debug command
💡 Result:
In Claude Code, /debug [description] is a bundled skill that troubleshoots your current Claude Code session by reading the session debug log. You can optionally add a short description to focus the analysis (e.g., /debug my slash commands aren’t showing up). [1]
If you want more low-level debug output from the CLI itself, run Claude Code with claude --debug (e.g., to see detailed hook matching/execution, exit codes, and outputs). [2]
Sources: [1] [2]
Use claude --debug CLI flag instead of /debug skill for hook-level troubleshooting.
The /debug command is valid but it's a session debugging skill, not the right tool for viewing hook registration/execution entries. For hook-level debugging details, users need to run Claude Code with the claude --debug CLI flag (e.g., claude --debug) to see hook matching, registration, and execution information. The path superpowers/hooks/hooks.json is correct.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 88, Update the README guidance to recommend using the
claude CLI debug flag instead of the session skill: replace the reference to the
`/debug` skill with the CLI flag invocation `claude --debug` so users know to
run Claude Code with `claude --debug` to view hook matching, registration, and
execution entries (the `superpowers/hooks/hooks.json` path remains correct);
ensure the sentence explicitly contrasts the session `/debug` skill versus the
CLI `claude --debug` flag for hook-level troubleshooting.
Steps to check skill loading: inspect transcript, use /debug, check SessionStart hook. Upstream PR: obra#634 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 participant
Summary
Skill(...): Successfully loaded skill) users can look forVerification
git diff --checkCloses #446