--- title: "obra/superpowers" description: "An agentic skills framework & software development methodology that works." source: https://github.com/obra/superpowers ref: main license: MIT licenseName: "MIT License" canonical: https://skillsdocs.com/obra/superpowers base: https://github.com/obra/superpowers/blob/main/ chapters: 14 inlined: 14 withheld: 0 words: 13241 updated: 2026-08-08T01:45:49Z generator: "Skills Docs" --- > **obra/superpowers** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/obra/superpowers > Per-chapter Markdown: https://skillsdocs.com/obra/superpowers/.md > Machine manifest: https://skillsdocs.com/obra/superpowers/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/obra/superpowers > Install: `npx skills add obra/superpowers` > Upstream: https://github.com/obra/superpowers @ `main` > Licence: MIT > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request # obra/superpowers An agentic skills framework & software development methodology that works. - **Chapters:** 14 - **Inlined:** 14 (licence detected) - **Words:** 13,241 - **Reading time:** 59 min - **Stars:** 270,801 ## Table of contents 1. [brainstorming](https://skillsdocs.com/obra/superpowers/brainstorming.md) — You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, require… 2. [dispatching-parallel-agents](https://skillsdocs.com/obra/superpowers/dispatching-parallel-agents.md) — Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies 3. [executing-plans](https://skillsdocs.com/obra/superpowers/executing-plans.md) — Use when you have a written implementation plan to execute in a separate session with review checkpoints 4. [finishing-a-development-branch](https://skillsdocs.com/obra/superpowers/finishing-a-development-branch.md) — Use when implementation is complete, all tests pass, and you need to decide how to integrate the work 5. [receiving-code-review](https://skillsdocs.com/obra/superpowers/receiving-code-review.md) — Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical… 6. [requesting-code-review](https://skillsdocs.com/obra/superpowers/requesting-code-review.md) — Use when completing tasks, implementing major features, or before merging to verify work meets requirements 7. [subagent-driven-development](https://skillsdocs.com/obra/superpowers/subagent-driven-development.md) — Use when executing implementation plans with independent tasks in the current session 8. [systematic-debugging](https://skillsdocs.com/obra/superpowers/systematic-debugging.md) — Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes 9. [test-driven-development](https://skillsdocs.com/obra/superpowers/test-driven-development.md) — Use when implementing any feature or bugfix, before writing implementation code 10. [using-git-worktrees](https://skillsdocs.com/obra/superpowers/using-git-worktrees.md) — Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via… 11. [using-superpowers](https://skillsdocs.com/obra/superpowers/using-superpowers.md) — Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions 12. [verification-before-completion](https://skillsdocs.com/obra/superpowers/verification-before-completion.md) — Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output b… 13. [writing-plans](https://skillsdocs.com/obra/superpowers/writing-plans.md) — Use when you have a spec or requirements for a multi-step task, before touching code 14. [writing-skills](https://skillsdocs.com/obra/superpowers/writing-skills.md) — Use when creating new skills, editing existing skills, or verifying skills work before deployment ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/obra/superpowers/blob/main/._ # Superpowers Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them. ## Quickstart Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [Gemini CLI](#gemini-cli), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi). ## How it works It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do. Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest. After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for your agent to work autonomously for a couple hours at a time without deviating from the plan you put together. There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers. ## Commercial Services If you're using Superpowers in enterprise and could benefit from commercial support, additional tooling, or managed spending, please don't hesitate to drop us a line at sales@primeradiant.com. ## Installation Installation differs by harness. If you use more than one, install Superpowers separately for each one. ### Claude Code Superpowers is available via the [official Claude plugin marketplace](https://claude.com/plugins/superpowers) #### Official Marketplace - Install the plugin from Anthropic's official marketplace: ```bash /plugin install superpowers@claude-plugins-official ``` #### Superpowers Marketplace The Superpowers marketplace provides Superpowers and some other related plugins for Claude Code. - Register the marketplace: ```bash /plugin marketplace add obra/superpowers-marketplace ``` - Install the plugin from this marketplace: ```bash /plugin install superpowers@superpowers-marketplace ``` ### Antigravity Install Superpowers as a plugin from this repository: ```bash agy plugin install https://github.com/obra/superpowers ``` Antigravity runs the plugin's session-start hook, so Superpowers is active from the first message. Reinstall with the same command to update. ### Codex App Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins). - In the Codex app, click on Plugins in the sidebar. - You should see `Superpowers` in the Coding section. - Click the `+` next to Superpowers and follow the prompts. ### Codex CLI Superpowers is available via the [official Codex plugin marketplace](https://github.com/openai/plugins). - Open the plugin search interface: ```bash /plugins ``` - Search for Superpowers: ```bash superpowers ``` - Select `Install Plugin`. ### Cursor - In Cursor Agent chat, install from marketplace: ```text /add-plugin superpowers ``` - Or search for "superpowers" in the plugin marketplace. ### Factory Droid - Register the marketplace: ```bash droid plugin marketplace add https://github.com/obra/superpowers ``` - Install the plugin: ```bash droid plugin install superpowers@superpowers ``` ### Gemini CLI - Install the extension: ```bash gemini extensions install https://github.com/obra/superpowers ``` - Update later: ```bash gemini extensions update superpowers ``` ### GitHub Copilot CLI - Register the marketplace: ```bash copilot plugin marketplace add obra/superpowers-marketplace ``` - Install the plugin: ```bash copilot plugin install superpowers@superpowers-marketplace ``` ### Kimi Code Superpowers is available in Kimi Code's plugin marketplace. - Open Kimi Code's plugin manager: ```text /plugins ``` - Go to `Marketplace` > `Superpowers` and install it. - Or install directly from this repository: ```text /plugins install https://github.com/obra/superpowers ``` - Detailed docs: [docs/README.kimi.md](https://github.com/obra/superpowers/blob/main/docs/README.kimi.md) ### OpenCode OpenCode uses its own plugin install; install Superpowers separately even if you already use it in another harness. - Tell OpenCode: ``` Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md ``` - Detailed docs: [docs/README.opencode.md](https://github.com/obra/superpowers/blob/main/docs/README.opencode.md) ### Pi Install Superpowers as a Pi package from this repository: ```bash pi install git:github.com/obra/superpowers ``` For local development, run Pi with this checkout loaded as a temporary package: ```bash pi -e /path/to/superpowers ``` The Pi package loads the Superpowers skills and a small extension that injects the `using-superpowers` bootstrap at session startup and again after compaction. Pi has native skills, so no compatibility `Skill` tool is required. Subagent and task-list tools remain optional Pi companion packages. ## The Basic Workflow 1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document. 2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline. 3. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps. 4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints. 5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests. 6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress. 7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree. **The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions. ## What's Inside ### Skills Library **Testing** - **test-driven-development** - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference) **Debugging** - **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques) - **verification-before-completion** - Ensure it's actually fixed **Collaboration** - **brainstorming** - Socratic design refinement - **writing-plans** - Detailed implementation plans - **executing-plans** - Batch execution with checkpoints - **dispatching-parallel-agents** - Concurrent subagent workflows - **requesting-code-review** - Pre-review checklist - **receiving-code-review** - Responding to feedback - **using-git-worktrees** - Parallel development branches - **finishing-a-development-branch** - Merge/PR decision workflow - **subagent-driven-development** - Fast iteration with two-stage review (spec compliance, then code quality) **Meta** - **writing-skills** - Create new skills following best practices (includes testing methodology) - **using-superpowers** - Introduction to the skills system ## Philosophy - **Test-Driven Development** - Write tests first, always - **Systematic over ad-hoc** - Process over guessing - **Complexity reduction** - Simplicity as primary goal - **Evidence over claims** - Verify before declaring success Read [the original release announcement](https://blog.fsck.com/2025/10/09/superpowers/). ## Contributing The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support. 1. Fork the repository 2. Switch to the 'dev' branch 3. Create a branch for your work 4. Follow the `writing-skills` skill for creating and testing new and modified skills 5. Submit a PR, being sure to fill in the pull request template. Skill-behavior tests use the drill eval harness from [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. Plugin-infrastructure tests live at `tests/` and run via the relevant `run-*.sh` or `npm test`. See `skills/writing-skills/SKILL.md` for the complete guide. ## Updating Superpowers updates are somewhat coding-agent dependent, but are often automatic. ## License MIT License - see LICENSE file for details ## Visual companion telemetry Because skills and plugins don't provide any feedback to creators, we have no idea how many of you are using Superpowers. By default, the Prime Radiant logo on brainstorming's optional visual companion feature is loaded from our website. It includes the version of Superpowers in use. It does not include any details about your project, prompt, or coding agent. We don't see your clicks or anything about what you're building. This helps us have a rough idea of how many folks are using Superpowers and which version of Superpowers they're using. It's 100% optional. To disable this, set the environment variable `SUPERPOWERS_DISABLE_TELEMETRY` to any true value. Superpowers also honors Claude Code's `DISABLE_TELEMETRY` and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` opt-outs. ## Community Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of the folks at [Prime Radiant](https://primeradiant.com). - **Discord**: [Join us](https://discord.gg/35wsABTejz) for community support, questions, and sharing what you're building with Superpowers - **Issues**: https://github.com/obra/superpowers/issues - **Release announcements**: [Sign up](https://primeradiant.com/superpowers/) to get notified about new versions --- ## 1. brainstorming - **Source:** https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/brainstorming.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (7), referenced from this skill's directory: - `scripts/frame-template.html` — https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/scripts/frame-template.html - `scripts/helper.js` — https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/scripts/helper.js - `scripts/server.cjs` — https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/scripts/server.cjs - `scripts/start-server.sh` — https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/scripts/start-server.sh - `scripts/stop-server.sh` — https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/scripts/stop-server.sh - `spec-document-reviewer-prompt.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/spec-document-reviewer-prompt.md - `visual-companion.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/brainstorming/visual-companion.md --- name: brainstorming description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." --- # Brainstorming Ideas Into Designs Help turn ideas into fully formed designs and specs through natural collaborative dialogue. Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval. Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. ## Anti-Pattern: "This Is Too Simple To Need A Design" Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval. ## Checklist You MUST create a task for each of these items and complete them in order: 1. **Explore project context** — check files, docs, recent commits 2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below. 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria 4. **Propose 2-3 approaches** — with trade-offs and your recommendation 5. **Present design** — in sections scaled to their complexity, get user approval after each section 6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit 7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) 8. **User reviews written spec** — ask user to review the spec file before proceeding 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan ## Process Flow ```dot digraph brainstorming { "Explore project context" [shape=box]; "Ask clarifying questions" [shape=box]; "Propose 2-3 approaches" [shape=box]; "Present design sections" [shape=box]; "User approves design?" [shape=diamond]; "Write design doc" [shape=box]; "Spec self-review\n(fix inline)" [shape=box]; "User reviews spec?" [shape=diamond]; "Invoke writing-plans skill" [shape=doublecircle]; "Explore project context" -> "Ask clarifying questions"; "Ask clarifying questions" -> "Propose 2-3 approaches"; "Propose 2-3 approaches" -> "Present design sections"; "Present design sections" -> "User approves design?"; "User approves design?" -> "Present design sections" [label="no, revise"]; "User approves design?" -> "Write design doc" [label="yes"]; "Write design doc" -> "Spec self-review\n(fix inline)"; "Spec self-review\n(fix inline)" -> "User reviews spec?"; "User reviews spec?" -> "Write design doc" [label="changes requested"]; "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"]; } ``` **The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans. ## The Process **Understanding the idea:** - Check out the current project state first (files, docs, recent commits) - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first. - If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle. - For appropriately-scoped projects, ask questions one at a time to refine the idea - Prefer multiple choice questions when possible, but open-ended is fine too - Only one question per message - if a topic needs more exploration, break it into multiple questions - Focus on understanding: purpose, constraints, success criteria **Exploring approaches:** - Propose 2-3 different approaches with trade-offs - Present options conversationally with your recommendation and reasoning - Lead with your recommended option and explain why - YAGNI ruthlessly - remove unnecessary features from every approach and design **Presenting the design:** - Once you believe you understand what you're building, present the design - Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced - Ask after each section whether it looks right so far - Cover: architecture, components, data flow, error handling, testing - Be ready to go back and clarify if something doesn't make sense **Design for isolation and clarity:** - Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently - For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on? - Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work. - Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much. **Working in existing codebases:** - Explore the current structure before proposing changes. Follow existing patterns. - Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in. - Don't propose unrelated refactoring. Stay focused on what serves the current goal. ## After the Design **Documentation:** - Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD--design.md` - (User preferences for spec location override this default) - Use elements-of-style:writing-clearly-and-concisely skill if available - Commit the design document to git **Spec Self-Review:** After writing the spec document, look at it with fresh eyes: 1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them. 2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions? 3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition? 4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit. Fix any issues inline. No need to re-review — just fix and move on. **User Review Gate:** After the spec review loop passes, ask the user to review the written spec before proceeding: > "Spec written and committed to ``. Please review it and let me know if you want to make any changes before we start writing out the implementation plan." Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves. **Implementation:** - Invoke the writing-plans skill to create a detailed implementation plan - Do NOT invoke any other skill. writing-plans is the next step. ## Visual Companion A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser. **Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message: > "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you." **This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with `--open` so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it. **Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?** - **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs - **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser. If they agree to the companion, read the detailed guide before proceeding: `skills/brainstorming/visual-companion.md` --- ## 2. dispatching-parallel-agents - **Source:** https://github.com/obra/superpowers/blob/main/skills/dispatching-parallel-agents/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/dispatching-parallel-agents/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/dispatching-parallel-agents.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: dispatching-parallel-agents description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies --- # Dispatching Parallel Agents ## Overview You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work. When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel. **Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently. ## When to Use ```dot digraph when_to_use { "Multiple failures?" [shape=diamond]; "Are they independent?" [shape=diamond]; "Single agent investigates all" [shape=box]; "One agent per problem domain" [shape=box]; "Can they work in parallel?" [shape=diamond]; "Sequential agents" [shape=box]; "Parallel dispatch" [shape=box]; "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"]; "Can they work in parallel?" -> "Parallel dispatch" [label="yes"]; "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"]; } ``` **Use when:** - 3+ test files failing with different root causes - Multiple subsystems broken independently - Each problem can be understood without context from others - No shared state between investigations **Don't use when:** - Failures are related (fix one might fix others) - Need to understand full system state - Agents would interfere with each other ## The Pattern ### 1. Identify Independent Domains Group failures by what's broken: - File A tests: Tool approval flow - File B tests: Batch completion behavior - File C tests: Abort functionality Each domain is independent - fixing tool approval doesn't affect abort tests. ### 2. Create Focused Agent Tasks Each agent gets: - **Specific scope:** One test file or subsystem - **Clear goal:** Make these tests pass - **Constraints:** Don't change other code - **Expected output:** Summary of what you found and fixed ### 3. Dispatch in Parallel Issue all three subagent dispatches in the same response — they run in parallel: ```text Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures" Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures" Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures" # All three run concurrently. ``` Multiple dispatch calls in one response = parallel execution. One per response = sequential. ### 4. Review and Integrate When agents return: - Read each summary - Verify fixes don't conflict - Run full test suite - Integrate all changes ## Agent Prompt Structure Good agent prompts are: 1. **Focused** - One clear problem domain 2. **Self-contained** - All context needed to understand the problem 3. **Specific about output** - What should the agent return? ```markdown Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts: 1. "should abort tool with partial output capture" - expects 'interrupted at' in message 2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed 3. "should properly track pendingToolCount" - expects 3 results but gets 0 These are timing/race condition issues. Your task: 1. Read the test file and understand what each test verifies 2. Identify root cause - timing issues or actual bugs? 3. Fix by: - Replacing arbitrary timeouts with event-based waiting - Fixing bugs in abort implementation if found - Adjusting test expectations if testing changed behavior Do NOT just increase timeouts - find the real issue. Return: Summary of what you found and what you fixed. ``` ## Common Mistakes **❌ Too broad:** "Fix all the tests" - agent gets lost **✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope **❌ No context:** "Fix the race condition" - agent doesn't know where **✅ Context:** Paste the error messages and test names **❌ No constraints:** Agent might refactor everything **✅ Constraints:** "Do NOT change production code" or "Fix tests only" **❌ Vague output:** "Fix it" - you don't know what changed **✅ Specific:** "Return summary of root cause and changes" ## When NOT to Use **Related failures:** Fixing one might fix others - investigate together first **Need full context:** Understanding requires seeing entire system **Exploratory debugging:** You don't know what's broken yet **Shared state:** Agents would interfere (editing same files, using same resources) ## Real Example from Session **Scenario:** 6 test failures across 3 files after major refactoring **Failures:** - agent-tool-abort.test.ts: 3 failures (timing issues) - batch-completion-behavior.test.ts: 2 failures (tools not executing) - tool-approval-race-conditions.test.ts: 1 failure (execution count = 0) **Decision:** Independent domains - abort logic separate from batch completion separate from race conditions **Dispatch:** ``` Agent 1 → Fix agent-tool-abort.test.ts Agent 2 → Fix batch-completion-behavior.test.ts Agent 3 → Fix tool-approval-race-conditions.test.ts ``` **Results:** - Agent 1: Replaced timeouts with event-based waiting - Agent 2: Fixed event structure bug (threadId in wrong place) - Agent 3: Added wait for async tool execution to complete **Integration:** All fixes independent, no conflicts, full suite green ## Verification After agents return: 1. **Review each summary** - Understand what changed 2. **Check for conflicts** - Did agents edit same code? 3. **Run full suite** - Verify all fixes work together 4. **Spot check** - Agents can make systematic errors --- ## 3. executing-plans - **Source:** https://github.com/obra/superpowers/blob/main/skills/executing-plans/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/executing-plans/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/executing-plans.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: executing-plans description: Use when you have a written implementation plan to execute in a separate session with review checkpoints --- # Executing Plans ## Overview Load plan, review critically, execute all tasks, report when complete. **Announce at start:** "I'm using the executing-plans skill to implement this plan." **Note:** Tell your human partner that Superpowers works much better with access to subagents (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill. ## The Process ### Step 1: Load and Review Plan 1. Ensure an isolated workspace: use superpowers:using-git-worktrees to create one or verify the existing one 2. Read plan file 3. Review critically - identify any questions or concerns about the plan 4. If concerns: Raise them with your human partner before starting 5. If no concerns: Create todos for the plan items and proceed ### Step 2: Execute 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 ### Step 3: Complete Development After all tasks complete and verified: - Announce: "I'm using the finishing-a-development-branch skill to complete this work." - **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch - Follow that skill to verify tests, present options, execute choice ## When to Stop and Ask for Help **STOP executing immediately when:** - Hit a blocker (missing dependency, test fails, instruction unclear) - Plan has critical gaps preventing starting - You don't understand an instruction - Verification fails repeatedly **Ask for clarification rather than guessing.** ## When to Revisit Earlier Steps **Return to Review (Step 1) when:** - Partner updates the plan based on your feedback - Fundamental approach needs rethinking **Don't force through blockers** - stop and ask. ## Remember - Review plan critically first - Follow plan steps exactly - Don't skip verifications - Reference skills when plan says to - Stop when blocked, don't guess - Never start implementation on main/master branch without explicit user consent --- ## 4. finishing-a-development-branch - **Source:** https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/finishing-a-development-branch/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/finishing-a-development-branch.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: finishing-a-development-branch description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work --- # Finishing a Development Branch ## Overview **Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up. **Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work." ## Step 1: Verify Tests Run the project's full test suite (`npm test` / `cargo test` / `pytest` / `go test ./...`). **If tests fail**, report the failures and stop — the menu comes after a green suite: ``` Tests failing ( failures). Must fix before completing: [Show failures] ``` **If tests pass:** continue to Step 2. ## Step 2: Detect Environment ```bash GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) # Capture now, while still inside the workspace — Step 5 changes directory # before cleanup (Step 6) needs this value WORKTREE_PATH=$(git rev-parse --show-toplevel) ``` This determines which menu to show and how cleanup works: | State | Menu | Cleanup | |-------|------|---------| | `GIT_DIR == GIT_COMMON` (normal repo) | Standard 3 options | No worktree to clean up | | `GIT_DIR != GIT_COMMON`, named branch | Standard 3 options | Provenance-based (see Step 6) | | `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 2 options (no merge) | Externally managed — leave in place | ## Step 3: Determine Base Branch The base branch is whatever this work forked from — usually named in the plan, the conversation, or the branch's upstream. If it is not already known, ask: "This branch split from - is that correct?" Confirm before merging: merging into the wrong base is expensive to undo. ## Step 4: Present Options **Normal repo and named-branch worktree — present exactly these 3 options:** ``` Implementation complete. What would you like to do? 1. Merge back to locally 2. Push and create a Pull Request 3. Keep the branch as-is (I'll handle it later) Which option? ``` **Detached HEAD — present exactly these 2 options:** ``` Implementation complete. You're on a detached HEAD (externally managed workspace). 1. Push as new branch and create a Pull Request 2. Keep as-is (I'll handle it later) Which option? ``` Present the menu exactly as written — concise, with every option coming from the list above. Discarding the work happens only in response to your human partner explicitly asking for it (see "If your human partner asks to discard the work" below). Wait for their answer; the integration decision is theirs. ## Step 5: Execute Choice ### Option 1: Merge Locally ```bash # Get main repo root for CWD safety MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) cd "$MAIN_ROOT" # Merge first — verify success before removing anything git checkout git pull git merge # Verify tests on merged result ``` If tests fail on the merged result: stop, leave the worktree and branch in place, and investigate — nothing has been pushed, so the merge is local and recoverable. Once the merged result is green: clean up the worktree (Step 6), then delete the branch: ```bash git branch -d ``` ### Option 2: Push and Create PR ```bash git push -u origin # From a detached HEAD, name the new branch on the remote: # git push origin HEAD:refs/heads/ ``` Then create the pull/merge request against with the forge's tooling — its CLI if one is available, or the creation URL most forges print when you push — following the repo's PR template and conventions if present, and report the URL to your human partner. Keep the worktree — your human partner iterates on PR feedback there. ### Option 3: Keep As-Is Report: "Keeping branch . Worktree preserved at ." ### If your human partner asks to discard the work This path exists only as a response to an explicit request to throw the work away. Confirm first: ``` This will permanently delete: - Branch - All commits: - Worktree at Type 'discard' to confirm. ``` Wait for that exact confirmation. When it arrives: ```bash MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel) cd "$MAIN_ROOT" ``` Then clean up the worktree (Step 6) and force-delete the branch: ```bash git branch -D ``` ## Step 6: Cleanup Workspace **Runs for Option 1 and confirmed discards.** Options 2 and 3 always preserve the worktree. Both callers have already changed directory to the main repo root — worktree removal must run from outside the worktree — and use the `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` values captured in Step 2, from before that directory change. **If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done. **If `WORKTREE_PATH` is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup: ```bash git worktree remove "$WORKTREE_PATH" git worktree prune # Self-healing: clean up any stale registrations ``` **Otherwise:** The host environment owns this workspace — leave it in place. If your platform provides a workspace-exit tool, use it. ## Quick Reference | Option | Merge | Push | Keep Worktree | Cleanup Branch | |--------|-------|------|---------------|----------------| | 1. Merge locally | yes | - | - | yes | | 2. Create PR | - | yes | yes | - | | 3. Keep as-is | - | - | yes | - | | Discard (explicit request only) | - | - | - | yes (force) | ## Common Rationalizations | Excuse | Reality | |--------|---------| | "Tests passed earlier this session" | Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on. | | "They obviously want it merged" | Integration is your human partner's decision. Present the menu and wait. | | "They seem done with this feature — I'll offer to discard it" | The menu is complete as written. Discard happens only when your human partner asks for it in so many words. | | "'Yeah, get rid of it' counts as confirmation" | Only the typed word `discard` authorizes deletion. | | "The PR is up, so the worktree is clutter now" | PR feedback gets fixed in that worktree. It stays until the work lands. | | "This other worktree looks stale — I'll clean it too" | Clean up only worktrees under `.worktrees/` or `worktrees/`. Everything else belongs to the host. | | "The merged-result failure is probably flaky" | A failing merged result stops everything. Branch and worktree stay put while you investigate. | | "The base branch is obviously main" | Confirm the fork point or ask. Merging into the wrong base is expensive to undo. | | "The push was rejected — force-push will fix it" | A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request. | --- ## 5. receiving-code-review - **Source:** https://github.com/obra/superpowers/blob/main/skills/receiving-code-review/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/receiving-code-review/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/receiving-code-review.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: receiving-code-review description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation --- # Code Review Reception ## Overview Code review requires technical evaluation, not emotional performance. **Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort. ## The Response Pattern ``` WHEN receiving code review feedback: 1. READ: Complete feedback without reacting 2. UNDERSTAND: Restate requirement in own words (or ask) 3. VERIFY: Check against codebase reality 4. EVALUATE: Technically sound for THIS codebase? 5. RESPOND: Technical acknowledgment or reasoned pushback 6. IMPLEMENT: One item at a time, test each ``` ## Forbidden Responses **NEVER:** - "You're absolutely right!" (explicit instruction-file violation) - "Great point!" / "Excellent feedback!" (performative) - "Let me implement that now" (before verification) **INSTEAD:** - Restate the technical requirement - Ask clarifying questions - Push back with technical reasoning if wrong - Just start working (actions > words) ## Handling Unclear Feedback ``` IF any item is unclear: STOP - do not implement anything yet ASK for clarification on unclear items WHY: Items may be related. Partial understanding = wrong implementation. ``` **Example:** ``` your human partner: "Fix 1-6" You understand 1,2,3,6. Unclear on 4,5. ❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later ✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding." ``` ## Source-Specific Handling ### From your human partner - **Trusted** - implement after understanding - **Still ask** if scope unclear - **No performative agreement** - **Skip to action** or technical acknowledgment ### From External Reviewers ``` BEFORE implementing: 1. Check: Technically correct for THIS codebase? 2. Check: Breaks existing functionality? 3. Check: Reason for current implementation? 4. Check: Works on all platforms/versions? 5. Check: Does reviewer understand full context? IF suggestion seems wrong: Push back with technical reasoning IF can't easily verify: Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?" IF conflicts with your human partner's prior decisions: Stop and discuss with your human partner first ``` **your human partner's rule:** "External feedback - be skeptical, but check carefully" ## YAGNI Check for "Professional" Features ``` IF reviewer suggests "implementing properly": grep codebase for actual usage IF unused: "This endpoint isn't called. Remove it (YAGNI)?" IF used: Then implement properly ``` **your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it." ## Implementation Order ``` FOR multi-item feedback: 1. Clarify anything unclear FIRST 2. Then implement in this order: - Blocking issues (breaks, security) - Simple fixes (typos, imports) - Complex fixes (refactoring, logic) 3. Test each fix individually 4. Verify no regressions ``` ## When To Push Back Push back when: - Suggestion breaks existing functionality - Reviewer lacks full context - Violates YAGNI (unused feature) - Technically incorrect for this stack - Legacy/compatibility reasons exist - Conflicts with your human partner's architectural decisions **How to push back:** - Use technical reasoning, not defensiveness - Ask specific questions - Reference working tests/code - Involve your human partner if architectural **If you're uncomfortable pushing back out loud:** Name that tension, then tell your partner about the issue you've seen. They'll appreciate your honesty. ## Acknowledging Correct Feedback When feedback IS correct: ``` ✅ "Fixed. [Brief description of what changed]" ✅ "Good catch - [specific issue]. Fixed in [location]." ✅ [Just fix it and show in the code] ❌ "You're absolutely right!" ❌ "Great point!" ❌ "Thanks for catching that!" ❌ "Thanks for [anything]" ❌ ANY gratitude expression ``` **Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback. **If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead. ## Gracefully Correcting Your Pushback If you pushed back and were wrong: ``` ✅ "You were right - I checked [X] and it does [Y]. Implementing now." ✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing." ❌ Long apology ❌ Defending why you pushed back ❌ Over-explaining ``` State the correction factually and move on. ## Common Mistakes | Mistake | Fix | |---------|-----| | Performative agreement | State requirement or just act | | Blind implementation | Verify against codebase first | | Batch without testing | One at a time, test each | | Assuming reviewer is right | Check if breaks things | | Avoiding pushback | Technical correctness > comfort | | Partial implementation | Clarify all items first | | Can't verify, proceed anyway | State limitation, ask for direction | ## Real Examples **Performative Agreement (Bad):** ``` Reviewer: "Remove legacy code" ❌ "You're absolutely right! Let me remove that..." ``` **Technical Verification (Good):** ``` Reviewer: "Remove legacy code" ✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?" ``` **YAGNI (Good):** ``` Reviewer: "Implement proper metrics tracking with database, date filters, CSV export" ✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?" ``` **Unclear Item (Good):** ``` your human partner: "Fix items 1-6" You understand 1,2,3,6. Unclear on 4,5. ✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing." ``` ## GitHub Thread Replies When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment. --- ## 6. requesting-code-review - **Source:** https://github.com/obra/superpowers/blob/main/skills/requesting-code-review/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/requesting-code-review/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/requesting-code-review.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (1), referenced from this skill's directory: - `code-reviewer.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/requesting-code-review/code-reviewer.md --- name: requesting-code-review description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements --- # Requesting Code Review Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. **Core principle:** Review early, review often. ## When to Request Review **Mandatory:** - After each task in subagent-driven development - After completing major feature - Before merge to main **Optional but valuable:** - When stuck (fresh perspective) - Before refactoring (baseline check) - After fixing complex bug ## How to Request **1. Get git SHAs:** ```bash BASE_SHA=$(git rev-parse HEAD~1) # or origin/main HEAD_SHA=$(git rev-parse HEAD) ``` **2. Dispatch code reviewer subagent:** Dispatch a `general-purpose` subagent, filling the template at [code-reviewer.md](code-reviewer.md) **Placeholders:** - `{DESCRIPTION}` - Brief summary of what you built - `{PLAN_OR_REQUIREMENTS}` - What it should do - `{BASE_SHA}` - Starting commit - `{HEAD_SHA}` - Ending commit **3. Act on feedback:** - Fix Critical issues immediately - Fix Important issues before proceeding - Note Minor issues for later - Push back if reviewer is wrong (with reasoning) ## Example ``` [Just completed Task 2: Add verification function] You: Let me request code review before proceeding. BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}') HEAD_SHA=$(git rev-parse HEAD) [Dispatch code reviewer subagent] DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md BASE_SHA: a7981ec HEAD_SHA: 3df7661 [Subagent returns]: Strengths: Clean architecture, real tests Issues: Important: Missing progress indicators Minor: Magic number (100) for reporting interval Assessment: Ready to proceed You: [Fix progress indicators] [Continue to Task 3] ``` ## Common Rationalizations | Excuse | Reality | |--------|---------| | "I'll just review the diff myself instead of dispatching a reviewer" | You're the coordinator — reviewing the diff inline burns the context window you need to keep driving the work. Dispatch a reviewer subagent: the diff and the evaluation live in its context, and only the findings come back to you. | | "The reviewer needs my whole session history to understand the change" | Hand it precisely crafted context, never your session's history. That keeps the reviewer on the work product, not your thought process. | ## Red Flags **Never:** - Skip review because "it's simple" - Ignore Critical issues - Proceed with unfixed Important issues - Argue with valid technical feedback **If reviewer wrong:** - Push back with technical reasoning - Show code/tests that prove it works - Request clarification See template at: [code-reviewer.md](code-reviewer.md) --- ## 7. subagent-driven-development - **Source:** https://github.com/obra/superpowers/blob/main/skills/subagent-driven-development/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/subagent-driven-development.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (6), referenced from this skill's directory: - `implementer-prompt.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/implementer-prompt.md - `re-review-prompt.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/re-review-prompt.md - `scripts/review-package` — https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/scripts/review-package - `scripts/sdd-workspace` — https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/scripts/sdd-workspace - `scripts/task-brief` — https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/scripts/task-brief - `task-reviewer-prompt.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/task-reviewer-prompt.md --- name: subagent-driven-development description: Use when executing implementation plans with independent tasks in the current session --- # Subagent-Driven Development Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end. **Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work. **Core principle:** Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration **Narration:** between tool calls, narrate at most one short line — the ledger and the tool results carry the record. **Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it. ## When to Use ```dot digraph when_to_use { "Have implementation plan?" [shape=diamond]; "Tasks mostly independent?" [shape=diamond]; "Stay in this session?" [shape=diamond]; "subagent-driven-development" [shape=box]; "executing-plans" [shape=box]; "Manual execution or brainstorm first" [shape=box]; "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"]; "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"]; "Tasks mostly independent?" -> "Stay in this session?" [label="yes"]; "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"]; "Stay in this session?" -> "subagent-driven-development" [label="yes"]; "Stay in this session?" -> "executing-plans" [label="no - parallel session"]; } ``` **vs. Executing Plans (parallel session):** - Same session (no context switch) - Fresh subagent per task (no context pollution) - Review after each task (spec compliance + code quality), broad review at the end - Faster iteration (no human-in-loop between tasks) ## The Process ```dot digraph process { rankdir=TB; subgraph cluster_per_task { label="Per Task"; "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box]; "Implementer asks questions?" [shape=diamond]; "Answer questions, provide context" [shape=box]; "Implementer implements, tests, commits, self-reviews" [shape=box]; "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box]; "Spec ✅ and quality approved?" [shape=diamond]; "Finding conflicts with plan text?" [shape=diamond]; "Ask human partner which governs" [shape=box]; "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box]; "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box]; "All findings addressed?" [shape=diamond]; "R = 5?" [shape=diamond]; "Adjudicate each open finding" [shape=box]; "Any load-bearing finding?" [shape=diamond]; "STOP: report BLOCKED to human partner" [shape=box]; "Park findings in ledger with rulings" [shape=box]; "Append completion to ledger, mark todo complete" [shape=box]; } "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box]; "More tasks remain?" [shape=diamond]; "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box]; "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box]; "Final review clean: delete this plan's workspace" [shape=box]; "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen]; "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)"; "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?"; "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"]; "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews"; "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"]; "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)"; "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?"; "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"]; "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"]; "Finding conflicts with plan text?" -> "Ask human partner which governs" [label="yes"]; "Ask human partner which governs" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model"; "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"]; "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)"; "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?"; "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"]; "All findings addressed?" -> "R = 5?" [label="no"]; "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"]; "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"]; "Adjudicate each open finding" -> "Any load-bearing finding?"; "Any load-bearing finding?" -> "STOP: report BLOCKED to human partner" [label="yes"]; "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"]; "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete"; "Append completion to ledger, mark todo complete" -> "More tasks remain?"; "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"]; "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"]; "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals"; "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace"; "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch"; } ``` ## Setup Ensure the work happens in an isolated workspace: use superpowers:using-git-worktrees to create one or verify the existing one. Never start implementation on a main/master branch without your human partner's explicit consent. Conversation memory does not survive compaction. In real sessions, controllers that lost their place have re-dispatched entire completed task sequences — the single most expensive failure observed. Track progress in a ledger file, not only in todos. - Each plan owns a workspace: at skill start, run this skill's `scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored directory (`/.superpowers/sdd//`), home to every artifact for THIS plan: ledger, briefs, reports, review packages. Another plan's directory is never yours to read or write. - Check for this plan's ledger at `/progress.md`. If its first line names your plan file, tasks with a `Task : complete` line are DONE — do not re-dispatch them; resume at the first task without one. A task whose last line is a fix round is mid-loop: resume the loop at the next round. A ledger whose first line names a different plan file — or a stray ledger at the old flat path `.superpowers/sdd/progress.md` — is another plan's progress: leave it in place and start your own, fresh. - Create the ledger with its identity as the first line: `# SDD ledger — plan: `. - The ledger is your recovery map: the commits it names exist in git even when your context no longer remembers creating them. After compaction, trust the ledger and `git log` over your own recollection. - `git clean -fdx` will destroy the workspace (it's git-ignored scratch); if that happens, recover from `git log`. Read the plan once, note its context and Global Constraints, and create a todo per task. Before dispatching Task 1, scan the plan once for conflicts: - tasks that contradict each other or the plan's Global Constraints - anything the plan explicitly mandates that the review rubric treats as a defect (a test that asserts nothing, verbatim duplication of a logic block) Present everything you find to your human partner as one batched question — each finding beside the plan text that mandates it, asking which governs — before execution begins, not one interrupt per discovery mid-plan. If the scan is clean, proceed without comment. The review loop remains the net for conflicts that only emerge from implementation. ## Model Selection Use the least powerful model that can handle each role to conserve cost and increase speed. **Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified. **Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model. **Architecture and design tasks**: use the most capable available model. The final whole-branch review is one of these — dispatch it on the most capable available model, not the session default. **Review tasks**: choose the model with the same judgment, scaled to the diff's size, complexity, and risk. A small mechanical diff does not need the most capable model; a subtle concurrency change does. Scoped re-reviews of small fix diffs take a cheap-to-mid tier. **Fix-loop escalation (rounds 4-5)**: use a model at least one tier above the implementer that got stuck. **Always specify the model explicitly when dispatching a subagent.** An omitted model inherits your session's model — often the most capable and most expensive — which silently defeats this section. **Turn count beats token price.** Wall-clock and context cost scale with how many turns a subagent takes, and the cheapest models routinely take 2-3× the turns on multi-step work — costing more overall. Use a mid-tier model as the floor for reviewers and for implementers working from prose descriptions. When the task's plan text contains the complete code to write, the implementation is transcription plus testing: use the cheapest tier for that implementer. Single-file mechanical fixes also take the cheapest tier. **Task complexity signals (implementation tasks):** - Touches 1-2 files with a complete spec → cheap model - Touches multiple files with integration concerns → standard model - Requires design judgment or broad codebase understanding → most capable model ## The Task Loop Everything you paste into a dispatch prompt — and everything a subagent prints back — stays resident in your context for the rest of the session and is re-read on every later turn. Hand artifacts over as files. ### 1. Dispatch the implementer Record BASE (`git rev-parse HEAD`) before dispatching — the review package and fix-round diffs need it. - **Task brief:** before dispatching an implementer, run this skill's `scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a uniquely named file and prints the path. Compose the dispatch so the brief stays the single source of requirements. Your dispatch should contain: (1) one line on where this task fits in the project; (2) the brief path, introduced as "read this first — it is your requirements, with the exact values to use verbatim"; (3) interfaces and decisions from earlier tasks that the brief cannot know; (4) your resolution of any ambiguity you noticed in the brief; (5) the report-file path and report contract. Exact values (numbers, magic strings, signatures, test cases) appear only in the brief. Never make a subagent read the whole plan file. - **Report file:** name the implementer's report file after the brief (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in the dispatch prompt. The implementer writes the full report there and returns only status, commits, a one-line test summary, and concerns. - A dispatch prompt describes one task, not the session's history. Do not paste accumulated prior-task summaries ("state after Tasks 1-3") into later dispatches — a real session's dispatch hit 42k chars of which 99% was pasted history. A fresh subagent needs its task, the interfaces it touches, and the global constraints. Nothing else. - If an earlier task parked a finding in the area this task touches, carry a pointer to that ledger entry in the dispatch. - Record the implementer's agent identity from the dispatch result — fix-loop rounds 1-3 resume this agent. - Never dispatch multiple implementation subagents in parallel (conflicts). Template: [implementer-prompt.md](implementer-prompt.md) ### 2. Handle the report Implementer subagents report one of four statuses. Handle each appropriately: **DONE:** Generate the review package (`scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path. **DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review. **NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch. **BLOCKED:** The implementer cannot complete the task. Assess the blocker: 1. If it's a context problem, provide more context and re-dispatch with the same model 2. If the task requires more reasoning, re-dispatch with a more capable model 3. If the task is too large, break it into smaller pieces 4. If the plan itself is wrong, escalate to the human **Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change. If the implementer asks questions — before starting or mid-task — answer clearly and completely, provide additional context if needed, and don't rush it into implementation. ### 3. Review the task Per-task reviews are task-scoped gates. The broad review happens once, at the final whole-branch review. Never skip the task review, and never accept a report missing either verdict — spec compliance AND task quality are both required. Implementer self-review never replaces the task review; both are needed. - Hand the reviewer its diff as a file: run this skill's `scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path it prints (or, without bash: `git log --oneline`, `git diff --stat`, and `git diff -U10` for the range, redirected to one uniquely named file). The output never enters your own context, and the reviewer sees the commit list, stat summary, and full diff with context in one Read call. Use the BASE you recorded before dispatching the implementer — never `HEAD~1`, which silently truncates multi-commit tasks. Never dispatch a task reviewer without a diff file. - **Reviewer inputs:** the task reviewer gets three paths — the same brief file, the report file, and the review package — plus the global constraints that bind the task. - The global-constraints block you hand the reviewer is its attention lens. Copy the binding requirements verbatim from the plan's Global Constraints section or the spec: exact values, exact formats, and the stated relationships between components ("same layout as X", "matches Y"). The reviewer's template already carries the process rules (YAGNI, test hygiene, review method) — the constraints block is for what THIS project's spec demands. - Do not add open-ended directives like "check all uses" or "run race tests if useful" without a concrete, task-specific reason - Do not ask a reviewer to re-run tests the implementer already ran on the same code — the implementer's report carries the test evidence - Do not pre-judge findings for the reviewer — never instruct a reviewer to ignore or not flag a specific issue. If you believe a finding would be a false positive, let the reviewer raise it and adjudicate it in the review loop. If the prompt you are writing contains "do not flag," "don't treat X as a defect," "at most Minor," or "the plan chose" — stop: you are pre-judging, usually to spare yourself a review loop. The task reviewer may report "⚠️ Cannot verify from diff" items — requirements that live in unchanged code or span tasks. These do not block the rest of the review, but you must resolve each one yourself before marking the task complete: you hold the plan and cross-task context the reviewer lacks. If you confirm an item is a real gap, treat it as a failed spec review — it enters the fix loop with the other findings. Template: [task-reviewer-prompt.md](task-reviewer-prompt.md) ### 4. The fix loop The loop triggers when the review reports spec ❌, any Critical or Important finding, or a ⚠️ item you confirmed as a real gap. Before the loop starts, two routes leave it immediately: - Record Minor findings in the progress ledger as you go (`Task : minor (deferred): `), and point the final whole-branch review at that list so it can triage which must be fixed before merge. A roll-up nobody reads is a silent discard. Minor findings never enter the loop. - A finding labeled plan-mandated — or any finding that conflicts with what the plan's text requires — is the human's decision, like any plan contradiction: present the finding and the plan text, ask which governs. Do not dismiss the finding because the plan mandates it, and do not dispatch a fix that contradicts the plan without asking. Everything else enters the loop. A fix round is one fix dispatch plus one scoped re-review. Five rounds maximum per task: **Rounds 1-3 — resume the original implementer.** Send it the open findings verbatim. Its context is intact: it knows the task, the code, and its own choices. If your harness cannot send another message to a live subagent, dispatch a fresh implementer carrying the brief path, the report-file path, and the findings — the report file is the persistent memory either way. **Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per Model Selection), with the brief path, the report-file path, the open findings, and this framing: "A prior implementer attempted this task [N] times; you own it now. Read the report file for what was tried." A loop that survives three resumes usually means the implementer cannot see its own problem — fresh eyes and a capability bump in one move. **Every round, either way:** the implementer fixes, re-runs the tests covering the amended code, appends its fix report to the same report file, and returns the short contract. Before re-dispatching the reviewer, confirm the fix report contains the covering tests, the command run, and the output; dispatch the re-review once all three are present. Name the covering test files in the fix message — a one-line fix does not need the whole suite. **The re-review is scoped.** Run `scripts/review-package PLAN_FILE FIX_BASE HEAD` where FIX_BASE is the head the previous review saw, and dispatch [re-review-prompt.md](re-review-prompt.md) with the findings list, the brief, the report file, and the printed diff path. The re-reviewer verdicts each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix diff only. New Critical/Important breakage in the fix diff joins the open findings list. Out-of-scope observations go to the ledger as deferred minors — they never extend the loop. **After each round,** append to the ledger: `Task : fix round /5 ( addressed, open — ; commits ..)` Never fix findings yourself in the controller session — your context stays clean for coordination, and controller fixes skip review. **The breaker.** When round 5's re-review still leaves findings open, stop dispatching. Adjudicate each open finding yourself — you hold the plan and the cross-task context the reviewer lacks: - **The reviewer is wrong, or the point is contestable:** park it — `Task : parked — — ruling: `. The final review sees both sides. - **Real, but nothing downstream builds on it:** park it the same way, with a ruling that says it's real and deferred. - **Real and load-bearing** — a later task builds on it, or it reveals a plan defect: STOP. Append `Task : BLOCKED — ` and report to your human partner with the finding, the plan text it collides with, and the fix history. Parking a structural failure lets every dependent task build on it and hands the final review a problem it cannot fix either. Adjudicate only at the cap. Adjudicating earlier to end a loop is pre-judging with a different name. Every adjudication is a ledger entry — a silent discard is forbidden. ### 5. Complete the task When the review comes back clean — or every open finding is parked with a ruling at the cap — append the completion line to the ledger in the same message as your other bookkeeping: - `Task : complete (commits .., review clean)` - `Task : complete (commits .., parked)` after a tripped breaker Then mark the todo complete and move on. Never move to the next task while the review has open Critical/Important issues that are neither fixed nor parked-with-ruling at the cap. ## Final Review The final whole-branch review gets a package too: run `scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the branch started from, e.g. `git merge-base main HEAD`) and include the printed path in the final review dispatch, so the final reviewer reads one file instead of re-deriving the branch diff with git commands. Dispatch on the most capable available model (see Model Selection), using superpowers:requesting-code-review's [code-reviewer.md](../requesting-code-review/code-reviewer.md). Point it at the ledger's deferred-minor and parked lines so it can triage which must be fixed before merge. If the final whole-branch review returns findings, dispatch ONE fix subagent with the complete findings list — not one fixer per finding. Per-finding fixers each rebuild context and re-run suites; a real session's final-review fix wave cost more than all its tasks combined. Then run exactly one scoped re-review of the fix wave (`scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range, [re-review-prompt.md](re-review-prompt.md)). Adjudicate any residual findings as in the task loop's breaker: park with rulings, or stop on load-bearing ones. There is no second fix wave — residual load-bearing findings surface to your human partner when finishing-a-development-branch presents the options. ## Finish When the final whole-branch review is clean and its fixes are merged, delete this plan's workspace (`rm -rf `) — the git history is the record now. Sibling directories belong to other plans; leave them alone. Use superpowers:finishing-a-development-branch. ## Common Rationalizations | Excuse | Reality | |--------|---------| | "Close enough on spec compliance" | Reviewer found spec gaps = not done. Fix or hit the cap and adjudicate — those are the only exits. | | "I'll fix it myself, dispatching is overhead" | Controller fixes pollute your context and skip review. Resume the implementer. | | "One more round will converge" | Past the cap, rounds don't converge — the failure is structural. Adjudicate and route. | | "The reviewer will just find something new anyway" | Scoped re-reviews verify fixes; they cannot wander. New findings on untouched code go to the ledger, not the loop. | | "This finding is obviously wrong, I'll drop it" | You adjudicate only at the cap, and every ruling is a ledger entry. Silent discards are forbidden. | | "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. | | "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. | | "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. | ## Example Workflow ``` You: I'm using Subagent-Driven Development to execute this plan. [Setup: worktree verified] [Read plan file once: docs/superpowers/plans/feature-plan.md] [Resolve workspace: scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start] [Create todos for all tasks] Task 1: Hook installation script [Run task-brief for Task 1; dispatch implementer with brief + report paths + context] Implementer: "Before I begin - should the hook be installed at user or system level?" You: "User level (~/.config/superpowers/hooks/)" Implementer: [Later] - Implemented install-hook command - Added tests, 5/5 passing - Self-review: Found I missed --force flag, added it - Committed [Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path] Task reviewer: Spec ✅ - all requirements met, nothing extra. Strengths: Good test coverage, clean. Issues: None. Task quality: Approved. [Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)] Task 2: Recovery modes [Run task-brief for Task 2; dispatch implementer with brief + report paths + context] Implementer: [No questions] - Added verify/repair modes - 8/8 tests passing - Committed [Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path] Task reviewer: Spec ❌: - Missing: Progress reporting (spec says "report every 100 items") Issues (Important): Magic number (100) [Fix round 1: resume the implementer with both findings] Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant. Re-ran test/recovery.test.js — 10/10 passing. Fix report appended. [Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review] Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41). Magic number — ADDRESSED (src/recovery.js:7). New breakage: none. Verdict: all findings addressed. [Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)] [Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)] ... [After all tasks] [Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model] Final reviewer: All requirements met. Deferred minors triaged: none block merge. [Delete this plan's workspace — the record now lives in git] Done! Using superpowers:finishing-a-development-branch. ``` --- ## 8. systematic-debugging - **Source:** https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/systematic-debugging.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (10), referenced from this skill's directory: - `condition-based-waiting-example.ts` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/condition-based-waiting-example.ts - `condition-based-waiting.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/condition-based-waiting.md - `CREATION-LOG.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/CREATION-LOG.md - `defense-in-depth.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/defense-in-depth.md - `find-polluter.sh` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/find-polluter.sh - `root-cause-tracing.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/root-cause-tracing.md - `test-academic.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/test-academic.md - `test-pressure-1.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/test-pressure-1.md - `test-pressure-2.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/test-pressure-2.md - `test-pressure-3.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/systematic-debugging/test-pressure-3.md --- name: systematic-debugging description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes --- # Systematic Debugging ## Overview **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure. **Violating the letter of this process is violating the spirit of debugging.** ## The Iron Law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` If you haven't completed Phase 1, you cannot propose fixes. ## When to Use Use for ANY technical issue: - Test failures - Bugs in production - Unexpected behavior - Performance problems - Build failures - Integration issues **Use this ESPECIALLY when:** - Under time pressure (emergencies make guessing tempting) - "Just one quick fix" seems obvious - You've already tried multiple fixes - Previous fix didn't work - You don't fully understand the issue **Don't skip when:** - Issue seems simple (simple bugs have root causes too) - You're in a hurry (rushing guarantees rework) - Manager wants it fixed NOW (systematic is faster than thrashing) ## The Four Phases You MUST complete each phase before proceeding to the next. ### Phase 1: Root Cause Investigation **BEFORE attempting ANY fix:** 1. **Read Error Messages Carefully** - Don't skip past errors or warnings - They often contain the exact solution - Read stack traces completely - Note line numbers, file paths, error codes 2. **Reproduce Consistently** - Can you trigger it reliably? - What are the exact steps? - Does it happen every time? - If not reproducible → gather more data, don't guess 3. **Check Recent Changes** - What changed that could cause this? - Git diff, recent commits - New dependencies, config changes - Environmental differences 4. **Gather Evidence in Multi-Component Systems** **WHEN system has multiple components (CI → build → signing, API → service → database):** **BEFORE proposing fixes, add diagnostic instrumentation:** ``` For EACH component boundary: - Log what data enters component - Log what data exits component - Verify environment/config propagation - Check state at each layer Run once to gather evidence showing WHERE it breaks THEN analyze evidence to identify failing component THEN investigate that specific component ``` **Example (multi-layer system):** ```bash # Layer 1: Workflow echo "=== Secrets available in workflow: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # Layer 2: Build script echo "=== Env vars in build script: ===" env | grep IDENTITY || echo "IDENTITY not in environment" # Layer 3: Signing script echo "=== Keychain state: ===" security list-keychains security find-identity -v # Layer 4: Actual signing codesign --sign "$IDENTITY" --verbose=4 "$APP" ``` **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗) 5. **Trace Data Flow** **WHEN error is deep in call stack:** See `root-cause-tracing.md` in this directory for the complete backward tracing technique. **Quick version:** - Where does bad value originate? - What called this with bad value? - Keep tracing up until you find the source - Fix at source, not at symptom ### Phase 2: Pattern Analysis **Find the pattern before fixing:** 1. **Find Working Examples** - Locate similar working code in same codebase - What works that's similar to what's broken? 2. **Compare Against References** - If implementing pattern, read reference implementation COMPLETELY - Don't skim - read every line - Understand the pattern fully before applying 3. **Identify Differences** - What's different between working and broken? - List every difference, however small - Don't assume "that can't matter" 4. **Understand Dependencies** - What other components does this need? - What settings, config, environment? - What assumptions does it make? ### Phase 3: Hypothesis and Testing **Scientific method:** 1. **Form Single Hypothesis** - State clearly: "I think X is the root cause because Y" - Write it down - Be specific, not vague 2. **Test Minimally** - Make the SMALLEST possible change to test hypothesis - One variable at a time - Don't fix multiple things at once 3. **Verify Before Continuing** - Did it work? Yes → Phase 4 - Didn't work? Form NEW hypothesis - DON'T add more fixes on top 4. **When You Don't Know** - Say "I don't understand X" - Don't pretend to know - Ask for help - Research more ### Phase 4: Implementation **Fix the root cause, not the symptom:** 1. **Create Failing Test Case** - Simplest possible reproduction - 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 2. **Implement Single Fix** - Address the root cause identified - ONE change at a time - No "while I'm here" improvements - No bundled refactoring 3. **Verify Fix** - Test passes now? - No other tests broken? - Issue actually resolved? - Use the `superpowers:verification-before-completion` skill before claiming success 4. **If Fix Doesn't Work** - STOP - Count: How many fixes have you tried? - If < 3: Return to Phase 1, re-analyze with new information - **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** **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? **Discuss with your human partner before attempting more fixes** This is NOT a failed hypothesis - this is a wrong architecture. ## Red Flags - STOP and Follow Process If you catch yourself thinking: - "Quick fix for now, investigate later" - "Just try changing X and see if it works" - "Add multiple changes, run tests" - "Skip the test, I'll manually verify" - "It's probably X, let me fix that" - "I don't fully understand but this might work" - "Pattern says X but I'll adapt it differently" - "Here are the main problems: [lists fixes without investigation]" - Proposing solutions before tracing data flow - **"One more fix attempt" (when already tried 2+)** - **Each fix reveals new problem in different place** **ALL of these mean: STOP. Return to Phase 1.** **If 3+ fixes failed:** Question the architecture (see Phase 4.5) ## your human partner's Signals You're Doing It Wrong **Watch for these redirections:** - "Is that not happening?" - You assumed without verifying - "Will it show us...?" - You should have added evidence gathering - "Stop guessing" - You're proposing fixes without understanding - "Ultra-think this" - Question fundamentals, not just symptoms - "We're stuck?" (frustrated) - Your approach isn't working **When you see these:** STOP. Return to Phase 1. ## Common Rationalizations | Excuse | Reality | |--------|---------| | "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. | | "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. | | "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. | | "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. | | "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. | ## Quick Reference | Phase | Key Activities | Success Criteria | |-------|---------------|------------------| | **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY | | **2. Pattern** | Find working examples, compare | Identify differences | | **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis | | **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass | ## When Process Reveals "No Root Cause" If systematic investigation reveals issue is truly environmental, timing-dependent, or external: 1. You've completed the process 2. Document what you investigated 3. Implement appropriate handling (retry, timeout, error message) 4. Add monitoring/logging for future investigation **But:** 95% of "no root cause" cases are incomplete investigation. ## Supporting Techniques These techniques are part of systematic debugging and available in this directory: - **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger - **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling --- ## 9. test-driven-development - **Source:** https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/test-driven-development/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/test-driven-development.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (1), referenced from this skill's directory: - `writing-good-tests.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/test-driven-development/writing-good-tests.md --- name: test-driven-development description: Use when implementing any feature or bugfix, before writing implementation code --- # Test-Driven Development (TDD) ## Overview Write the test first. Watch it fail. Write minimal code to pass. **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing. **Violating the letter of the rules is violating the spirit of the rules.** ## When to Use **Always:** - New features - Bug fixes - Refactoring - Behavior changes **Exceptions (ask your human partner):** - Throwaway prototypes - Generated code - Configuration files Thinking "skip TDD just this once"? Stop. That's rationalization. ## The Iron Law ``` NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST ``` Write code before the 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 Implement fresh from tests. Period. ## Red-Green-Refactor ```dot digraph tdd_cycle { rankdir=LR; red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"]; verify_red [label="Verify fails\ncorrectly", shape=diamond]; green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"]; verify_green [label="Verify passes\nAll green", shape=diamond]; refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"]; next [label="Next", shape=ellipse]; red -> verify_red; verify_red -> green [label="yes"]; verify_red -> red [label="wrong\nfailure"]; green -> verify_green; verify_green -> refactor [label="yes"]; verify_green -> green [label="no"]; refactor -> verify_green [label="stay\ngreen"]; verify_green -> next; next -> red; } ``` ### RED - Write Failing Test Write one minimal test showing what should happen. ```typescript 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); }); ``` Clear name, tests real behavior, one thing ```typescript test('retry works', async () => { const mock = jest.fn() .mockRejectedValueOnce(new Error()) .mockRejectedValueOnce(new Error()) .mockResolvedValueOnce('success'); await retryOperation(mock); expect(mock).toHaveBeenCalledTimes(3); }); ``` Vague name, tests mock not code **Requirements:** - One behavior - Clear name - Real code (no mocks unless unavoidable) ### Verify RED - Watch It Fail **MANDATORY. Never skip.** ```bash npm test path/to/test.test.ts ``` Confirm: - Test fails (not errors) - Failure message is expected - Fails because feature missing (not typos) **Test passes?** You're testing existing behavior. Fix test. **Test errors?** Fix error, re-run until it fails correctly. ### GREEN - Minimal Code Write simplest code to pass the test. ```typescript async function retryOperation(fn: () => Promise): Promise { for (let i = 0; i < 3; i++) { try { return await fn(); } catch (e) { if (i === 2) throw e; } } throw new Error('unreachable'); } ``` Just enough to pass ```typescript async function retryOperation( fn: () => Promise, options?: { maxRetries?: number; backoff?: 'linear' | 'exponential'; onRetry?: (attempt: number) => void; } ): Promise { // YAGNI } ``` Over-engineered Don't add features, refactor other code, or "improve" beyond the test. ### Verify GREEN - Watch It Pass **MANDATORY.** ```bash npm test path/to/test.test.ts ``` Confirm: - Test passes - Other tests still pass - Output pristine (no errors, warnings) **Test fails?** Fix code, not test. **Other tests fail?** Fix now. ### REFACTOR - Clean Up After green only: - Remove duplication - Improve names - Extract helpers Keep tests green. Don't add behavior. ### Repeat Next failing test for next feature. ## Good Tests | Quality | Good | Bad | |---------|------|-----| | **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` | | **Clear** | Name describes behavior | `test('test1')` | | **Shows intent** | Demonstrates desired API | Obscures what code should do | When writing or changing any test, read [writing-good-tests.md](writing-good-tests.md) for the rules that keep tests honest: - Name the production change that would make the test fail — before writing it - Assert on real behavior, never on mock behavior - Keep test-only code in test utilities, out of production classes - Understand a dependency's side effects before mocking it ## Common Rationalizations | Excuse | Reality | |--------|---------| | "Too simple to test" | Simple code breaks. Test takes 30 seconds. | | "I'll test after" | Tests written after pass immediately — which proves nothing. They may test the wrong thing, test the implementation instead of the behavior, or miss the edge case you forgot. You never watched it fail, so you never proved it can catch the bug. Test-first forces that failure. | | "Tests after achieve same goals (spirit not ritual)" | Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests written after are biased by the code you already wrote — you verify the cases you remembered, not the ones you'd have discovered. Coverage without proof the tests work. | | "Already manually tested" | Manual testing is ad-hoc: no record of what you covered, no way to re-run it when the code changes, easy to forget cases under pressure. "Worked when I tried it" ≠ comprehensive. Automated tests run the same way every time. | | "Deleting X hours is wasteful" | Sunk cost fallacy — that time is already spent either way. The real choice: rewrite with TDD (high confidence) vs. keep it and bolt tests on after (low confidence, likely bugs). Keeping code you can't trust is the waste. | | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. | | "Need to explore first" | Fine. Throw away exploration, start with TDD. | | "Test hard = design unclear" | Listen to test. Hard to test = hard to use. | | "TDD will slow me down" | TDD IS the pragmatic path: catches bugs before commit, prevents regressions, lets you refactor without fear. "Pragmatic" shortcuts mean debugging in production — slower, not faster. | | "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. | | "Existing code has no tests" | You're improving it. Add tests for existing code. | ## Red Flags - STOP and Start Over - Code before test - Test after implementation - Test passes immediately - Can't explain why test failed - Tests added "later" - Rationalizing "just this once" - "I already manually tested it" - "Tests after achieve the same purpose" - "It's about spirit not ritual" - "Keep as reference" or "adapt existing code" - "Already spent X hours, deleting is wasteful" - "TDD is dogmatic, I'm being pragmatic" - "This is different because..." **All of these mean: Delete code. Start over with TDD.** ## Example: Bug Fix **Bug:** Empty email accepted **RED** ```typescript test('rejects empty email', async () => { const result = await submitForm({ email: '' }); expect(result.error).toBe('Email required'); }); ``` **Verify RED** ```bash $ npm test FAIL: expected 'Email required', got undefined ``` **GREEN** ```typescript function submitForm(data: FormData) { if (!data.email?.trim()) { return { error: 'Email required' }; } // ... } ``` **Verify GREEN** ```bash $ npm test PASS ``` **REFACTOR** Extract validation for multiple fields if needed. ## Verification Checklist Before marking work complete: - [ ] Every new function/method has a test - [ ] Watched each test fail before implementing - [ ] Each test failed for expected reason (feature missing, not typo) - [ ] Wrote minimal code to pass each test - [ ] All tests pass - [ ] Output pristine (no errors, warnings) - [ ] Tests use real code (mocks only if unavoidable) - [ ] Edge cases and errors covered Can't check all boxes? You skipped TDD. Start over. ## When Stuck | Problem | Solution | |---------|----------| | Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. | | Test too complicated | Design too complicated. Simplify interface. | | Must mock everything | Code too coupled. Use dependency injection. | | Test setup huge | Extract helpers. Still complex? Simplify design. | ## Debugging Integration Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression. Never fix bugs without a test. ## Final Rule ``` Production code → test exists and failed first Otherwise → not TDD ``` No exceptions without your human partner's permission. --- ## 10. using-git-worktrees - **Source:** https://github.com/obra/superpowers/blob/main/skills/using-git-worktrees/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/using-git-worktrees/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/using-git-worktrees.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: using-git-worktrees description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback --- # Using Git Worktrees ## Overview Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available. **Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness. **Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace." ## Step 0: Detect Existing Isolation **Before creating anything, check if you are already in an isolated workspace.** ```bash GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P) GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P) BRANCH=$(git branch --show-current) ``` **Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule: ```bash # If this returns a path, you're in a submodule, not a worktree — treat as normal repo git rev-parse --show-superproject-working-tree 2>/dev/null ``` **If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree. Report with branch state: - On a branch: "Already in isolated workspace at `` on branch ``." - Detached HEAD: "Already in isolated workspace at `` (detached HEAD, externally managed). Branch creation needed at finish time." **If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree: > "Would you like me to set up an isolated worktree? It protects your current branch from changes." Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2. ## Step 1: Create Isolated Workspace **You have two mechanisms. Try them in this order.** ### 1a. Native Worktree Tools (preferred) The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2. Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage. Only proceed to Step 1b if you have no native worktree tool available. ### 1b. Git Worktree Fallback **Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git. #### Directory Selection Follow this priority order. Explicit user preference always beats observed filesystem state. 1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking. 2. **Check for an existing project-local worktree directory:** ```bash ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative ``` If found, use it. If both exist, `.worktrees` wins. 3. **If there is no other guidance available**, default to `.worktrees/` at the project root. #### Safety Verification (project-local directories only) **MUST verify directory is ignored before creating worktree:** ```bash git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null ``` **If NOT ignored:** Add to .gitignore, commit the change, then proceed. **Why critical:** Prevents accidentally committing worktree contents to repository. #### Create the Worktree ```bash # Determine path based on chosen location path="$LOCATION/$BRANCH_NAME" git worktree add "$path" -b "$BRANCH_NAME" cd "$path" ``` **Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place. ## Step 2: Project Setup Auto-detect and run appropriate setup: ```bash # Node.js if [ -f package.json ]; then npm install; fi # Rust if [ -f Cargo.toml ]; then cargo build; fi # Python if [ -f requirements.txt ]; then pip install -r requirements.txt; fi if [ -f pyproject.toml ]; then poetry install; fi # Go if [ -f go.mod ]; then go mod download; fi ``` ## Step 3: Verify Clean Baseline Run tests to ensure workspace starts clean: ```bash # Use project-appropriate command npm test / cargo test / pytest / go test ./... ``` **If tests fail:** Report failures, ask whether to proceed or investigate. **If tests pass:** Report ready. ### Report ``` Worktree ready at Tests passing ( tests, 0 failures) Ready to implement ``` ## Quick Reference | Situation | Action | |-----------|--------| | Already in linked worktree | Skip creation (Step 0) | | In a submodule | Treat as normal repo (Step 0 guard) | | Native worktree tool available | Use it (Step 1a) | | No native tool | Git worktree fallback (Step 1b) | | `.worktrees/` exists | Use it (verify ignored) | | `worktrees/` exists | Use it (verify ignored) | | Both exist | Use `.worktrees/` | | Neither exists | Check instruction file, then default `.worktrees/` | | Directory not ignored | Add to .gitignore + commit | | Permission error on create | Sandbox fallback, work in place | | Tests fail during baseline | Report failures + ask | | No package.json/Cargo.toml | Skip dependency install | ## Common Rationalizations | Excuse | Reality | |--------|---------| | "I'm obviously not in a worktree — no need to check" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. | | "`git worktree add` is quicker than hunting for a native tool" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. | | "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. | | "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. | | "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. | --- ## 11. using-superpowers - **Source:** https://github.com/obra/superpowers/blob/main/skills/using-superpowers/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/using-superpowers/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/using-superpowers.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (4), referenced from this skill's directory: - `references/antigravity-tools.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/using-superpowers/references/antigravity-tools.md - `references/codex-tools.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/using-superpowers/references/codex-tools.md - `references/gemini-tools.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/using-superpowers/references/gemini-tools.md - `references/pi-tools.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/using-superpowers/references/pi-tools.md --- name: using-superpowers description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions --- If you were dispatched as a subagent to execute a specific task, ignore this skill. If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill. IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT. This is not negotiable. You cannot rationalize your way out of this. ## The Rule **Invoke relevant or requested skills BEFORE any response or action** — including clarifying questions, exploring the codebase, or checking files. If it turns out wrong for the situation, you don't have to use it. **Before entering plan mode:** if you haven't already brainstormed, invoke the brainstorming skill first. Then announce "Using [skill] to [purpose]" and follow the skill exactly. If it has a checklist, create a todo per item. ## Skill Priority When multiple skills apply, process skills come first — they set the approach, then implementation skills (frontend-design, etc.) carry it out. Brainstorming and systematic-debugging are Superpowers' most common process skills, but the rule holds for any of them. - "Let's build X" → superpowers:brainstorming first, then implementation skills. - "Fix this bug" → superpowers:systematic-debugging first, then domain skills. ## Red Flags These thoughts mean STOP—you're rationalizing: | Thought | Reality | |---------|---------| | "This is just a simple question" | Questions are tasks. Check for skills. | | "I need more context first" | Skill check comes BEFORE clarifying questions. | | "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. | | "I can check git/files quickly" | Files lack conversation context. Check for skills. | | "Let me gather information first" | Skills tell you HOW to gather information. | | "This doesn't need a formal skill" | If a skill exists, use it. | | "I remember this skill" | Skills evolve. Read current version. | | "This doesn't count as a task" | Action = task. Check for skills. | | "The skill is overkill" | Simple things become complex. Use it. | | "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. | ## Platform Adaptation If your harness appears here, read its reference file for special instructions: - Codex: `references/codex-tools.md` - Pi: `references/pi-tools.md` - Antigravity: `references/antigravity-tools.md` ## User Instructions User instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior. Only skip skill workflows or instructions when your human partner has explicitly told you to. --- ## 12. verification-before-completion - **Source:** https://github.com/obra/superpowers/blob/main/skills/verification-before-completion/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/verification-before-completion/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/verification-before-completion.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: verification-before-completion description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always --- # Verification Before Completion ## Overview **Core principle:** Evidence before claims, always. **Violating the letter of this rule is violating the spirit of this rule.** ## The Iron Law ``` NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE ``` If you haven't run the verification command in this message, you cannot claim it passes. ## The Gate Function ``` BEFORE claiming any status or expressing satisfaction: 1. IDENTIFY: What command proves this claim? 2. RUN: Execute the FULL command (fresh, complete) 3. READ: Full output, check exit code, count failures 4. VERIFY: Does output confirm the claim? - If NO: State actual status with evidence - If YES: State claim WITH evidence 5. ONLY THEN: Make the claim Skip any step = lying, not verifying ``` ## Common Failures | Claim | Requires | Not Sufficient | |-------|----------|----------------| | Tests pass | Test command output: 0 failures | Previous run, "should pass" | | Linter clean | Linter output: 0 errors | Partial check, extrapolation | | Build succeeds | Build command: exit 0 | Linter passing, logs look good | | Bug fixed | Test original symptom: passes | Code changed, assumed fixed | | Regression test works | Red-green cycle verified | Test passes once | | Agent completed | VCS diff shows changes | Agent reports "success" | | Requirements met | Line-by-line checklist | Tests passing | ## Red Flags - STOP - Using "should", "probably", "seems to" - Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.) - About to commit/push/PR without verification - Trusting agent success reports - Relying on partial verification - Thinking "just this once" - Tired and wanting work over - **ANY wording implying success without having run verification** ## Rationalization Prevention | Excuse | Reality | |--------|---------| | "Should work now" | RUN the verification | | "I'm confident" | Confidence ≠ evidence | | "Just this once" | No exceptions | | "Linter passed" | Linter ≠ compiler | | "Agent said success" | Verify independently | | "I'm tired" | Exhaustion ≠ excuse | | "Partial check is enough" | Partial proves nothing | | "Different words so rule doesn't apply" | Spirit over letter | ## Key Patterns **Tests:** ``` ✅ [Run test command] [See: 34/34 pass] "All tests pass" ❌ "Should pass now" / "Looks correct" ``` **Regression tests (TDD Red-Green):** ``` ✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass) ❌ "I've written a regression test" (without red-green verification) ``` **Build:** ``` ✅ [Run build] [See: exit 0] "Build passes" ❌ "Linter passed" (linter doesn't check compilation) ``` **Requirements:** ``` ✅ Re-read plan → Create checklist → Verify each → Report gaps or completion ❌ "Tests pass, phase complete" ``` **Agent delegation:** ``` ✅ Agent reports success → Check VCS diff → Verify changes → Report actual state ❌ Trust agent report ``` ## When To Apply **ALWAYS before:** - ANY variation of success/completion claims - ANY expression of satisfaction - ANY positive statement about work state - Committing, PR creation, task completion - Moving to next task - Delegating to agents **Rule applies to:** - Exact phrases - Paraphrases and synonyms - Implications of success - ANY communication suggesting completion/correctness --- ## 13. writing-plans - **Source:** https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-plans/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/writing-plans.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (1), referenced from this skill's directory: - `plan-document-reviewer-prompt.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-plans/plan-document-reviewer-prompt.md --- name: writing-plans description: Use when you have a spec or requirements for a multi-step task, before touching code --- # Writing Plans ## Overview Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well. **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." **Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time. **Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-.md` - (User preferences for plan location override this default) ## Scope Check If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own. ## File Structure Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in. - Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility. - You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much. - Files that change together should live together. Split by responsibility, not by technical layer. - In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable. This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently. ## Task Right-Sizing A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. When drawing task boundaries: fold setup, configuration, scaffolding, and documentation steps into the task whose deliverable needs them; split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task ends with an independently testable deliverable. ## Bite-Sized Task Granularity **Each step is one action (2-5 minutes):** - "Write the failing test" - step - "Run it to make sure it fails" - step - "Implement the minimal code to make the test pass" - step - "Run the tests and make sure they pass" - step - "Commit" - step ## Plan Document Header **Every plan MUST start with this header:** ```markdown # [Feature Name] Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** [One sentence describing what this builds] **Architecture:** [2-3 sentences about approach] **Tech Stack:** [Key technologies/libraries] ## Global Constraints [The spec's project-wide requirements — version floors, dependency limits, naming and copy rules, platform requirements — one line each, with exact values copied verbatim from the spec. Every task's requirements implicitly include this section.] --- ``` ## Task Structure ````markdown ### 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` **Interfaces:** - Consumes: [what this task uses from earlier tasks — exact signatures] - Produces: [what later tasks rely on — exact function names, parameter and return types. A task's implementer sees only their own task; this block is how they learn the names and types neighboring tasks use.] - [ ] **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** ```python 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** ```bash git add tests/path/test.py src/path/file.py git commit -m "feat: add specific feature" ``` ```` ## No Placeholders Every step must contain the actual content an engineer needs. These are **plan failures** — never write them: - "TBD", "TODO", "implement later", "fill in details" - "Add appropriate error handling" / "add validation" / "handle edge cases" - "Write tests for the above" (without actual test code) - "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order) - Steps that describe what to do without showing how (code blocks required for code steps) - References to types, functions, or methods not defined in any task ## Self-Review After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch. **1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps. **2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them. **3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug. If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task. ## Execution Handoff After saving the plan, offer execution choice: **"Plan complete and saved to `docs/superpowers/plans/.md`. Two execution options:** **1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration **2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints **Which approach?"** **If Subagent-Driven chosen:** - **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development - Fresh subagent per task + two-stage review **If Inline Execution chosen:** - **REQUIRED SUB-SKILL:** Use superpowers:executing-plans - Batch execution with checkpoints for review --- ## 14. writing-skills - **Source:** https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md - **Raw:** https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/SKILL.md - **Markdown:** https://skillsdocs.com/obra/superpowers/writing-skills.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (6), referenced from this skill's directory: - `anthropic-best-practices.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/anthropic-best-practices.md - `examples/CLAUDE_MD_TESTING.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/examples/CLAUDE_MD_TESTING.md - `graphviz-conventions.dot` — https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/graphviz-conventions.dot - `persuasion-principles.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/persuasion-principles.md - `render-graphs.js` — https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/render-graphs.js - `testing-skills-with-subagents.md` — https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/testing-skills-with-subagents.md --- name: writing-skills description: Use when creating new skills, editing existing skills, or verifying skills work before deployment --- # Writing Skills ## Overview **Writing skills IS Test-Driven Development applied to process documentation.** **Personal skills live in your runtime's skills directory** (`~/.claude/skills/` on Claude Code) — see [codex-tools.md](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias. You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes). **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing. **REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation. **Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill. ## What is a Skill? A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches. **Skills are:** Reusable techniques, patterns, tools, reference guides **Skills are NOT:** Narratives about how you solved a problem once ## TDD Mapping for Skills | 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 | | **Write test first** | Run baseline scenario BEFORE writing skill | | **Watch it fail** | Document exact rationalizations agent uses | | **Minimal code** | Write skill addressing those specific violations | | **Watch it pass** | Verify agent now complies | | **Refactor cycle** | Find new rationalizations → plug → re-verify | The entire skill creation process follows RED-GREEN-REFACTOR. ## When to Create a Skill **Create when:** - Technique wasn't intuitively obvious to you - You'd reference this again across projects - Pattern applies broadly (not project-specific) - Others would benefit **Don't create for:** - One-off solutions - Standard practices well-documented elsewhere - Project-specific conventions (put in your instructions file) - Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls) ## Skill Types ### Technique Concrete method with steps to follow (condition-based-waiting, root-cause-tracing) ### Pattern Way of thinking about problems (flatten-with-flags, test-invariants) ### Reference API docs, syntax guides, tool documentation (office docs) ## Directory Structure ``` skills/ skill-name/ SKILL.md # Main reference (required) supporting-file.* # Only if needed ``` **Flat namespace** - all skills in one searchable namespace **Separate files for:** 1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax 2. **Reusable tools** - Scripts, utilities, templates **Keep inline:** - Principles and concepts - Code patterns (< 50 lines) - Everything else ## SKILL.md Structure **Frontmatter (YAML):** - Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields) - Max 1024 characters total - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars) - `description`: Third-person, describes ONLY when to use (NOT what it does) - Start with "Use when..." to focus on triggering conditions - Include specific symptoms, situations, and contexts - **NEVER summarize the skill's process or workflow** (see SDO section for why) - Keep under 500 characters if possible ```markdown --- name: Skill-Name-With-Hyphens description: Use when [specific triggering conditions and symptoms] --- # Skill Name ## Overview What is this? Core principle in 1-2 sentences. ## When to Use [Small inline flowchart IF decision non-obvious] Bullet list with SYMPTOMS and use cases When NOT to use ## Core Pattern (for techniques/patterns) Before/after code comparison ## Quick Reference Table or bullets for scanning common operations ## Implementation Inline code for simple patterns Link to file for heavy reference or reusable tools ## Common Mistakes What goes wrong + fixes ## Real-World Impact (optional) Concrete results ``` ## Skill Discovery Optimization (SDO) **Critical for discovery:** Future agents need to FIND your skill ### 1. Rich Description Field **Purpose:** Your agent reads the description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?" **Format:** Start with "Use when..." to focus on triggering conditions **CRITICAL: Description = When to Use, NOT What the Skill Does** The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description. **Why this matters:** Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality). When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process. **The trap:** Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip. ```yaml # ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill description: Use when executing plans - dispatches subagent per task with code review between tasks # ❌ BAD: Too much process detail description: Use for TDD - write test first, watch it fail, write minimal code, refactor # ✅ GOOD: Just triggering conditions, no workflow summary description: Use when executing implementation plans with independent tasks in the current session # ✅ GOOD: Triggering conditions only description: Use when implementing any feature or bugfix, before writing implementation code ``` **Content:** - Use concrete triggers, symptoms, and situations that signal this skill applies - Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep) - Keep triggers technology-agnostic unless the skill itself is technology-specific - If skill is technology-specific, make that explicit in the trigger - Write in third person (injected into system prompt) - **NEVER summarize the skill's process or workflow** ```yaml # ❌ BAD: Too abstract, vague, doesn't include when to use description: For async testing # ❌ BAD: First person description: I can help you with async tests when they're flaky # ❌ BAD: Mentions technology but skill isn't specific to it description: Use when tests use setTimeout/sleep and are flaky # ✅ GOOD: Starts with "Use when", describes problem, no workflow description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently # ✅ GOOD: Technology-specific skill with explicit trigger description: Use when using React Router and handling authentication redirects ``` ### 2. Keyword Coverage Use words an agent would search for: - Error messages: "Hook timed out", "ENOTEMPTY", "race condition" - Symptoms: "flaky", "hanging", "zombie", "pollution" - Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach" - Tools: Actual commands, library names, file types ### 3. Descriptive Naming **Use active voice, verb-first:** - ✅ `creating-skills` not `skill-creation` - ✅ `condition-based-waiting` not `async-test-helpers` ### 4. Token Efficiency (Critical) **Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts. **Target word counts:** - getting-started workflows: <150 words each - Frequently-loaded skills: <200 words total - Other skills: <500 words (still be concise) **Techniques:** **Move details to tool help:** ```bash # ❌ BAD: Document all flags in SKILL.md search-conversations supports --text, --both, --after DATE, --before DATE, --limit N # ✅ GOOD: Reference --help search-conversations supports multiple modes and filters. Run --help for details. ``` **Use cross-references:** ```markdown # ❌ BAD: Repeat workflow details When searching, dispatch subagent with template... [20 lines of repeated instructions] # ✅ GOOD: Reference other skill Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow. ``` **Compress examples:** ```markdown # ❌ BAD: Verbose example (42 words) your human partner: "How did we handle authentication errors in React Router before?" You: I'll search past conversations for React Router authentication patterns. [Dispatch subagent with search query: "React Router authentication error handling 401"] # ✅ GOOD: Minimal example (20 words) Partner: "How did we handle auth errors in React Router?" You: Searching... [Dispatch subagent → synthesis] ``` **Eliminate redundancy:** - Don't repeat what's in cross-referenced skills - Don't explain what's obvious from command - Don't include multiple examples of same pattern **Verification:** ```bash wc -w skills/path/SKILL.md # getting-started workflows: aim for <150 each # Other frequently-loaded: aim for <200 total ``` **Name by what you DO or core insight:** - ✅ `condition-based-waiting` > `async-test-helpers` - ✅ `using-skills` not `skill-usage` - ✅ `flatten-with-flags` > `data-structure-refactoring` - ✅ `root-cause-tracing` > `debugging-techniques` **Gerunds (-ing) work well for processes:** - `creating-skills`, `testing-skills`, `debugging-with-logs` - Active, describes the action you're taking ### 5. Cross-Referencing Other Skills **When writing documentation that references other skills:** Use skill name only, with explicit requirement markers: - ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development` - ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging` - ❌ Bad: `See skills/testing/test-driven-development` (unclear if required) - ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context) **Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them. ## Flowchart Usage ```dot digraph when_flowchart { "Need to show information?" [shape=diamond]; "Decision where I might go wrong?" [shape=diamond]; "Use markdown" [shape=box]; "Small inline flowchart" [shape=box]; "Need to show information?" -> "Decision where I might go wrong?" [label="yes"]; "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"]; "Decision where I might go wrong?" -> "Use markdown" [label="no"]; } ``` **Use flowcharts ONLY for:** - Non-obvious decision points - Process loops where you might stop too early - "When to use A vs B" decisions **Never use flowcharts for:** - Reference material → Tables, lists - Code examples → Markdown blocks - Linear instructions → Numbered lists - Labels without semantic meaning (step1, helper2) See `graphviz-conventions.dot` in this directory for graphviz style rules. **Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG: ```bash ./render-graphs.js ../some-skill # Each diagram separately ./render-graphs.js ../some-skill --combine # All diagrams in one SVG ``` ## Code Examples **One excellent example beats many mediocre ones** Choose most relevant language: - Testing techniques → TypeScript/JavaScript - System debugging → Shell/Python - Data processing → Python **Good example:** - Complete and runnable - Well-commented explaining WHY - From real scenario - Shows pattern clearly - Ready to adapt (not generic template) **Don't:** - Implement in 5+ languages - Create fill-in-the-blank templates - Write contrived examples You're good at porting - one great example is enough. ## File Organization ### Self-Contained Skill ``` defense-in-depth/ SKILL.md # Everything inline ``` When: All content fits, no heavy reference needed ### Skill with Reusable Tool ``` condition-based-waiting/ SKILL.md # Overview + patterns example.ts # Working helpers to adapt ``` When: Tool is reusable code, not just narrative ### Skill with Heavy Reference ``` pptx/ SKILL.md # Overview + workflows pptxgenjs.md # 600 lines API reference ooxml.md # 500 lines XML structure scripts/ # Executable tools ``` When: Reference material too large for inline ## The Iron Law (Same as TDD) ``` NO SKILL WITHOUT A FAILING TEST FIRST ``` This applies to NEW skills AND EDITS to existing skills. Write skill before testing? Delete it. Start over. Edit skill without testing? Same violation. **No exceptions:** - Not for "simple additions" - Not for "just adding a section" - Not for "documentation updates" - Don't keep untested changes as "reference" - Don't "adapt" while running tests - Delete means delete **REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation. ## Testing All Skill Types Different skill types need different test approaches: ### Discipline-Enforcing Skills (rules/requirements) **Examples:** TDD, verification-before-completion, designing-before-coding **Test with:** - Academic questions: Do they understand the rules? - Pressure scenarios: Do they comply under stress? - Multiple pressures combined: time + sunk cost + exhaustion - Identify rationalizations and add explicit counters **Success criteria:** Agent follows rule under maximum pressure ### Technique Skills (how-to guides) **Examples:** condition-based-waiting, root-cause-tracing, defensive-programming **Test with:** - Application scenarios: Can they apply the technique correctly? - Variation scenarios: Do they handle edge cases? - Missing information tests: Do instructions have gaps? **Success criteria:** Agent successfully applies technique to new scenario ### Pattern Skills (mental models) **Examples:** reducing-complexity, information-hiding concepts **Test with:** - Recognition scenarios: Do they recognize when pattern applies? - Application scenarios: Can they use the mental model? - Counter-examples: Do they know when NOT to apply? **Success criteria:** Agent correctly identifies when/how to apply pattern ### Reference Skills (documentation/APIs) **Examples:** API documentation, command references, library guides **Test with:** - Retrieval scenarios: Can they find the right information? - Application scenarios: Can they use what they found correctly? - Gap testing: Are common use cases covered? **Success criteria:** Agent finds and correctly applies reference information ## Common Rationalizations for Skipping Testing | Excuse | Reality | |--------|---------| | "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. | | "It's just a reference" | References can have gaps, unclear sections. Test retrieval. | | "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. | | "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. | | "Too tedious to test" | Testing is less tedious than debugging bad skill in production. | | "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. | | "Academic review is enough" | Reading ≠ using. Test application scenarios. | | "No time to test" | Deploying untested skill wastes more time fixing it later. | **All of these mean: Test before deploying. No exceptions.** ## Match the Form to the Failure Before writing guidance, classify the baseline failure. The form that bulletproofs one failure type measurably backfires on another. | Baseline failure | Right form | Wrong form | |---|---|---| | Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see Bulletproofing below) | Soft guidance ("prefer...", "consider...") | | Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) | Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list ("don't restate", "never narrate") | | Omits a required element from something they already produce | Structural: REQUIRED field or slot in the template they fill in | Prose reminders near the template | | Behavior should depend on a condition | Conditional keyed to an observable predicate ("if the brief exists, reference it") | Unconditional rule + exemption clauses | **Why prohibitions backfire on shaping problems:** under a competing incentive ("make the prompt self-contained"), agents negotiate with "don't X". In head-to-head wording tests on dispatch-prompt guidance, the prohibition arm produced clearly more of the unwanted content than the recipe arm (fully separated distributions), and trended worse than even the no-guidance control — micro-test your own case rather than assuming, but never reach for the prohibition by default. A recipe leaves nothing to negotiate: the output matches the stated shape or it doesn't. **Rules for whichever form you pick:** - **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same wording tests. Express a real exception as its own conditional on an observable predicate. - **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it. ## Bulletproofing Skills Against Rationalization Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure. **Scope:** this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead. **Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles. ### Close Every Loophole Explicitly Don't just state the rule - forbid specific workarounds: ```markdown Write code before test? Delete it. ``` ```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 ``` ### Address "Spirit vs Letter" Arguments Add foundational principle early: ```markdown **Violating the letter of the rules is violating the spirit of the rules.** ``` This cuts off entire class of "I'm following the spirit" rationalizations. ### Build Rationalization Table Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table: ```markdown | Excuse | Reality | |--------|---------| | "Too simple to test" | Simple code breaks. Test takes 30 seconds. | | "I'll test after" | Tests passing immediately prove nothing. | | "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" | ``` ### Create Red Flags List Make it easy for agents to self-check when rationalizing: ```markdown ## Red Flags - STOP and Start Over - Code before test - "I already manually tested it" - "Tests after achieve the same purpose" - "It's about spirit not ritual" - "This is different because..." **All of these mean: Delete code. Start over with TDD.** ``` ### Update SDO for Violation Symptoms Add to description: symptoms of when you're ABOUT to violate the rule: ```yaml description: use when implementing any feature or bugfix, before writing implementation code ``` ## RED-GREEN-REFACTOR for Skills Follow the TDD cycle: ### RED: Write Failing Test (Baseline) Run pressure scenario with subagent WITHOUT the skill. Document exact behavior: - What choices did they make? - What rationalizations did they use (verbatim)? - Which pressures triggered violations? This is "watch the test fail" - you must see what agents naturally do before writing the skill. ### GREEN: Write Minimal Skill Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases. Run same scenarios WITH skill. Agent should now comply. ### REFACTOR: Close Loopholes Agent found new rationalization? Add explicit counter. Re-test until bulletproof. ### Micro-Test Wording Before Full Scenarios Full pressure-scenario runs are the final gate, but they are slow and expensive per iteration. Verify the wording itself first with micro-tests: 1. **One fresh-context sample per call** — a raw API call, or a single-shot subagent if you don't have API access. System prompt = the realistic context the guidance will live in (the full skill or prompt template, not the guidance in isolation); user message = a task that tempts the failure. 2. **Always include a no-guidance control.** If the control doesn't exhibit the failure, there is nothing to fix — stop, don't author the guidance. 3. **5+ reps per variant.** Single samples lie. 4. **Manually read every flagged match.** Score programmatically if you like, but template echoes and quoted counter-examples masquerade as hits; automated counts alone overstate both failure and success. 5. **Variance is a metric.** When guidance lands, reps converge on the same shape. Five different interpretations across five reps means the wording isn't binding — tighten the form before adding words. Micro-tests verify wording; they do not replace pressure scenarios for discipline skills. **Testing methodology:** See [testing-skills-with-subagents.md](testing-skills-with-subagents.md) for the complete testing methodology: - How to write pressure scenarios - Pressure types (time, sunk cost, authority, exhaustion) - Plugging holes systematically - Meta-testing techniques ## Anti-Patterns ### ❌ Narrative Example "In session 2025-10-03, we found empty projectDir caused..." **Why bad:** Too specific, not reusable ### ❌ Multi-Language Dilution example-js.js, example-py.py, example-go.go **Why bad:** Mediocre quality, maintenance burden ### ❌ Code in Flowcharts ```dot step1 [label="import fs"]; step2 [label="read file"]; ``` **Why bad:** Can't copy-paste, hard to read ### ❌ Generic Labels helper1, helper2, step3, pattern4 **Why bad:** Labels should have semantic meaning ## STOP: Before Moving to Next Skill **After writing ANY skill, you MUST STOP and complete the deployment process.** **Do NOT:** - Create multiple skills in batch without testing each - Move to next skill before current one is verified - Skip testing because "batching is more efficient" **The deployment checklist below is MANDATORY for EACH skill.** Deploying untested skills = deploying untested code. It's a violation of quality standards. ## Skill Creation Checklist (TDD Adapted) **IMPORTANT: Create a todo for EACH checklist item below.** **RED Phase - Write 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 - Write Minimal Skill:** - [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars) - [ ] YAML frontmatter with required `name` and `description` fields (max 1024 chars; see [spec](https://agentskills.io/specification)) - [ ] Description starts with "Use when..." and includes specific triggers/symptoms - [ ] Description written in third person - [ ] Keywords throughout for search (errors, symptoms, tools) - [ ] Clear overview with core principle - [ ] Address specific baseline failures identified in RED - [ ] Guidance form matches the failure type (see Match the Form to the Failure) - [ ] For behavior-shaping guidance: wording micro-tested against a no-guidance control (5+ reps, every flagged match read manually) — N/A for pure reference skills - [ ] 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 **Deployment:** - [ ] Commit skill to git and push to your fork (if configured) - [ ] Consider contributing back via PR (if broadly useful) ## Discovery Workflow How future agents find your skill: 1. **Encounters problem** ("tests are flaky") 2. **Searches skills** (greps descriptions, browses categories) 3. **Finds SKILL** (description matches) 4. **Scans overview** (is this relevant?) 5. **Reads patterns** (quick reference table) 6. **Loads example** (only when implementing) **Optimize for this flow** - put searchable terms early and often.