diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 2fd19ba1e..bb58e54ef 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -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 diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index c1b2533f4..520d8b4e5 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -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." @@ -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 @@ -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 diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md index 111d2a98c..c2f303a80 100644 --- a/skills/systematic-debugging/SKILL.md +++ b/skills/systematic-debugging/SKILL.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/skills/using-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.md index e153843cd..1a002bc85 100644 --- a/skills/using-git-worktrees/SKILL.md +++ b/skills/using-git-worktrees/SKILL.md @@ -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// (global location) -Which would you prefer? -``` +This is the preferred default: project-local and hidden. ## Safety Verification @@ -148,7 +145,7 @@ Ready to implement | `.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 | @@ -163,7 +160,7 @@ Ready to implement ### 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 @@ -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 diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index 7867fcfc0..750c21b32 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -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 @@ -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. | diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 448ca3193..a02b13f50 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -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/.md`. Two execution options:** +**"Plan complete and saved to `docs/plans/.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