obra.

Commenting Intent

Comment WHY code exists and non-obvious decisions, not WHAT code does (mechanics)

Creating Skills

TDD for process documentation - test with subagents before writing, iterate until bulletproof

Designing Before Coding

Design in pseudocode first, iterate approaches, then translate to code

Domain-Focused Naming

Name code by what it does in the domain, not how it's implemented or its history

Encapsulating Complexity

Hide implementation details behind interfaces - work at domain level (what), not implementation level (how)

Exploring Alternatives

Try 2-3 different approaches before implementing - don't settle for first design you think of

Installing Skills System

Fork, clone to ~/.clank, run installer, edit CLAUDE.md

Keeping Routines Focused

Each routine does one thing and does it well - extract when routines have multiple responsibilities

Localizing Variables

Declare variables in smallest possible scope, initialize close to first use, minimize span and live time

Maintaining Consistent Abstractions

Class interfaces present one cohesive abstraction - don't mix domain logic with serialization, persistence, or unrelated concerns

Naming Variables

Choose names that fully and accurately describe what the variable represents

Reducing Complexity

Managing complexity is software's primary technical imperative - all other goals are secondary

Refactoring Safely

Refactor with tests first, one change at a time, never mix refactoring with bug fixes or new features

Simplifying Control Flow

Flatten nested conditionals with early returns or table-driven methods - keep nesting depth under 3 levels

Single Purpose Variables

Use each variable for exactly one purpose - no hybrid coupling or hidden meanings

Validating Inputs

Check all external inputs for validity - garbage in, nothing out, never garbage out

Writing Evergreen Comments

Write comments explaining WHAT and WHY, never temporal context or history

driving-claude-code-sessions

Use when acting as a project manager that delegates tasks to other coding-agent sessions (Claude Code, Codex, or Pi) - launch workers, assign them work, monitor progress, review their tool calls, and collect results

chronicle

|

e2e-scenario-testing

Use when verifying a running application end-to-end through its real interface — a web UI, a CLI, or a TUI — by writing and executing agent-run "scenario cards" against a freshly built instance with falsifiable assertions. Trigger on "test it end to end", "prove the UI actually works", "write/run a scenario", or after a change touches a user-facing surface that unit tests can't fully cover. Not for unit tests, pure code review, or API-only checks.

maintaining-documentation

Use when documentation needs creating, checking, or maintaining — docs may have drifted from code, pre-release doc verification, updating docs after finishing code work, adding or enforcing project terminology, deciding where a new doc should live, or a routine re-audit of previously verified docs.

roborev-design-review

Request a design review for a commit and present the results

roborev-design-review-branch

Request a design review for all commits on the current branch and present the results

roborev-fix

Use when the user asks to fix open failing reviews, invokes /roborev-fix, or provides job IDs; do not use when the user only pastes review findings with no request to discover or close reviews

roborev-refine

Iterative review-fix loop for the current branch — reviews via daemon, fixes inline, re-reviews until passing or max iterations reached

roborev-respond

Add a comment to a roborev code review and close it

roborev-review

Request a code review for a commit and present the results

roborev-review-branch

Request a code review for all commits on the current branch and present the results

syncing-obsidian

Use when reading or writing files in an Obsidian vault that is synced with obsync. Ensures changes are pulled before reading and pushed after writing. Also covers sync status, file history, version restore, and diagnosing sync issues.

maintaining-macos-defaults

Use on demand to reconcile a Mac's GUI-changed settings into version control — when the user says "reconcile my mac defaults", "capture my macOS settings", or after they've changed System Settings and want the keepers tracked. Drives homedir-manager's `defaults` verb (capture/drift/apply) against a versioned desired-state file.

managing-homedir

Use when adding, changing, deploying, onboarding, or auditing homedir-manager content repos — the marker-based symlink deployment system that manages dotfiles and config across your machines. Covers the update workflow, the manifest, OS-splitting, secrets, new-machine onboarding, and the audit process.

prove-claim

Use when asked to prove, disprove, investigate, or find evidence for a claim about people, concepts, ideas, or their relationships. Also use when asked to explore connections, find who influenced what, trace how ideas developed, or answer questions that require reasoning over multiple linked notes.

blender-reconstruct

Build and review evidence tagged Blender architectural candidates while preserving unrelated scene content.

depth-inspect

Inspect native RGB, depth, confidence, calibration, and poses to make finite, source traceable reference points and surface measurements.

scan-ingest

Preserve and inventory scan archives while retaining capture variants, hashes, calibration, and frame provenance.

scan-register

Fit and independently validate rigid scan alignment from named, source traceable correspondences.

scan-to-model

