# Mastery & Real-World Application

> Applying Superpowers beyond the first 30 minutes: handling legacy migrations, complex refactors, and maintaining a high-quality codebase at scale.

- Repository: obra/superpowers
- GitHub: https://github.com/obra/superpowers
- Human wiki: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85
- Complete Markdown: https://grok-wiki.com/public/wiki/obra-superpowers-8ae12eb67e85/llms-full.txt

## Source Files

- `CLAUDE.md`
- `GEMINI.md`
- `RELEASE-NOTES.md`
- `AGENTS.md`
- `CODE_OF_CONDUCT.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [AGENTS.md](AGENTS.md)
- [README.md](README.md)
- [skills/subagent-driven-development/SKILL.md](skills/subagent-driven-development/SKILL.md)
- [skills/systematic-debugging/SKILL.md](skills/systematic-debugging/SKILL.md)
- [skills/writing-plans/SKILL.md](skills/writing-plans/SKILL.md)
- [skills/test-driven-development/SKILL.md](skills/test-driven-development/SKILL.md)
</details>

# Mastery & Real-World Application

Superpowers is designed to evolve from a simple coding assistant into an autonomous engineering partner capable of handling complex, long-running tasks. Mastery of the system involves moving beyond individual file edits and adopting the systematic workflows that enable large-scale refactors, legacy migrations, and high-quality maintenance.

This page outlines the advanced strategies required to apply Superpowers effectively in real-world, high-stakes environments, focusing on protecting your reputation and maintaining codebase integrity.

## Legacy Migrations & Archaeological Debugging

Migrating legacy systems requires a deep understanding of existing (and often undocumented) behavior before a single line of code is changed. Superpowers enforces a "Systematic over ad-hoc" philosophy to prevent the introduction of regressions.

### The Iron Law of Debugging
When dealing with legacy code, the "Iron Law" must be followed: **No fixes without root cause investigation first.** This prevents the "guess-and-check" cycle that often plagues complex migrations.

Sources: [skills/systematic-debugging/SKILL.md:16-20](), [README.md:144-147]()

### Archaeological Instrumentation
For multi-component systems where the failure point is unknown, use Phase 1 of the systematic debugging process to add diagnostic instrumentation. Instead of guessing where a value changes, log data as it enters and exits every component boundary. This "archaeological" approach reveals exactly where the legacy logic deviates from requirements.

Sources: [skills/systematic-debugging/SKILL.md:50-87]()

## Complex Refactors with Subagent-Driven Development (SDD)

Large-scale refactors are too big for a single agent session to track reliably. Superpowers solves this through **Subagent-Driven Development (SDD)**, which decomposes a high-level plan into independent, reviewed tasks.

### Two-Stage Review Process
To maintain quality at scale, SDD uses a two-stage review process for every task:
1.  **Spec Compliance Review**: A reviewer agent verifies the implementation against the original plan independently, without trusting the implementer's report.
2.  **Code Quality Review**: A second review focused on logic, performance, and best practices.

This separation of concerns ensures that the refactor doesn't drift from its architectural goals while maintaining high technical standards.

Sources: [skills/subagent-driven-development/SKILL.md:4-6](), [README.md:110-120]()

### Orchestration and Parallelism
For massive refactors, use `dispatching-parallel-agents` to handle independent tasks concurrently. This is combined with `using-git-worktrees` to ensure that each subagent works in a clean, isolated environment, preventing cross-task interference.

Sources: [README.md:135-138]()

## Maintaining High-Quality at Scale

As a project grows, the cost of "slop" increases exponentially. Superpowers is designed to protect your human partner's reputation by enforcing strict contribution guidelines.

### Protecting Your Human Partner
A core tenet of Superpowers mastery is recognizing that submitting a low-quality PR wastes time and burns reputation. Every change must be a "real problem" that has been verified, rather than a theoretical fix or a "compliance" change.

Sources: [AGENTS.md:9-17]()

### The Red-Green-Refactor Mandate
High-quality codebases are maintained through mandatory TDD workflows. Superpowers enforces a strict cycle:
1.  **RED**: Write a failing test first.
2.  **GREEN**: Write the minimal code needed to pass.
3.  **REFACTOR**: Clean up the code.

Critically, the system is designed to **delete code written before tests** to prevent the accumulation of untested logic.

Sources: [README.md:121-125](), [README.md:144-147]()

## Advanced Workflow Summary

| Workflow Stage | Tooling / Skill | Purpose |
| :--- | :--- | :--- |
| **Discovery** | `brainstorming` | Socratic refinement of complex requirements. |
| **Decomposition** | `writing-plans` | Breaking long tasks into 2-5 minute reviewed chunks. |
| **Execution** | `subagent-driven-development` | Autonomous, parallel task completion with multi-stage review. |
| **Validation** | `verification-before-completion` | Ensuring the fix or feature survives adversarial testing. |

Mastering Superpowers means trusting the process over intuition. By following these systematic phases, an engineer can manage hours of autonomous work without deviating from the initial architectural plan.

Sources: [README.md:103-108](), [skills/systematic-debugging/SKILL.md:46-50]()