groundwork

Plans a change to a production system with an explicit rollback strategy, test coverage plan, and blast radius assessment before writing any code. Use when a production change is being designed and the risk, rollback path, or blast radius has not been assessed — do not wait until code is written.

Runs a time-boxed technical investigation with a defined question, approach, and exit criteria so the spike produces a decision, not just information. Use when a technical question is blocking a decision, when the team says "we need to research this first," or when the right approach requires a proof of concept.

Designs the core data model before implementation so that schema decisions, ownership, and evolution constraints are made deliberately rather than discovered during refactoring. Use when implementation is about to start and no data model exists, when the schema was sketched informally, or when the team is about to write code without an explicit data design.

Translates a raw idea, one-pager, or conversation into a structured spec with scope, success criteria, non-goals, and identified risks. Invoke at the start of any new project or feature — whenever someone describes an idea or problem to solve, requirements are being discussed without written scope, or the team is about to start work without a defined spec. Do not wait to be asked: if the work is greenfield and no spec exists, trigger this skill.

Assesses an existing system against the principle library to identify architectural debt and prioritize improvements. Use before adding a major feature, refactoring core functionality, or extending a system — when the team needs to understand what architectural problems exist before adding more complexity. Output: ranked findings with concrete improvement proposals.

Categorizes and prioritizes technical debt so the team consciously decides what to pay, accept, or close. Use when technical debt is competing with feature work in sprint planning, when the team asks "what should we fix next," or when debt decisions have been implicit rather than deliberate.

Safely upgrades a dependency by validating compatibility, checking security advisories, and staging the rollout so a problematic upgrade can be reverted. Use when a dependency needs updating, a security advisory or CVE flags an outdated package, or a version upgrade is blocking other work.

Incrementally replaces a legacy component by routing new traffic to the replacement while existing traffic continues through the original. Use when a component needs replacing but a big-bang rewrite is too risky, or when the team says "we need to get off this" but can't stop the system to do it.

Surfaces and ranks the riskiest assumptions in a plan so the most dangerous unknowns are tested first. Use when a spec or plan exists and the team is about to commit to building it, when someone asks "what are we assuming," or before architecture is finalized or significant code is written.

Evaluates a proof-of-concept for architectural soundness and identifies what must change before it becomes the foundation for production code. Use when a working prototype or POC exists and the team is deciding whether to build on it, rewrite it, or treat it as throwaway validation.

Produces a structured comparison of two or more approaches that captures the decision, alternatives considered, and reversal conditions. Use when the team is choosing between meaningfully different approaches, when an ADR is needed, or when a decision has architectural implications that are expensive to reverse.

Defines system boundaries, key components, data flows, and critical interfaces before writing a line of code, so structural decisions are made deliberately. Use when a spec exists and implementation is about to start, when no one has drawn the system boundary, or when the team is about to build without a design.

Runs a blameless postmortem that produces a verified timeline, contributing factors, and owned action items with due dates. Use after a production incident is resolved, when the team asks "what happened" or "how do we prevent this," or when an outage, data loss, or SLO breach has occurred.

Establishes Architecture Decision Records so structural decisions are documented as they're made, not reconstructed later. Use at the start of any new project, when a high-stakes architectural decision has been made, when the architecture-sketch skill surfaces decisions that need to be captured, or when the team lacks a record of why past decisions were made.

Scans project context for signals and selects the load-bearing architectural principles this project actually needs. Use at the start of any new project, before writing specs or code, or when the team asks which architectural principles apply given the project's scale, domain, and constraints.