superpowers-skills

Before deploying a skill, complete this checklist (it is recommended to use TodoWrite to manage these items):

RED Phase (Failing Test)

• Create pressure scenarios (3+ combined pressures for discipline skills)
• Run scenarios WITHOUT skill - document baseline behavior verbatim
• Identify patterns in rationalizations/failures

GREEN Phase (Minimal Skill)

• Name describes what you DO or core insight
• YAML frontmatter with rich when_to_use (include symptoms!)
• Keywords throughout for search (errors, symptoms, tools)
• Clear overview with core principle
• Address specific baseline failures identified in RED
• Code inline OR @link to separate file
• One excellent example (not multi-language)
• Run scenarios WITH skill - verify agents now comply

REFACTOR Phase (Close Loopholes)

• Identify NEW rationalizations from testing
• Add explicit counters (if discipline skill)
• Build rationalization table from all test iterations
• Create red flags list
• Re-test until bulletproof

Quality Checks

• Small flowchart only if decision non-obvious
• Quick reference table
• Common mistakes section
• No narrative storytelling
• Supporting files only for tools or heavy reference

Writing Skills is the application of Test-Driven Development (TDD) to process documentation. Instead of writing documentation and then hoping it works, you follow a RED-GREEN-REFACTOR cycle:

1. RED (Test Fails): Create a 'pressure scenario' using subagents. Run the scenario without the skill present to observe the agent violating rules or using incorrect rationalizations. This establishes your baseline.
2. GREEN (Test Passes): Write the skill (SKILL.md) specifically addressing the violations observed. Verify that the agent now complies with the skill.
3. REFACTOR: Identify new loopholes or rationalizations the agent uses to bypass the skill. Update the documentation to plug these holes while maintaining compliance.

The Iron Law: NO SKILL WITHOUT A FAILING TEST FIRST. This applies to both creating new skills and editing existing ones.

| TDD Concept | Skill Creation |
|-------------|----------------|
| Test case | Pressure scenario with subagent |
| Production code | Skill document (SKILL.md) |
| Test fails (RED) | Agent violates rule without skill (baseline) |
| Test passes (GREEN) | Agent complies with skill present |
| Refactor | Close loopholes while maintaining compliance |

The Executing Plans skill is designed for implementing complete implementation plans in controlled, bite-sized batches with mandatory review checkpoints. Instead of attempting to execute an entire plan at once, you execute a small batch of tasks, report the results, and wait for human feedback before proceeding. This prevents large-scale errors and allows for architectural course correction.

Core Workflow:

1. Load & Review: Critically analyze the plan file. Raise concerns before starting.
2. Batch Execution: Execute a subset of tasks (default is the first 3 tasks). Follow each step exactly and run all specified verifications.
3. Report: After a batch, show implementation details and verification output, then state: "Ready for feedback."
4. Iterate: Apply feedback and execute the next batch until the plan is exhausted.
5. Finalize: Once the plan is complete, transition to the Finishing a Development Branch skill to wrap up work.

Root Cause Tracing is a systematic method for debugging errors that manifest deep in the call stack. Instead of fixing the symptom (where the error is first caught), you trace the execution chain backward to find the original trigger.

The Tracing Process

1. Observe the Symptom: Identify the error message (e.g., Error: git init failed in /path/to/dir).
2. Find Immediate Cause: Identify the specific line of code causing the failure (e.g., an execFileAsync call).
3. Ask: What Called This?: Move up the call stack (e.g., Function A called Function B).
4. Trace Values: Inspect the arguments being passed up the chain. Look for invalid values like empty strings, undefined, or incorrect paths.
5. Find Original Trigger: Locate the exact point where the invalid value was first introduced (e.g., a variable initialized incorrectly or a test accessing a property before setup).

Core Principle: NEVER fix just the symptom. Trace back to the source and fix the trigger, then add validation layers (defense-in-depth) to prevent recurrence.