Coordinate evidence based reconstruction from scans, photos, plans, and measurements into a reviewable Blender architectural model.

source-observe

Use when cataloging or annotating visible construction in photographs or scan RGB, especially before registration or while the base model may be replaced.

street-view-reference

Collect and verify Google Street View exterior references for a building reconstruction, preserving panorama identity, imagery dates, attribution and viewpoint separately from calibrated scan evidence.

linear

Manage Linear issues. Use when asked about tasks, tickets, bugs, or Linear.

brainstorming

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.

dispatching-parallel-agents

Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies

executing-plans

Use when you have a written implementation plan to execute in a separate session with review checkpoints

finishing-a-development-branch

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work

receiving-code-review

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

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

subagent-driven-development

Use when executing implementation plans with independent tasks in the current session

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

using-git-worktrees

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-superpowers

Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions

verification-before-completion

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

writing-plans

Use when you have a spec or requirements for a multi-step task, before touching code

writing-skills

Use when creating new skills, editing existing skills, or verifying skills work before deployment

browsing

Use when you need direct browser control - teaches Chrome DevTools Protocol for controlling existing browser sessions, multi-tab management, form automation, and content extraction via use_browser MCP tool

developing-claude-code-plugins

Use when working on Claude Code plugins (creating, modifying, testing, releasing, or maintaining) - provides streamlined workflows, patterns, and examples for the complete plugin lifecycle

example-workflow

Use when demonstrating plugin workflow features - shows how skills can guide multi-step processes

working-with-claude-code

Use when working with Claude Code CLI, plugins, hooks, MCP servers, skills, configuration, or any Claude Code feature - provides comprehensive official documentation for all aspects of Claude Code

finding-duplicate-functions

Use when auditing a codebase for semantic duplication - functions that do the same thing but have different names or implementations. Especially useful for LLM-generated codebases where new functions are often created rather than reusing existing ones.

mcp-cli

Use MCP servers on-demand via the mcp CLI tool - discover tools, resources, and prompts without polluting context with pre-loaded MCP integrations

using-tmux-for-interactive-commands

Use when you need to run interactive CLI tools (vim, git rebase -i, Python REPL, etc.) that require real-time input/output - provides tmux-based approach for controlling interactive sessions through detached sessions and send-keys

windows-vm

Create, manage, or connect to a headless Windows 11 VM running in Docker with SSH access. Use when the user wants to spin up, stop, restart, or SSH into a Windows VM.

Brainstorming Ideas Into Designs

Interactive idea refinement using Socratic method to develop fully-formed designs

Code Review Reception

Receive and act on code review feedback with technical rigor, not performative agreement or blind implementation

Collision-Zone Thinking

Force unrelated concepts together to discover emergent properties - "What if we treated X like Y?"

Condition-Based Waiting

Replace arbitrary timeouts with condition polling for reliable async tests

Defense-in-Depth Validation

Validate at every layer data passes through to make bugs impossible

Gardening Skills Wiki

Maintain skills wiki health - check links, naming, cross-references, and coverage

Getting Started with Skills

Skills wiki intro - mandatory workflows, search tool, brainstorming triggers

Inversion Exercise

Flip core assumptions to reveal hidden constraints and alternative approaches - "what if the opposite were true?"

Meta-Pattern Recognition

Spot patterns appearing in 3+ domains to find universal principles

Preserving Productive Tensions

Recognize when disagreements reveal valuable context, preserve multiple valid approaches instead of forcing premature resolution

Pulling Updates from Skills Repository

Sync local skills repository with upstream changes from obra/superpowers-skills

Remembering Conversations

Search previous Claude Code conversations for facts, patterns, decisions, and context using semantic or text search

Root Cause Tracing

Systematically trace bugs backward through call stack to find original trigger

Scale Game

Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths hidden at normal scales

Sharing Skills

Contribute skills back to upstream via branch and PR

Simplification Cascades

Find one insight that eliminates multiple components - "if this is true, we don't need X, Y, or Z"

Test-Driven Development (TDD)

Write the test first, watch it fail, write minimal code to pass

Testing Anti-Patterns

Never test mock behavior. Never add test-only methods to production classes. Understand dependencies before mocking.

Testing Skills With Subagents

RED-GREEN-REFACTOR for process documentation - baseline without skill, write addressing failures, iterate closing loopholes

Tracing Knowledge Lineages

Understand how ideas evolved over time to find old solutions for new problems and avoid repeating past failures

When Stuck - Problem-Solving Dispatch

Dispatch to the right problem-solving technique based on how you're stuck

writing-clearly-and-concisely

Apply Strunk's timeless writing rules to ANY prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Makes your writing clearer, stronger, and more professional.