scuba-stack

Guidance for writing the test before the code. Use when building new behavior or fixing a bug — write the failing test first, watch it fail for the right reason, then make it pass. Test-first is a mandate with a few stated exceptions, not loose advice; reach for it before you write the implementation, not after.

Method for finding the cause of a bug, failing test, regression, or unexplained symptom whose cause is unknown. Use when something is broken and you don't yet know why — reproduce it, narrow by halving, instrument and read live state, and repair the root rather than silencing the symptom. Not for plan-writing or building features to a known design — but a senior-implementer whose own fresh build breaks reaches for this; it is the discipline for the unknown.

Procedure for gating work with fresh, independent, lensed hunters until a CLEAN verdict, and for front-running an external automated reviewer by tuning your own hunters to the bug categories it actually finds. Use at every quality gate: spec, plan, and code or PR review. Make sure to use this whenever reviewing or QAing substantive work before it advances, scaling the depth to the stakes.

Operating manual for the top-level orchestrator the user talks to: the single agent that receives the user's asks, dispatches each piece of work at the right depth (a direct specialist for a small task, or running the `team-manager` lifecycle itself for a big chunk), monitors everything in flight, surfaces decisions one at a time, and stays free. Use this whenever acting as the user's chief of staff or orchestrator: receiving asks, choosing dispatch depth, delegating to specialists or wearing the manager hat for an epic, health-checking running work, surfacing decisions, and presenting epic-bookend briefs. Make sure to use this skill whenever coordinating or delegating work, or when the user asks for status or a decision, even if "chief of staff" isn't said.

The hat the chief of staff wears to own an epic end to end (anything bigger than one PR); the operating manual for running an epic yourself, not a separate agent. Use this whenever owning a chunk end to end: triaging it, grooming an epic into slices and dispatching workers (one writer per branch), running the spec -> plan -> build lifecycle with adversarial review until clean, owning the integration branch and the never-draft merge model, health-monitoring those workers, and keeping progress visible and durable. It is also the canonical home of the integration-branch / serial-dependent-chain / never-draft model. Make sure to use this skill whenever running a chunk, triaging a backlog, managing workers, or moving work through its lifecycle, even if the role isn't named.

The ritual for taking completed, verified work up for review. Use the moment a build is done and ready to go up: when finishing a chunk, opening or putting up a PR, or shipping a change. Open the PR first to start the external reviewer, then in parallel run a swarm of fresh independent Opus hunters over the diff, reconcile their findings with the external reviewer's into one classified list, dispatch the `steward` to own closeout (rebase, paginate/triage threads, resolve, re-verify, merge to the integration branch), routing REAL bugs to the `bug-fixer` for root-cause repair, and loop until CLEAN. Make sure to use this whenever work is finished and about to go up for review, so you find your own bugs instead of waiting on the PR queue.

Produces the per-epic brief that the chief of staff presents to the user at an epic's two bookends — a v1 architecture brief at design-done and a v2 executive brief at merge, both states in one updated file. Use this whenever an epic reaches a bookend and a brief is needed, or whenever the user or the chief of staff asks for an architecture brief, an executive brief, an epic report, or a product-and-architecture summary. The brief is a self-contained HTML document covering the work from two lenses, product and architecture, sourced from the control plane. Make sure to use this skill whenever rendering either bookend brief, and start from the bundled template rather than designing from scratch.

The single state-of-the-world document the chief of staff keeps current and reads first on every resume — a Mermaid stage-tagged tree of every in-flight thread, linking to the artifacts and per-thread status each one needs to recover. Use when initializing or updating orchestration state, on every monitor tick, and to recover after a lost session. The roadmap is the resume anchor; the per-team files are the detail. Make sure to keep it current as work moves, delegating the typing to a scribe rather than blocking on it.

Procedure for keeping delegated background work alive. A re-arming poll that health-checks every running agent by git SHA, file mtime, and durable artifacts rather than waiting for completion messages. Use this whenever one or more agents or processes are running in the background and you need to detect stalls and deaths before they cost hours. Make sure to use this whenever you have dispatched background work.

