Claude/analyze code 011 c uz vfq5 pyk bv5s s4fbbj q #102
Conversation
Created detailed documentation of the Superpowers codebase including: - Project overview and core philosophy - Architecture and directory structure - Skills system design and activation mechanism - Key design patterns (TDD, systematic debugging, brainstorming) - Integration points (slash commands, SessionStart hook, git worktrees) - Implementation details and code quality standards - Extension/contribution guidelines - Critical success factors and common failure modes
Created comprehensive distribution package for Claude Desktop users: PACKAGES: - Pro Setup: Full 20-skill library for Project-enabled users ($20/month) - Free Mode: Condensed workflows for free tier users PRO SETUP (pro-setup/): - 20 converted skills organized by category (core, testing, debugging, collaboration, meta) - Custom instructions for project-level protocol - Skills index with decision guide and symptom-based lookup - Complete setup guide (15-minute one-time setup) - Preserves all workflow content while removing tool dependencies FREE MODE (free-mode/): - core-workflows.md: Condensed TDD, debugging, brainstorming (~2000 words) - 3 one-page cheat sheets for quick reference - Quick-start guide (2-minute per-session setup) - Upload-based workflow for users without Projects feature CONVERSION PIPELINE (conversion/): - convert-skill.sh: Single skill converter - convert-all-skills.sh: Batch conversion script - Automated tool reference stripping and link rewriting - Maintenance documentation for future updates KEY TRANSFORMATIONS: - Skill tool → skill reference - Task tool → manual task breakdown - TodoWrite → explicit checklist tracking - SessionStart hook → custom instructions - superpowers:name → name.md (in project knowledge) DOCUMENTATION: - Main README with feature comparison and decision guide - Pro setup guide with troubleshooting and examples - Free quick-start with workflow reference - Conversion README for maintainers DELIVERABLES: - 34 total files (20 skills + 14 docs/tools) - ~15 hours of work compressed into complete package - Serves all user tiers with realistic expectations - Clear upgrade path from Free → Pro → Claude Code CRITICAL FINDING: Projects feature is Pro-only. Free users have significantly degraded experience (manual upload each session). Pro users get good experience with persistent knowledge but no automatic activation. Recommendation: Pro users for viable experience, Free for evaluation only.
WalkthroughIntroduces comprehensive documentation, setup guides, and tooling for the Superpowers Skills Library—a system providing structured workflows for AI-assisted coding. Includes specification, tier-specific guides (Free/Pro/Desktop), conversion scripts for skill format migration, skill documentation across development phases, and debugging utilities. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ 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: 15
🧹 Nitpick comments (28)
superpowers-desktop/pro-setup/custom-instructions.txt (1)
1-80: Consider softening tone to encourage buy-in.The file uses heavy emphasis throughout ("MANDATORY", "automatic failure", "NOT optional", repeated capitalization). While clarity is important, this prescriptive, inflexible tone may discourage adoption or create friction with users who feel constrained.
The underlying intent (use proven workflows consistently) is sound, but framing it as a mandate with automated enforcement may feel punitive rather than enabling.
Consider reframing key sections with language that emphasizes benefits rather than requirements:
- Instead of: "Skills are MANDATORY, not optional"
- Try: "Using relevant skills dramatically improves outcome quality and reduces rework. Choose the matching skill first."
- Instead of: "automatic failure"
- Try: "responses without skill validation are prone to oversight"
This softens tone while maintaining the expectation of consistency.
superpowers-desktop/pro-setup/skills/debugging/find-polluter.sh (1)
42-42: Consider documenting thenpm testcommand assumptions.The script assumes
npm testaccepts a file path as an argument, which may not be true for all test configurations (jest, mocha, vitest, etc. have different CLI interfaces). Consider documenting this limitation or making the test command configurable.You could add a note in the header comments or make the test command configurable:
#!/bin/bash # Bisection script to find which test creates unwanted files/state # Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern> # Example: ./find-polluter.sh '.git' 'test' # Note: Requires npm test to accept a file path argument # (Works with: Jest, Mocha when configured to; adjust TEST_CMD if needed) +TEST_CMD="${TEST_CMD:-npm test}"Then use
$TEST_CMD "$TEST_FILE"on line 42.superpowers-desktop/pro-setup/skills/collaboration/requesting-code-review.md (1)
36-36: Clarify the reference to "code-reviewer.md (in project knowledge) type".The phrase "code-reviewer.md (in project knowledge) type" is unclear. Consider revising to specify whether this refers to a task type, a template file, or another concept.
-Use manual task breakdown with code-reviewer.md (in project knowledge) type, fill template at `code-reviewer.md` +Use manual task breakdown with the code-reviewer template, fill template at `code-reviewer.md` (in project knowledge)superpowers-desktop/pro-setup/skills/testing/condition-based-waiting.md (1)
89-89: Clarify the reference to "@example.ts".The reference to "@example.ts" at line 89 is unconventional. Typically, file references use relative paths or full filenames. Consider updating to be more explicit:
-See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session. +See condition-based-waiting-example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.superpowers-desktop/pro-setup/skills/debugging/verification-before-completion.md (1)
112-117: Clarify the reference to "24 failure memories".Line 112 mentions "From 24 failure memories" but doesn't explain what this refers to. Consider adding context:
- Is this from internal testing?
- A specific project history?
- Should this be documented elsewhere?
Without context, readers may not understand the significance of this reference.
superpowers-desktop/pro-setup/skills/meta/sharing-skills.md (2)
166-182: Use markdown headings instead of emphasis for troubleshooting section.Lines 166, 170, 174, 178 use emphasis (text) as pseudo-headings. Convert these to proper markdown headings using
###for consistency and better semantic structure.-**"gh: command not found"** +### "gh: command not found"
167-167: Wrap bare URLs in angle brackets or markdown syntax.Per MD034 (markdownlint), bare URLs should be wrapped for proper markdown parsing:
-- Install GitHub CLI: https://cli.github.com/ +- Install GitHub CLI: <https://cli.github.com/>Apply the same fix to line 172.
Also applies to: 172-172
superpowers-desktop/pro-setup/skills/testing/testing-anti-patterns.md (1)
20-20: Add language specifiers to fenced code blocks.Multiple code blocks lack language identifiers (MD040). For example, line 20 uses
```but should specify the content language. Most blocks here are pseudocode/plain text, but consider adding explicit identifiers:-``` +```text 1. NEVER test mock behavior 2. NEVER add test-only methods to production classes 3. NEVER mock without understanding dependencies -``` +```Also applies to: 58-58, 109-109, 158-158, 217-217, 236-236, 248-248
superpowers-desktop/pro-setup/skills/collaboration/finishing-a-development-branch.md (1)
24-27: Clarify test command syntax.Line 26 lists command alternatives separated by
/, but this won't execute as written. The actual command depends on the project's build system. Consider clarifying:-# Run project's test suite -npm test / cargo test / pytest / go test ./... +# Run project's test suite (varies by project type) +# npm test (Node.js) +# pytest (Python) +# cargo test (Rust) +# go test ./... (Go)superpowers-desktop/pro-setup/skills/core/using-superpowers.md (2)
8-14: Consider using markdown blockquote instead of HTML tags for emphasis.Lines 8-14 use raw HTML
<EXTREMELY-IMPORTANT>tags. While visually effective, markdown blockquotes provide better portability:-<EXTREMELY-IMPORTANT> +> **EXTREMELY IMPORTANT** + If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST read the skill. IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT. This is not negotiable. This is not optional. You cannot rationalize your way out of this. -</EXTREMELY-IMPORTANT> +>
63-63: Fix numbering inconsistency and redundant phrasing.Line 63 has redundant text: "explicit checklist tracking tracking = steps get skipped" (tracking appears twice). Line 98–101 has numbering issue: steps 1, 3, 4 with no step 2. Apply this fix:
-Every time. The overhead of explicit checklist tracking is tiny compared to the cost of missing steps. +Every time. The overhead of tracking checklist items explicitly is tiny compared to the cost of missing steps. -**Starting any task:** -1. If relevant skill exists → Use the skill -3. Announce you're using it -4. Follow what it says +**Starting any task:** +1. If relevant skill exists → Use the skill +2. Announce you're using it +3. Follow what it saysAlso applies to: 101-101
superpowers-desktop/pro-setup/skills/core/systematic-debugging.md (2)
20-20: Add language specifiers to code blocks.Lines 20 and 79 have fenced code blocks without language identifiers (MD040). Line 20 should be
text(pseudocode rules), line 79 should bebash:-``` +```text NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST -``` +```and
-``` +```bash # Layer 1: Workflow -``` +```Also applies to: 79-79
45-45: Minor: Consider tightening phrasing for consistency.Line 45 uses "in a hurry"; for conciseness, consider "rushing" to align with line 46's "rushing guarantees rework":
-- Manager wants it fixed NOW (systematic is faster than thrashing) +- You're under time pressure (systematic is faster than thrashing)This is a minor prose suggestion.
superpowers-desktop/conversion/README.md (1)
56-56: Add language specifier to output structure code block.Line 56 code block should specify language:
-``` +``` pro-setup/skills/ ├── core/ (4 skills) @@ -62,7 +62,7 @@ pro-setup/skills/ └── meta/ (3 skills) -``` +```This is a tree structure, so
textwould be appropriate.superpowers-desktop/conversion/convert-all-skills.sh (1)
8-8: Hardcoded source path may cause failures on different systems.Line 8 hardcodes the source path:
SKILLS_DIR="/home/user/superpowers/skills"This assumes the plugin repo is cloned to a specific location. If users clone to different paths, the script will fail silently (find no files). Consider making this configurable:
SKILLS_DIR="${PLUGIN_SKILLS_DIR:-/home/user/superpowers/skills}"Or accept it as an argument:
SKILLS_DIR="${1:-/home/user/superpowers/skills}"Verify this path works for intended use cases, or update to support alternate clone locations.
superpowers-desktop/free-mode/QUICK-START.md (1)
366-366: Convert emphasis to proper heading.Line 366 uses
**Ready to start?**as emphasis, but this introduces a new section and should use heading syntax (## Ready to Start?) for proper document hierarchy.- **Ready to start?** + ## Ready to Start?superpowers-desktop/free-mode/core-workflows.md (1)
16-16: Convert emphasis to proper headings.Lines 16 and 97 use bold emphasis for "The Iron Law" when these should be subheadings to maintain proper document hierarchy.
## 1. Test-Driven Development (TDD) - ### The Iron Law - **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST** + ### The Iron Law + NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST ## 2. Systematic Debugging - ### The Iron Law - **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST** + ### The Iron Law + NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRSTAlso applies to: 97-97
superpowers-desktop/pro-setup/skills/collaboration/writing-plans.md (1)
67-72: Convert emphasis to proper headings.Lines 67, 79, and 84 use bold emphasis for section headers. These should use heading hierarchy (###) instead.
- **Step 1: Write the failing test** + ### Step 1: Write the Failing Test - **Step 2: Run test to verify it fails** + ### Step 2: Run Test to Verify It Fails - **Step 3: Write minimal implementation** + ### Step 3: Write Minimal Implementation - **Step 4: Run test to verify it passes** + ### Step 4: Run Test to Verify It Passes - **Step 5: Commit** + ### Step 5: CommitAlso applies to: 79-82, 84-89
superpowers-desktop/pro-setup/skills/collaboration/dispatching-parallel-agents.md (1)
165-165: Convert emphasis to proper headings.Four lines use bold emphasis for section headers that should be formatted as subheadings for proper document structure.
- ## Key Benefits + ### Key Benefits - 1. **Parallelization** - Multiple investigations happen simultaneously + 1. Parallelization - Multiple investigations happen simultaneously - ## Verification + ### Verification - ## Real-World Impact + ### Real-World ImpactAlso applies to: 169-169, 173-173, 177-177
superpowers-desktop/pro-setup/skills/debugging/root-cause-tracing.md (1)
42-44: Specify language for fenced code block or use alternative diagram format.Line 42 begins a fenced code block without a language specifier. Since this appears to be a text placeholder, consider either specifying a language (e.g.,
```text) or using thedotsyntax (as you do elsewhere for diagrams). This improves markdown consistency and enables proper syntax highlighting.superpowers-desktop/pro-setup/SETUP.md (2)
68-86: Standardize test section headers to proper markdown headings.The test sections (lines 68, 74, 81) use bold emphasis (
**Test 1: ...**, **Test 2: ...**) instead of proper markdown headings. Converting these to heading level 4 (#### Test 1: ...) improves document structure and enables better markdown rendering, outline generation, and accessibility.Apply this diff to standardize headers:
-**Test 1: Skill Discovery** +#### Test 1: Skill Discovery
69-69: Add language specifiers to fenced code blocks.Multiple code blocks throughout the file lack language specifiers, which limits syntax highlighting and documentation clarity. Lines 69, 75, 82, 95, 153, 203, 219, 232 each contain a code block. Consider:
- Using
```markdownfor example conversations and checklist blocks- Using
```bashfor shell command examples- Using
```plaintextor plain text format for sample outputThis improves readability and enables proper syntax highlighting in rendering tools.
Also applies to: 75-75, 82-82, 95-95, 153-153, 203-203, 219-219, 232-232
superpowers-desktop/pro-setup/skills/core/brainstorming.md (1)
21-21: Use hyphen in compound adjective.Line 21 mentions "multiple choice questions" — when used as a compound adjective before a noun, this should be "multiple-choice questions". This is a minor grammar refinement that follows standard English style conventions.
superpowers-desktop/pro-setup/skills/core/test-driven-development.md (2)
208-288: Convert rationalization headers to proper markdown structure.The "Why Order Matters" section (lines 210-273) uses bold emphasis for subsection headers (lines 210, 220, 230, 238, 248) instead of heading levels. While these headers may be stylistically intentional for the "rationalization" framing, converting them to heading level 4 (
####) would improve document structure without sacrificing emphasis. Example:-**"I'll write tests after to verify it works"** +#### "I'll write tests after to verify it works"Similarly, the "Red Flags" section (lines 274-289) uses bold emphasis on lines 296, 304, 310, 320 that could be converted to proper headings.
35-35: Specify languages for fenced code blocks.Three code blocks lack language specifiers:
- Line 35: Code block showing "Iron Law" — likely
textorplaintext- Line 92: Code block after "Good" label — likely
typescript- Line 361: Code block showing "Final Rule" — likely
textorplaintextAdding language tags enables syntax highlighting and improves documentation clarity.
Also applies to: 92-92, 361-361
superpowers-desktop/pro-setup/skills/index.md (1)
27-27: Reduce repetitive phrasing in quick decision guide.The decision guide uses "I want to" or "I need to" repeatedly across lines 27, 35, 37 and similar entries. Consider varying the phrasing for better readability:
-**I want to submit code for review** → `collaboration/requesting-code-review.md` -**I want to create a new skill** → `meta/writing-skills.md` -**I want to contribute a skill back** → `meta/sharing-skills.md` +**Ready to submit code for review** → `collaboration/requesting-code-review.md` +**Creating a new skill** → `meta/writing-skills.md` +**Contributing a skill back** → `meta/sharing-skills.md`This improves document flow without sacrificing clarity or consistency.
Also applies to: 35-35, 37-37
superpowers-desktop/pro-setup/skills/collaboration/using-git-worktrees.md (1)
43-43: Specify bash language for shell script code blocks.Multiple fenced code blocks containing shell commands lack language specifiers. Lines 43, 66, 87, 113 should all use
```bashto enable proper syntax highlighting and document formatting:-``` +```bash # Check in priority order ls -d .worktrees 2>/dev/nullThis improves readability and consistency across the documentation.
Also applies to: 66-66, 87-87, 113-113
claude.md (1)
155-157: Specify bash language for shell script code block.Line 155 contains a shell command example without a language specifier. Use
```bashto enable syntax highlighting:-``` +```bash /plugin marketplace add obra/superpowers-marketplace
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (35)
claude.md(1 hunks)superpowers-desktop/README.md(1 hunks)superpowers-desktop/conversion/README.md(1 hunks)superpowers-desktop/conversion/convert-all-skills.sh(1 hunks)superpowers-desktop/conversion/convert-skill.sh(1 hunks)superpowers-desktop/free-mode/QUICK-START.md(1 hunks)superpowers-desktop/free-mode/cheat-sheets/brainstorming-cheat-sheet.md(1 hunks)superpowers-desktop/free-mode/cheat-sheets/debugging-cheat-sheet.md(1 hunks)superpowers-desktop/free-mode/cheat-sheets/tdd-cheat-sheet.md(1 hunks)superpowers-desktop/free-mode/core-workflows.md(1 hunks)superpowers-desktop/pro-setup/SETUP.md(1 hunks)superpowers-desktop/pro-setup/custom-instructions.txt(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/dispatching-parallel-agents.md(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/executing-plans.md(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/finishing-a-development-branch.md(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/receiving-code-review.md(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/requesting-code-review.md(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/subagent-driven-development.md(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/using-git-worktrees.md(1 hunks)superpowers-desktop/pro-setup/skills/collaboration/writing-plans.md(1 hunks)superpowers-desktop/pro-setup/skills/core/brainstorming.md(1 hunks)superpowers-desktop/pro-setup/skills/core/systematic-debugging.md(1 hunks)superpowers-desktop/pro-setup/skills/core/test-driven-development.md(1 hunks)superpowers-desktop/pro-setup/skills/core/using-superpowers.md(1 hunks)superpowers-desktop/pro-setup/skills/debugging/defense-in-depth.md(1 hunks)superpowers-desktop/pro-setup/skills/debugging/find-polluter.sh(1 hunks)superpowers-desktop/pro-setup/skills/debugging/root-cause-tracing.md(1 hunks)superpowers-desktop/pro-setup/skills/debugging/verification-before-completion.md(1 hunks)superpowers-desktop/pro-setup/skills/index.md(1 hunks)superpowers-desktop/pro-setup/skills/meta/sharing-skills.md(1 hunks)superpowers-desktop/pro-setup/skills/meta/testing-skills-with-subagents.md(1 hunks)superpowers-desktop/pro-setup/skills/meta/writing-skills.md(1 hunks)superpowers-desktop/pro-setup/skills/testing/condition-based-waiting-example.ts(1 hunks)superpowers-desktop/pro-setup/skills/testing/condition-based-waiting.md(1 hunks)superpowers-desktop/pro-setup/skills/testing/testing-anti-patterns.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
superpowers-desktop/pro-setup/skills/core/brainstorming.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...ime to refine the idea - Prefer multiple choice questions when possible, but open...
(QB_NEW_EN_HYPHEN)
superpowers-desktop/free-mode/core-workflows.md
[grammar] ~7-~7: Ensure spelling is correct
Context: ...ck Reference - Implementing features/bugfixes → Test-Driven Development (Section 1)...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
superpowers-desktop/free-mode/QUICK-START.md
[style] ~127-~127: ‘Refer Back’ might be wordy. Consider a shorter alternative.
Context: ...id input ``` Update as you go. ### 4. Refer Back to the Document During the conversatio...
(EN_WORDINESS_PREMIUM_REFER_BACK)
superpowers-desktop/pro-setup/skills/testing/condition-based-waiting.md
[grammar] ~34-~34: Ensure spelling is correct
Context: ...ass sometimes, fail under load) - Tests timeout when run in parallel - Waiting for asyn...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
superpowers-desktop/pro-setup/skills/index.md
[style] ~27-~27: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...collaboration/executing-plans.md I want to submit code for review → `collaborati...
(REP_WANT_TO_VB)
[style] ~35-~35: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...finishing-a-development-branch.md **I want to create a new skill** →meta/writing-sk...
(REP_WANT_TO_VB)
[style] ~37-~37: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...skill** → meta/writing-skills.md I want to contribute a skill back → `meta/shari...
(REP_WANT_TO_VB)
superpowers-desktop/pro-setup/skills/meta/writing-skills.md
[grammar] ~291-~291: Ensure spelling is correct
Context: ...ists - Labels without semantic meaning (step1, helper2) See @graphviz-conventions.do...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~376-~376: ‘under stress’ might be wordy. Consider a shorter alternative.
Context: ...s? - Pressure scenarios: Do they comply under stress? - Multiple pressures combined: time + ...
(EN_WORDINESS_PREMIUM_UNDER_STRESS)
[style] ~548-~548: To elevate your writing, try using a synonym here.
Context: ...e"]; ``` Why bad: Can't copy-paste, hard to read ### ❌ Generic Labels helper1, ...
(HARD_TO)
superpowers-desktop/pro-setup/skills/core/test-driven-development.md
[grammar] ~256-~256: Use a hyphen to join words.
Context: ...ests after ≠ TDD. You get coverage, lose proof tests work. ## Common Rationaliza...
(QB_NEW_EN_HYPHEN)
[style] ~269-~269: To elevate your writing, try using a synonym here.
Context: ...clear" | Listen to test. Hard to test = hard to use. | | "TDD will slow me down" | T...
(HARD_TO)
superpowers-desktop/pro-setup/skills/meta/testing-skills-with-subagents.md
[grammar] ~332-~332: Ensure spelling is correct
Context: ...ed flags list - [ ] Updated description ith violation symptoms - [ ] Re-tested - ag...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
superpowers-desktop/pro-setup/SETUP.md
[style] ~266-~266: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...ills ### Adapting Custom Instructions Feel free to modify custom-instructions.txt to: - ...
(FEEL_FREE_TO_STYLE_ME)
superpowers-desktop/pro-setup/skills/core/systematic-debugging.md
[style] ~45-~45: ‘in a hurry’ might be wordy. Consider a shorter alternative.
Context: ...ple bugs have root causes too) - You're in a hurry (rushing guarantees rework) - Manager w...
(EN_WORDINESS_PREMIUM_IN_A_HURRY)
🪛 markdownlint-cli2 (0.18.1)
superpowers-desktop/pro-setup/skills/debugging/verification-before-completion.md
20-20: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
28-28: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
81-81: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
87-87: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
93-93: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
99-99: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
105-105: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/free-mode/cheat-sheets/tdd-cheat-sheet.md
4-4: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
8-8: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/free-mode/core-workflows.md
16-16: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
97-97: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
superpowers-desktop/free-mode/QUICK-START.md
60-60: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
73-73: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
87-87: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
116-116: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
130-130: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
203-203: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
268-268: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
346-346: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
366-366: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
superpowers-desktop/pro-setup/skills/collaboration/subagent-driven-development.md
43-43: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
66-66: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
87-87: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
113-113: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/free-mode/cheat-sheets/brainstorming-cheat-sheet.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
55-55: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/collaboration/dispatching-parallel-agents.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
55-55: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
119-119: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
165-165: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
169-169: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
173-173: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
177-177: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
claude.md
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/debugging/root-cause-tracing.md
42-42: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/conversion/README.md
56-56: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/meta/writing-skills.md
76-76: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
297-297: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
321-321: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
328-328: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
336-336: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
347-347: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
455-455: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/testing/testing-anti-patterns.md
20-20: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
109-109: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
158-158: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
217-217: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
236-236: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
248-248: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/collaboration/using-git-worktrees.md
43-43: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
66-66: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
87-87: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
113-113: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/collaboration/receiving-code-review.md
18-18: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
44-44: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
53-53: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
70-70: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
92-92: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
104-104: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
136-136: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
181-181: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
187-187: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
193-193: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
199-199: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/collaboration/executing-plans.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
55-55: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/core/test-driven-development.md
35-35: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
92-92: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
210-210: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
220-220: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
230-230: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
238-238: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
248-248: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
296-296: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
304-304: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
310-310: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
320-320: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
361-361: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/meta/testing-skills-with-subagents.md
204-204: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/collaboration/requesting-code-review.md
53-53: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/meta/sharing-skills.md
166-166: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
167-167: Bare URL used
(MD034, no-bare-urls)
170-170: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
172-172: Bare URL used
(MD034, no-bare-urls)
174-174: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
178-178: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
superpowers-desktop/pro-setup/SETUP.md
68-68: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
69-69: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
74-74: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
75-75: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
81-81: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
82-82: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
95-95: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
153-153: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
203-203: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
219-219: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
232-232: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
334-334: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
superpowers-desktop/pro-setup/skills/core/systematic-debugging.md
20-20: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
79-79: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/pro-setup/skills/collaboration/writing-plans.md
67-67: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
72-72: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
79-79: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
84-84: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
90-90: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/free-mode/cheat-sheets/debugging-cheat-sheet.md
4-4: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
8-8: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
64-64: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
superpowers-desktop/README.md
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (28)
superpowers-desktop/pro-setup/custom-instructions.txt (1)
5-13: Review comment contains incorrect circular reference claim; primary concerns are invalid.The review comment states that custom-instructions.txt creates a circular reference with using-superpowers.md because line 29 recommends reading using-superpowers.md "first." This is incorrect.
Why not circular:
- using-superpowers.md is a skill file documenting mandatory workflows for using skills
- custom-instructions.txt is the protocol file that tells Claude to check for and use available skills
- custom-instructions.txt is designed as the entry point and correctly directs skill usage, including referencing using-superpowers.md when needed
- Line 30's "Read this first to understand the system" means understanding that skills are mandatory—not a circular redirect
On "project knowledge":
The term is contextual, not formally defined, but clearly references the skills collection (superpowers-desktop/pro-setup/skills/*). This is conventional documentation phrasing and poses no practical confusion; developers will locate skills by browsing the referenced directory structure.On enforcement:
The phrase "automatic failure" lacks an operationalization mechanism (no validator, consequence, or explicit scope). However, this reads as ideological language emphasizing importance rather than a critical ambiguity requiring resolution. The protocol is clear: check for skills, use them, announce them. The consequences of skipping this are implicit.Likely an incorrect or invalid review comment.
superpowers-desktop/pro-setup/skills/debugging/find-polluter.sh (5)
1-5: Clear purpose and usage documentation.
6-12: Good defensive argument validation.
14-19: Clear status messaging.
45-58: Good error reporting for polluter detection.The detailed output (test file, pollution target, directory listing, suggested investigation commands) will be helpful for debugging.
61-63: Appropriate exit code and success messaging.superpowers-desktop/free-mode/cheat-sheets/debugging-cheat-sheet.md (1)
1-77: Excellent systematic debugging guide!This cheat sheet provides a clear, actionable framework for debugging with good examples and practical guidance. The 4-phase process, red flags, and common mistakes table are particularly valuable for preventing ad-hoc debugging approaches.
superpowers-desktop/free-mode/cheat-sheets/tdd-cheat-sheet.md (1)
1-68: Solid TDD reference guide with clear examples.The cheat sheet effectively communicates TDD principles with a clear RED-GREEN-REFACTOR cycle. The TypeScript example is well-constructed and demonstrates proper test structure with async operations and multiple assertions.
superpowers-desktop/README.md (3)
1-285: Comprehensive and well-organized README.The README provides excellent guidance for users across different tiers (Free/Pro/Claude Code) with clear feature comparisons, migration paths, and decision guides. The structure makes it easy for users to find the right path for their needs.
30-30: The referenced setup guide files exist—no action required.Both
pro-setup/SETUP.mdandfree-mode/QUICK-START.mdare present in the repository and properly referenced in the README.
237-239: External repository links verified as accessible.All three GitHub repository links in the documentation are correct and accessible (HTTP 200 responses confirmed for all URLs).
superpowers-desktop/pro-setup/skills/testing/condition-based-waiting-example.ts (1)
1-158: Well-structured example utilities for test stability.The three waiting utilities demonstrate a clean pattern for replacing arbitrary timeouts with condition-based polling. The implementation is correct, readable, and the included usage examples (lines 138-158) effectively illustrate the problem and solution. The 10ms polling interval is reasonable for test scenarios.
superpowers-desktop/pro-setup/skills/testing/condition-based-waiting.md (1)
1-122: Excellent practical documentation for eliminating flaky tests.The documentation clearly explains the problem of arbitrary timeouts and provides concrete patterns for condition-based waiting. The before/after examples, implementation details, and real-world impact metrics (lines 117-121) make this immediately actionable. The inclusion of when arbitrary timeouts ARE correct (lines 102-115) shows good balance.
superpowers-desktop/pro-setup/skills/debugging/verification-before-completion.md (1)
1-141: Strong and necessary guidance for verification discipline.This documentation establishes critical verification requirements with appropriate emphasis. The gate function pattern (lines 28-40), common failures table, and rationalization prevention section provide concrete, actionable guidance. The strong tone is justified given the critical nature of verification in development workflows.
superpowers-desktop/free-mode/cheat-sheets/brainstorming-cheat-sheet.md (1)
1-101: Well-structured brainstorming guide with practical examples.The cheat sheet provides a clear, systematic approach to collaborative design with helpful examples of questions and documentation. The key principles (lines 39-45) and good question patterns (lines 47-60) give concrete guidance, while the design section example (lines 62-83) demonstrates the expected output format.
superpowers-desktop/pro-setup/skills/meta/sharing-skills.md (1)
1-196: Skill documentation is well-structured and actionable.The sharing workflow is clear, commands are concrete, the example is thorough, and prerequisites are explicit. The "Keep personal when" and "Do NOT batch multiple skills" sections provide good guardrails. Content is well-suited for the Desktop environment.
superpowers-desktop/pro-setup/skills/testing/testing-anti-patterns.md (1)
1-304: Comprehensive anti-pattern documentation with actionable gate functions.The five anti-patterns are well-explained with concrete examples (good vs bad), clear rationale, and decision-tree gate functions. The quick reference table and red flags provide effective visual guides. Integration with TDD and reference to related skills (root-cause-tracing, verification-before-completion, defense-in-depth) shows good cohesion with the broader skill ecosystem. Content is practical and addresses real testing pitfalls.
superpowers-desktop/pro-setup/skills/collaboration/finishing-a-development-branch.md (1)
20-193: Workflow is well-structured with strong safety guardrails.The step-by-step process is clear: verify tests → determine base branch → present structured options → execute choice → clean up. Key safeguards are in place: confirmation required for discard (line 125), worktree cleanup only for specific options (line 175), test verification before offering merge/PR. The quick reference table and common mistakes section reinforce correct behavior. Integration points with other workflows are clearly noted.
superpowers-desktop/pro-setup/skills/core/using-superpowers.md (1)
1-103: Mandatory workflow protocol is clear and well-justified.The five-step First Response Protocol establishes a non-negotiable skill-discovery process. The Common Rationalizations section (lines 36–50) effectively counteracts common shortcuts and reinforces discipline. Clear distinction between rigid skills (TDD, debugging) and flexible skills (architecture, naming) acknowledges contextual variation. Desktop note transparency helps users understand adaptation limitations. Tone is appropriately strict for a mandatory workflow framework.
superpowers-desktop/pro-setup/skills/core/systematic-debugging.md (1)
1-297: Four-phase debugging framework is rigorous and well-integrated.The Iron Law (Phase 1 before fixes) is enforced throughout. Evidence gathering for multi-component systems (lines 74–111) with concrete example (CI → build → signing layers) is particularly valuable. Phase 3 emphasizes single-variable hypothesis testing. Phase 4 includes critical safeguard: stop after 3 failed fixes and question architecture (lines 196–215). Integration with root-cause-tracing, test-driven-development, and defense-in-depth skills shows good ecosystem cohesion. Red flags and common rationalizations reinforce discipline. Quick reference table aids workflow recall.
superpowers-desktop/conversion/README.md (1)
1-242: Conversion documentation is comprehensive and operationally sound.Clear purpose statement, usage examples for both scripts, concrete maintenance workflow, well-organized conversion rules tables, and practical troubleshooting section. The automated and manual verification checklists (lines 146–170) ensure quality conversions. Version tracking guidance (lines 172–193) and future improvements (lines 228–235) show forward-thinking. Documentation appropriately emphasizes keeping free-mode in sync and the distinction between core and non-core skills.
superpowers-desktop/conversion/convert-skill.sh (3)
53-60: Verify sed frontmatter pattern matches actual YAML structure.The pattern to insert the Desktop note after frontmatter assumes exactly
---\nbetween opening and closing markers. This may not match frontmatters with content. The pattern:/^---$/ { N /^---\n$/ ...requires the closing
---to be on the next line after opening---. For files with YAML content between markers, this pattern won't match. Verify this works with actual source files, or use a more robust pattern like:# Match until second occurrence of --- at line start 1,/^---$/!b /^---$/{ n; /^---$/!b; }Consider testing against a sample plugin skill file to confirm the pattern works.
24-61: Sed transformations appear correct and comprehensive.The sed script implements all documented conversion rules: tool references (Skill/Task/TodoWrite), cross-reference rewrites (superpowers: format), REQUIRED SUB-SKILL updates, and @file references. Transformations are appropriately escaped and cover the cases documented in README (lines 111–128 of conversion/README.md). The order of transformations is logical (tool refs first, cross-refs second, frontmatter append last).
1-62: Script uses good defensive practices with set -euo pipefail, input validation, and error messages.Proper handling of argument count and file existence. Output directory creation is correct. Success message provides feedback. The sed script is complex but documented well. Main concern is verifying the YAML frontmatter append pattern works correctly for actual plugin skill files.
superpowers-desktop/conversion/convert-all-skills.sh (2)
21-102: Skill category lists are organized and complete.All five categories (core, testing, debugging, collaboration, meta) are defined with appropriate skill lists. Counts match README (core: 4, testing: 2, debugging: 3, collaboration: 8, meta: 3). The use of bash arrays and explicit category loops makes the script maintainable. Defensive file checks before copying prevent errors if source files don't exist.
116-124: Summary output is helpful for validation.The final summary (lines 117–123) lists counts by category and the output directory, which aids in verifying successful conversion and locating results.
superpowers-desktop/pro-setup/skills/debugging/defense-in-depth.md (1)
1-128: Well-structured documentation with clear examples.The documentation effectively presents a four-layer validation pattern with concrete TypeScript examples and a compelling real-world case study. The progression from concept through application to results is logical and persuasive. No substantive issues identified.
claude.md (1)
1-355: Comprehensive project specification with clear architecture and philosophy.This documentation effectively establishes the Superpowers project scope, mandatory skills system, and design patterns. The architecture is well-explained, the iron laws (TDD, systematic debugging) are appropriately emphasized, and the real-world success metrics add credibility. The integration of skill discovery, mandatory workflow enforcement, and TodoWrite tracking creates a cohesive system.
Well done on the thoroughness and clarity of the specification. The project is well-positioned for adoption and contribution.
| ```typescript | ||
| // RED: Write failing test | ||
| test('retries failed operations 3 times', async () => { | ||
| let attempts = 0; | ||
| const operation = () => { | ||
| attempts++; | ||
| if (attempts < 3) throw new Error('fail'); | ||
| return 'success'; | ||
| }; | ||
|
|
||
| const result = await retryOperation(operation); | ||
|
|
||
| expect(result).toBe('success'); | ||
| expect(attempts).toBe(3); | ||
| }); | ||
|
|
||
| // Verify RED: Run test → FAIL | ||
|
|
||
| // GREEN: Write minimal implementation | ||
| async function retryOperation<T>(fn: () => Promise<T>): Promise<T> { | ||
| for (let i = 0; i < 3; i++) { | ||
| try { | ||
| return await fn(); | ||
| } catch (e) { | ||
| if (i === 2) throw e; | ||
| } | ||
| } | ||
| throw new Error('unreachable'); | ||
| } | ||
|
|
||
| // Verify GREEN: Run test → PASS | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language specifier to TypeScript code block.
- ```
+ ```typescript
// RED: Write failing test
test('retries failed operations 3 times', async () => {🤖 Prompt for AI Agents
superpowers-desktop/free-mode/core-workflows.md around lines 59 to 90: the code
block opening fence is missing a language specifier; update the opening fence
from ``` to ```typescript (and likewise ensure any other fenced blocks in this
section use the correct language tag) so the TypeScript snippet is properly
highlighted and rendered.
| ``` | ||
| You: [Upload core-workflows.md] | ||
| "Use TDD from core-workflows.md to implement user validation" | ||
|
|
||
| Claude: "I'll follow the RED-GREEN-REFACTOR cycle. | ||
|
|
||
| RED: Writing failing test first..." | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language specifiers to all code blocks.
Eight code blocks lack language identifiers. Most contain conversational examples or file structures that should use text or appropriate language markers.
- ```
+ ```text
You: [Upload core-workflows.md]
- ```
+ ```text
You: [Upload core-workflows.md]
- ```
+ ```text
You: [Upload core-workflows.md]
- ```
+ ```text
**My TDD Checklist:**
- ```
+ ```text
"What does systematic debugging say about Phase 2?"
- ```
+ ```text
"According to core-workflows.md, what should we do first?"
- ```
+ ```text
[New conversation]
- ```
+ ```text
free-mode/Also applies to: 73-81, 87-94, 116-123, 130-133, 203-207, 268-295, 346-354
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
60-60: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In superpowers-desktop/free-mode/QUICK-START.md around lines 60-67 (and also
apply to ranges 73-81, 87-94, 116-123, 130-133, 203-207, 268-295, 346-354),
several triple-backtick code blocks are missing language specifiers; update each
fence to include an appropriate language tag (use text for conversational
examples or file-structure snippets, or a specific language when applicable) so
each block starts with ```text (or ```json/```bash/etc. where appropriate) and
closes with ``` to ensure proper syntax highlighting and rendering.
| - **using-superpowers.md**: Establishes mandatory workflows | ||
| - Read this first to understand the system |
There was a problem hiding this comment.
Address circular reference with using-superpowers.md.
Line 29–30 recommends reading using-superpowers.md "first to understand the system," but this file (custom-instructions.txt) itself appears to be the entry point for users. This creates a circular dependency where the first document tells users to read another document first.
Restructure the guidance so the reading order is clear and unambiguous.
Consider reordering or clarifying:
- Should
using-superpowers.mdcome before this file? - Or should this file include a brief summary sufficient for users to proceed?
- Add an explicit "Recommended reading order" section if multiple entry points exist.
🤖 Prompt for AI Agents
In superpowers-desktop/pro-setup/custom-instructions.txt around lines 29 to 30,
the instruction telling users to "Read this first" and pointing to
using-superpowers.md creates a circular dependency because
custom-instructions.txt is the apparent entry point; fix by clarifying and
ordering the guides: either make using-superpowers.md the true entry point (move
it before or prepend a short index and update this file to say "See
using-superpowers.md first" with link), or keep custom-instructions.txt as the
entry point and include a brief summary of the essential content from
using-superpowers.md plus an explicit "Recommended reading order" list that
shows the exact sequence of files to read; update the text to remove ambiguous
"first" language and replace with the chosen unambiguous directive and reading
order.
|
|
||
| ## Critical Rules | ||
|
|
||
| 1. **Skills are MANDATORY, not optional**: If a skill exists for your task, you MUST use it |
There was a problem hiding this comment.
Address practical feasibility and edge cases.
The protocol mandates skill usage ("If a skill exists for your task, you MUST use it") and applies user instructions as goals rather than permission to skip workflows (lines 69).
However, the document doesn't address:
- What if no relevant skill exists for a task?
- What if a skill conflicts with explicit user instructions or constraints?
- How do users distinguish between "this task is simple" vs. "this task genuinely doesn't fit a skill"?
Without clear guidance on edge cases and conflicts, the protocol may be difficult to apply consistently in practice.
Add a "Handling Edge Cases" section that addresses:
- No matching skill: What should the response be?
- Conflicting guidance: How to resolve conflicts between skill requirements and user urgency/constraints?
- Judgment boundaries: What counts as a valid reason to modify or skip a workflow?
Also applies to: 65-69
🤖 Prompt for AI Agents
In superpowers-desktop/pro-setup/custom-instructions.txt around lines 34 and
65-69, the document mandates mandatory skill usage but lacks guidance for edge
cases; add a new "Handling Edge Cases" section that (1) defines the response
when no matching skill exists (e.g., explicitly state to proceed with
best-effort standard workflow, log/flag the missing skill, and notify the user),
(2) prescribes conflict resolution between skill requirements and explicit user
constraints or urgency (e.g., prioritize explicit user constraints, document the
deviation, and escalate when necessary), and (3) establishes clear judgment
boundaries for when to modify or skip a workflow (e.g., list allowed reasons
such as missing skill, safety/legal constraints, irreconcilable user
constraints, plus required approvals/logging); keep the text brief, procedural,
and include examples for each bullet so implementers can apply them
consistently.
|
|
||
| "Multiple failures?" -> "Are they independent?" [label="yes"]; | ||
| "Are they independent?" -> "Single agent investigates all" [label="no - related"]; | ||
| "Are they independent?" -> "Can they work in parallel?" [label="yes"]; |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language specifiers to code blocks.
Three code blocks lack language identifiers.
- ```
+ ```text
digraph when_to_use {
- ```
+ ```typescript
// In Claude Code / AI environment
- ```
+ ```text
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:Also applies to: 55-55, 119-119
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In
superpowers-desktop/pro-setup/skills/collaboration/dispatching-parallel-agents.md
around lines 30, 55, and 119, three fenced code blocks are missing language
specifiers; update each opening ``` fence to include the appropriate language
(e.g., ```text or ```typescript) matching the block content so syntax
highlighting and tooling work correctly—specifically change the fence at line 30
to ```typescript for the Claude Code comment or ```text if it's plain text, and
similarly add ```text or the correct language identifier at lines 55 and 119 to
the respective code block openings.
| ```markdown | ||
| # [Feature Name] Implementation Plan | ||
|
|
||
| > **For Claude:** REQUIRED SUB-SKILL: Use executing-plans.md (in project knowledge) to implement this plan task-by-task. | ||
|
|
||
| **Goal:** [One sentence describing what this builds] | ||
|
|
||
| **Architecture:** [2-3 sentences about approach] | ||
|
|
||
| **Tech Stack:** [Key technologies/libraries] | ||
|
|
||
| --- | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language specifiers to code blocks.
The markdown template blocks should include language specifications for proper rendering.
- ```markdown
+ ```markdown
# [Feature Name] Implementation Plan
- ```markdown
+ ```markdown
### Task N: [Component Name]Also applies to: 51-90
🤖 Prompt for AI Agents
In superpowers-desktop/pro-setup/skills/collaboration/writing-plans.md around
lines 35 to 47 (and also apply same change to lines 51-90), the fenced code
blocks lack explicit language specifiers which prevents proper syntax
highlighting; update each triple-backtick block to include the correct language
tag (e.g., ```markdown for markdown blocks, or the appropriate language for any
other code snippets) so all code/markup blocks render with proper highlighting
across viewers.
| # Get list of test files | ||
| TEST_FILES=$(find . -path "$TEST_PATTERN" | sort) | ||
| TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ') | ||
|
|
||
| echo "Found $TOTAL test files" | ||
| echo "" |
There was a problem hiding this comment.
Fix the find pattern syntax and line counting.
The find command doesn't support bash glob syntax like **. The -path option uses fnmatch patterns. Additionally, counting with wc -l returns 1 for empty input (the trailing newline), not 0.
Apply this diff to fix both issues:
-# Get list of test files
-TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
-TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+# Get list of test files
+TEST_FILES=$(find . -name "*.test.ts" -o -name "*.test.js" | sort)
+TOTAL=$(find . -name "*.test.ts" -o -name "*.test.js" | wc -l)
+
+# Alternatively, if you need more flexible patterns, use -regex:
+# TEST_FILES=$(find . -regex "$TEST_PATTERN" | sort)
+# TOTAL=$(find . -regex "$TEST_PATTERN" | wc -l)The example usage should also be updated to reflect the corrected pattern:
-# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+# Example: ./find-polluter.sh '.git' 'test'Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In superpowers-desktop/pro-setup/skills/debugging/find-polluter.sh lines 21-26,
the find usage and counting are wrong: replace the current find -path
"$TEST_PATTERN" call with a POSIX find-friendly pattern (either use -name for
simple globs like '*.test.js' or use -path with an explicit ./ prefix and
shell-style wildcards accepted by find, e.g. -path "./*/tests/*.test.js"), and
avoid piping to wc -l (which yields 1 for empty input) by reading results into
an array via mapfile -t (or while/read loop) and using the array length for
TOTAL; also update the example usage string to show the corrected pattern form
(e.g. './*/tests/*.test.js' or use -name '*.test.js') so it's clear what the
script expects.
| <Before> | ||
| ```markdown | ||
| Write code before test? Delete it. | ||
| ``` | ||
| </Before> | ||
|
|
||
| <After> | ||
| ```markdown | ||
| Write code before test? Delete it. Start over. | ||
|
|
||
| **No exceptions:** | ||
| - Don't keep it as "reference" | ||
| - Don't "adapt" it while writing tests | ||
| - Don't look at it | ||
| - Delete means delete | ||
| ``` | ||
| </After> |
There was a problem hiding this comment.
Add language specifier to fenced code block.
Markdownlint requires all code blocks to specify a language. Add markdown to the opening fence.
-<Before>
-```markdown
+<Before>
+```markdownThis applies to the opening fence on line 189. Change from ``` to ```markdown.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
204-204: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In superpowers-desktop/pro-setup/skills/meta/testing-skills-with-subagents.md
around lines 189-205, the fenced code block's opening fence lacks a language
specifier; update the opening fence from three backticks to include the markdown
language identifier (i.e. change the opening fence to include "markdown") so the
block is ```markdown ... ``` and satisfies markdownlint.
| - [ ] Updated rationalization table | ||
| - [ ] Updated red flags list | ||
| - [ ] Updated description ith violation symptoms | ||
| - [ ] Re-tested - agent still complies | ||
| - [ ] Meta-tested to verify clarity |
There was a problem hiding this comment.
Fix spelling error in checklist.
Line 332 has a typo: "ith" should be "with".
- [ ] Updated description ith violation symptoms
+ [ ] Updated description with violation symptoms🧰 Tools
🪛 LanguageTool
[grammar] ~332-~332: Ensure spelling is correct
Context: ...ed flags list - [ ] Updated description ith violation symptoms - [ ] Re-tested - ag...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In superpowers-desktop/pro-setup/skills/meta/testing-skills-with-subagents.md
around lines 330 to 334, there is a spelling typo in the checklist where line
332 reads "Updated description ith violation symptoms"; change "ith" to "with"
so the checklist item reads "Updated description with violation symptoms".
Ensure no other formatting or punctuation is altered.
| ``` | ||
| skills/ | ||
| skill-name/ | ||
| SKILL.md # Main reference (required) | ||
| supporting-file.* # Only if needed | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add language specifiers to code blocks and convert emphasis to proper headings.
Multiple code blocks lack language identifiers. Additionally, line 297 uses emphasis (**One excellent example**) where a proper heading (###) would improve document structure.
## Directory Structure
- ```
+ ```text
skills/
- ```
+ ```markdown
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]
---
- ```
+ ```text
skills/
skill-name/
- ```
+ ```text
NO SKILL WITHOUT A FAILING TEST FIRST-
# ❌ BAD: Too abstract, vague, doesn't include when to use
-
<Bad> ```markdown Write code before test? Delete it.
-
<Good> ```markdown Write code before test? Delete it. Start over.
-
Code Examples
- One excellent example beats many mediocre ones
-
One Excellent Example Beats Many Mediocre Ones
Also applies to: 321-324, 328-332, 336-342, 347-349, 440-444, 446-456
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
76-76: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<!-- This is an auto-generated comment by CodeRabbit -->
|
Error |
2 participants
Motivation and Context
How Has This Been Tested?
Breaking Changes
Types of changes
Checklist
Additional context
Summary by CodeRabbit
Release Notes
New Features
Documentation
Chores