spec-driven-engineering

Use when planning a non-trivial change's file/module structure, or reviewing whether a change's boundaries are sound — the structural lens on modules and boundaries, distinct from SOLID-level class design.

Use when encountering any bug, test failure, or unexpected behavior, before proposing a fix — to find and fix the true root cause instead of guessing at the symptom the report happened to name.

Use when starting any engineering task and it's unclear which skill in this repo to reach for first — routes to the right spine or supporting skill based on where the work actually is.

Use when a spec's requirements use terms that are vague, overloaded, or inconsistently used across the conversation — builds and stress-tests the project's domain vocabulary so the spec is written in precise, shared language.

Use when writing or reviewing any non-trivial code — naming, function design, error handling, testing, security, logging, and SOLID/DRY checks that apply regardless of language. Referenced by implement and review-code rather than invoked on its own.

Use when implementation is complete and review-code has returned READY — decides how the work gets integrated (merge, PR, rebase) and confirms nothing is left uncommitted or unverified before doing so.

Use when a plan, spec, or design decision feels shaky and needs to be pressure-tested before committing to it — a relentless interview that keeps pushing until every branch of the decision is resolved, not just the happy path.

Use when a conversation or session needs to end but the work isn't finished — compacts the current state into a handoff document another agent or session can pick up from without re-deriving everything.

Use when writing the actual code for a plan step, feature, or bugfix — turns a plan (or an ad-hoc change) into committed, verified code.

Use when a spec or set of requirements exists and needs to become an ordered, executable implementation plan before any code is written — turns a spec's goals and success criteria into sequenced steps with named files and per-step verification.

Use when a git merge or rebase produces conflicts — resolves each hunk by tracing what each side actually intended, not by mechanically picking one side or pasting both.

Use when about to commit, push, or open a PR for any non-trivial change — the last gate that checks the change against its spec and the engineering standards before it ships.

Use when starting any non-trivial feature, subsystem, or design change before writing code, or when requirements exist only in conversation with nothing written down — turns an idea into a spec with measurable success criteria that downstream implementation and review can be checked against.

Use when implement or debug-systematically reaches a code seam that needs a test written before the implementation — the test-first sub-routine those skills drive, not a standalone entry point.

Use when grooming a backlog of issues, bugs, or requests and deciding what's next — moves items through a tracker-agnostic state machine instead of an ad-hoc priority argument.

Use when writing or editing a SKILL.md, CLAUDE.md, or any other document an agent will read and act on — governs how this repo's own skills, and any project's agent-facing docs, are written so they get followed correctly.