A play for genuinely uncertain design problems. Spawn several independent attempts at the same task in parallel, evaluate them against one bar, pick a base, and fold the best pieces of the others into it. Use only when the right shape is unclear and the cost of several parallel Opus attempts is justified, never for routine work. Run by a manager or the orchestrator, since it spawns workers.

Guidance for sizing work before you build it. Use when a change is bigger than one reviewable PR, or when planning an epic. Cut it into small, independently-shippable slices that each prove themselves and ship one at a time, rather than batching an epic into one long-lived PR that never converges.

The chief of staff's ritual for turning the user's raw, underspecified ask into a dispatchable mandate before any work is dispatched. Use at the very front, whenever a new ask arrives or an ambiguity escalates back up, and before delegating anything substantive. Delegate the drafting to an intake-drafter so the chief of staff stays free; own the conversation, grill the user against the draft's assumptions and forks, and loop until the mandate is solid. Make sure to use this before dispatching substantive work, so the spec is built on extracted intent rather than a guess.

Guidance for deciding where code lives and what a module, package, or service exposes. Use when placing new code, designing an interface between parts, splitting or merging modules, or answering ownership and layering questions. A boundary is a promise; keep them few, explicit, and stable.

Guidance for choosing where to spend effort so it compounds. Use when a class of work keeps recurring or a change could make many future changes easier. Find the leverage point, the small structural change that removes a category of future work, rather than only solving the case in front of you.

Guidance to apply before committing to a design. Use when choosing an approach for any non-trivial piece of work. Generate two or three genuinely different options and name their tradeoffs before picking, rather than building the first workable idea.

Guidance for designing from the outside in. Use when designing a feature, an API, a CLI, or any interface. Start from the experience of whoever will use the thing, the user, the caller, the operator, and work back to the implementation, not the other way around.

Guidance to apply before solving a problem: get the foundation right first. Use at the start of any non-trivial task, before designing or coding. Name what is actually being asked, the real constraints, the invariants, and the failure modes, so you don't build correctly on a wrong base.

Guidance for changing an existing system, whether fixing a bug or adding a feature. Use whenever integrating new information or a new requirement into existing code: bug fixes, feature implementation, and the spec or plan that precedes them. Repair the root cause and fit the change into the design as a whole, refactoring where needed, instead of accreting another condition or special case.

Guidance for doing the least work that fully solves the problem. Use on any task. Reuse before building, don't solve problems you don't have, don't gold-plate, and automate the repetitive, while holding "fully solves" as the hard constraint.

Guidance for designing operations that are safe to run more than once with the same effect. Use when designing writes, webhooks, job handlers, migrations, payment or messaging flows, or anything that can be retried or delivered more than once. The goal is that a duplicate call changes nothing beyond the first.

Guidance for replacing an API, function, or interface without leaving the old one behind. Use when introducing a new version of something that already has callers, deprecating a path, or changing a shared signature. The aim is to finish the migration in the same effort, not to leave two ways to do one thing.

Guidance for writing code and docs that are cheap to read. Use when writing or reviewing any code, naming things, or structuring a module. Code is read far more than written, so reduce what a reader must hold in their head to understand it.

Guidance for keeping work pointed at the actual goal. Use during any multi-step task. Work toward the outcome rather than the task list: keep the goal in view, cut steps that don't serve it, and don't mistake activity for progress.

Guidance for when a design keeps fighting you. Use when patches are accumulating, every change touches many places, or the current shape feels wrong. Re-derive the design from the actual requirements and constraints, ignoring the current structure, instead of patching the local optimum.

Guidance for what to do before you serialize or share state across a boundary such as a process, service, cache, or the wire. Use when designing a payload, a cached value, a token, or any state two parts will both depend on. Shared serialized state is the most expensive coupling, so separate and minimize it first.

Guidance to apply before adding a feature, option, abstraction, configuration flag, or dependency. Use whenever you're about to add something to a codebase or design. The best change is often a removal; check whether removing or unifying gets you there before you grow the surface.

Guidance for designing types, APIs, and data models in a typed language so the compiler carries the invariants. Use when defining types, designing an interface or data model, or deciding how to represent state, especially in TypeScript. The aim is to make illegal states unrepresentable so whole classes of bug never compile.