Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions skills/brainstorming/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ Start by understanding the current project context, then ask questions one at a
- Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git

**Implementation (if continuing):**
- Ask: "Ready to set up for implementation?"
**Implementation:**
- Proceed directly to implementation setup
- Use superpowers:using-git-worktrees to create isolated workspace
- Use superpowers:writing-plans to create detailed implementation plan

Expand Down
28 changes: 12 additions & 16 deletions skills/executing-plans/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,28 +21,24 @@ Load plan, review critically, execute tasks in batches, report for review betwee
3. If concerns: Raise them with your human partner before starting
4. If no concerns: Create TodoWrite and proceed

### Step 2: Execute Batch
**Default: First 3 tasks**
### Step 2: Execute All Tasks

For each task:
1. Mark as in_progress
2. Follow each step exactly (plan has bite-sized steps)
3. Run verifications as specified
4. Mark as completed
5. Continue to next task immediately

### Step 3: Report
When batch complete:
- Show what was implemented
- Show verification output
- Say: "Ready for feedback."
**Do not stop for feedback between tasks.** Execute the entire plan.

### Step 4: Continue
Based on feedback:
- Apply changes if needed
- Execute next batch
- Repeat until complete
### Step 3: Report Completion
When all tasks complete:
- Show summary of what was implemented
- Show final verification output
- Report any issues encountered during execution

### Step 5: Complete Development
### Step 4: Complete Development

After all tasks complete and verified:
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
Expand All @@ -52,7 +48,7 @@ After all tasks complete and verified:
## When to Stop and Ask for Help