Agents may attempt to find loopholes or rationalize skipping rules (e.g., 'I'll just keep this code as a reference'). To prevent this, follow these patterns:

Close Loopholes Explicitly

Do not just state a rule; forbid specific workarounds.

Example of a good rule:

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

Address "Spirit vs Letter" Arguments

Include a foundational principle to prevent agents from claiming they are 'following the spirit' while breaking the rules: **Violating the letter of the rules is violating the spirit of the rules.**

Build a Rationalization Table

Capture every excuse an agent makes during testing in a table to address them in the skill documentation.

Create a Red Flags List

Provide a list of behaviors that should trigger an agent to stop and restart.

Example Red Flags:

• Code before test
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "This is different because..."

When designing skills for LLMs, you can use seven psychological persuasion principles to increase compliance rates (from ~33% to ~72%). These principles help ensure critical practices are followed even under pressure by reducing decision fatigue and preventing rationalization.

The Seven Principles

1. Authority: Use imperative language ("YOU MUST", "Never", "Always") and non-negotiable framing ("No exceptions") to eliminate decision fatigue. Best for discipline-enforcing or safety-critical skills.
2. Commitment: Force explicit choices or require announcements (e.g., "Announce skill usage") to ensure consistency with prior actions.
3. Scarcity: Create urgency using time-bound requirements ("Before proceeding") or sequential dependencies ("Immediately after X") to prevent procrastination.
4. Social Proof: Establish norms by using universal patterns ("Every time", "Always") or highlighting common failure modes.
5. Unity: Use collaborative language ("our codebase", "we're colleagues") to establish shared identity and goals.
6. Reciprocity: Obligation to return benefits. Use sparingly as it can feel manipulative and is rarely needed in skill design.
7. Liking: Preference for cooperating with those we like. Avoid for compliance as it creates sycophancy and conflicts with honest feedback culture.

Every implementation plan must follow a strict structure to ensure clarity for the executing agent.

1. Plan Document Header

Every plan MUST start with this specific header format:

# [Feature Name] Implementation Plan

> **For Claude:** Use `${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/executing-plans/SKILL.md` 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]

---

2. Task Granularity

Tasks must be "bite-sized," where each step represents a single action taking 2-5 minutes (e.g., writing a test, running it, implementing code, committing).

3. Task Format

Each task should follow this template:

• Files: Explicitly list Create, Modify (with line numbers), and Test paths.
• Step 1: Write the failing test (include code).
• Step 2: Run test to verify failure (include exact command and expected output).
• Step 3: Write minimal implementation (include code).
• Step 4: Run test to verify pass (include exact command and expected output).
• Step 5: Commit (include exact git commands).

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected

Step 2: Run test to verify it fails

Run: pytest tests/path/test.py::test_name -v Expected: FAIL with "function not defined"

Step 3: Write minimal implementation

def function(input):
    return expected

Step 4: Run test to verify it passes

Run: pytest tests/path/test.py::test_name -v Expected: PASS

Step 5: Commit

git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"

Revival Detection

When evaluating 'new' approaches, check if they are actually rebranded versions of old ideas.

1. Search for historical precedents.
2. Identify what is genuinely new vs. rebranded.
3. Understand why the previous version died.
4. Check if 'resurrection conditions' (changed context) exist.

Common Revival Patterns:

• Microservices $\leftarrow$ Service-Oriented Architecture $\leftarrow$ Distributed Objects
• GraphQL $\leftarrow$ SOAP $\leftarrow$ RPC
• Serverless $\leftarrow$ CGI scripts $\leftarrow$ Cloud functions
• NoSQL $\leftarrow$ Flat files $\leftarrow$ Document stores

Paradigm Shift Mapping

When major architectural changes occur, map the transition to preserve lessons.

Documentation Template for Paradigm Shifts:

## Paradigm Shift: From [Old] to [New]

**Pre-shift thinking:** [How we thought about problem]
**Catalyst:** [What triggered the shift]
**Post-shift thinking:** [How we think now]
**What was gained:** [New capabilities]
**What was lost:** [Old capabilities sacrificed]
**Lessons preserved:** [What we kept from old paradigm]
**Lessons forgotten:** [What we might need to relearn]