**STOP executing immediately when:**
- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
- Hit a blocker (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- You don't understand an instruction
- Verification fails repeatedly
Expand All @@ -72,8 +68,8 @@ After all tasks complete and verified:
- Follow plan steps exactly
- Don't skip verifications
- Reference skills when plan says to
- Between batches: just report and wait
- Stop when blocked, don't guess
- Execute entire plan without stopping
- Stop only when blocked, don't guess
- Never start implementation on main/master branch without explicit user consent

## Integration
Expand Down
31 changes: 17 additions & 14 deletions skills/systematic-debugging/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ You MUST complete each phase before proceeding to the next.
- Automated test if possible
- One-off test script if no framework
- MUST have before fixing
- Use the `superpowers:test-driven-development` skill for writing proper failing tests
- **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development for the failing test

2. **Implement Single Fix**
- Address the root cause identified
Expand All @@ -188,6 +188,7 @@ You MUST complete each phase before proceeding to the next.
- Test passes now?
- No other tests broken?
- Issue actually resolved?
- **REQUIRED SUB-SKILL:** Use superpowers:verification-before-completion before claiming fix works

4. **If Fix Doesn't Work**
- STOP
Expand All @@ -196,21 +197,21 @@ You MUST complete each phase before proceeding to the next.
- **If ≥ 3: STOP and question the architecture (step 5 below)**
- DON'T attempt Fix #4 without architectural discussion

5. **If 3+ Fixes Failed: Question Architecture**
5. **If 3+ Fixes Failed: Escalate to Architectural Refactoring**

**Pattern indicating architectural problem:**
- Each fix reveals new shared state/coupling/problem in different place
- Fixes require "massive refactoring" to implement
- Each fix creates new symptoms elsewhere

**STOP and question fundamentals:**
- Is this pattern fundamentally sound?
- Are we "sticking with it through sheer inertia"?
- Should we refactor architecture vs. continue fixing symptoms?
**Automatically escalate to architectural refactoring:**
- Stop attempting point fixes
- Document the failing pattern and evidence gathered
- Begin architectural analysis: Is this pattern fundamentally sound?
- Propose refactoring approach that addresses root structural issues
- **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development for all refactoring implementation

**Discuss with your human partner before attempting more fixes**

This is NOT a failed hypothesis - this is a wrong architecture.
This is NOT a failed hypothesis - this is a wrong architecture. Act accordingly.

## Red Flags - STOP and Follow Process

Expand All @@ -226,10 +227,11 @@ If you catch yourself thinking:
- Proposing solutions before tracing data flow
- **"One more fix attempt" (when already tried 2+)**
- **Each fix reveals new problem in different place**
- **"I'll skip TDD/verification skill, it's overkill for this fix"**

**ALL of these mean: STOP. Return to Phase 1.**

**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
**If 3+ fixes failed:** Auto-escalate to architectural refactoring (see Phase 4, Step 5)

## your human partner's Signals You're Doing It Wrong

Expand All @@ -253,7 +255,8 @@ If you catch yourself thinking:
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Auto-escalate to refactoring. |
| "Skip TDD/verification, it's simple" | Required sub-skills are REQUIRED. No exceptions. Invoke them. |

## Quick Reference

Expand Down Expand Up @@ -283,9 +286,9 @@ These techniques are part of systematic debugging and available in this director
- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling

**Related skills:**
- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
- **superpowers:verification-before-completion** - Verify fix worked before claiming success
**Required skills (MUST invoke during Phase 4):**
- **superpowers:test-driven-development** - REQUIRED for creating failing test case (Step 1) and refactoring (Step 5)
- **superpowers:verification-before-completion** - REQUIRED before claiming fix works (Step 3)

## Real-World Impact

Expand Down
19 changes: 8 additions & 11 deletions skills/using-git-worktrees/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,18 +35,15 @@ grep -i "worktree.*director" CLAUDE.md 2>/dev/null

**If preference specified:** Use it without asking.

### 3. Ask User
### 3. Default to .worktrees/

If no directory exists and no CLAUDE.md preference:
If no directory exists and no CLAUDE.md preference, create `.worktrees/` automatically:

```bash
mkdir -p .worktrees
```
No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?
```
This is the preferred default: project-local and hidden.

## Safety Verification

Expand Down Expand Up @@ -148,7 +145,7 @@ Ready to implement <feature-name>
| `.worktrees/` exists | Use it (verify ignored) |
| `worktrees/` exists | Use it (verify ignored) |
| Both exist | Use `.worktrees/` |
| Neither exists | Check CLAUDE.md → Ask user |
| Neither exists | Check CLAUDE.md → Default to `.worktrees/` |
| Directory not ignored | Add to .gitignore + commit |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |
Expand All @@ -163,7 +160,7 @@ Ready to implement <feature-name>
### Assuming directory location

- **Problem:** Creates inconsistency, violates project conventions
- **Fix:** Follow priority: existing > CLAUDE.md > ask
- **Fix:** Follow priority: existing > CLAUDE.md > default to `.worktrees/`

### Proceeding with failing tests

Expand Down Expand Up @@ -201,7 +198,7 @@ Ready to implement auth feature
- Skip CLAUDE.md check

**Always:**
- Follow directory priority: existing > CLAUDE.md > ask
- Follow directory priority: existing > CLAUDE.md > default to `.worktrees/`
- Verify directory is ignored for project-local
- Auto-detect and run project setup
- Verify clean test baseline
Expand Down
24 changes: 24 additions & 0 deletions skills/using-superpowers/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,8 @@ These thoughts mean STOP—you're rationalizing:
| "I'll just do this one thing first" | Check BEFORE doing anything. |
| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
| "This is too simple to need a plan" | Simple tasks get short plans. Still use writing-plans. |
| "I'll skip brainstorming, requirements are clear" | Fine, but you MUST still use writing-plans. Never skip both. |

## Skill Priority

Expand All @@ -85,3 +87,25 @@ The skill itself tells you which.
## User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

## Explicit Superpowers Requests

**When user explicitly says "use your superpowers" (or similar) for an implementation task:**

```
NEVER skip planning. At minimum, writing-plans is REQUIRED.
```

**The flow:**
1. Do you fully understand what to build?
- **No** → Use brainstorming first to clarify, then writing-plans
- **Yes** → Use writing-plans directly
2. NEVER skip both. Planning must happen before implementation.

**Why this matters:** The judgment call is "do I understand what to build?" NOT "is this simple enough to skip planning?" Simple tasks get short plans. Complex tasks get longer plans. But plans always happen.

| Thought | Reality |
|---------|---------|
| "This is obvious, no plan needed" | Obvious tasks get short plans. Still plan. |
| "I'll just make this quick change" | Quick changes still need plans. No exceptions. |
| "Planning is overkill here" | You're rationalizing. Use writing-plans. |
15 changes: 2 additions & 13 deletions skills/writing-plans/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,21 +96,10 @@ git commit -m "feat: add specific feature"

## Execution Handoff

After saving the plan, offer execution choice:
After saving the plan, proceed directly to subagent-driven execution:

**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
**"Plan complete and saved to `docs/plans/<filename>.md`. Proceeding with implementation."**

**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration

**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints

**Which approach?"**

**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Stay in this session
- Fresh subagent per task + code review

**If Parallel Session chosen:**
- Guide them to open new session in worktree
- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans