sdd-engineering

Use proactively at the start of any non-trivial feature or change, before implementation — or when asked to plan, scope, decompose, or design an approach. Takes EXISTING requirements as input (from the request or a spec document), verifies them against the codebase, and recommends improvements. If requirements are unclear or the execution mode (multi-agent vs single-agent) is not stated, it returns clarifying questions INSTEAD of a plan — relay them to the user and re-invoke with the answers. Once confirmed, writes a structured Implementation Plan to docs/plans/<feature>.md: requirement traceability IDs, tasks with owned paths, per-task skills, a dependency DAG (multi-agent) or sequential steps (single-agent), and measurable acceptance criteria. Read-only on product code; its ONLY write is the plan file. Does NOT write specifications. Does NOT implement. Callers SHOULD gather the execution mode (multi-agent vs single-agent) and requirement confirmations via AskUserQuestion BEFORE invoking — a stated mode avoids a second invocation through the clarification gate.

Use proactively to execute ONE task of an Implementation Plan (docs/plans/<feature>.md) — backend or UI — and as several parallel instances, one per disjoint task. Works in the same branch/working tree it was launched in; owns only its task's paths. Returns a report: files changed, skills applied, and green typecheck + existing-tests output (or the documented typecheck-only fallback when the project has no test command).

Use to verify that an implemented change satisfies every requirement and acceptance criterion of an Implementation Plan in `docs/plans/<feature>.md`. Maps every R-ID and measurable acceptance criterion to concrete evidence (file:line, test name, migration) and returns a coverage matrix with an ALL COVERED / GAPS FOUND verdict; cross-checks spec ACs when the plan names a SPEC-NN. Read-only; complements quality review and structural architecture review — this one is COVERAGE. Invoked by the `sdd-engineering:run-plan` skill after the last implementer wave, or directly via 'verify the plan', 'did we cover all requirements', 'requirement coverage', 'check plan against code'.

Use to write a Spec-Driven Development (SDD) feature specification BEFORE any planning or implementation — problem, goals/non-goals, user stories, EARS acceptance criteria, edge cases, input provenance. Grounds facts in the repository (docs, code search, and optional convention tools when the host project exposes them), critiques provided designs/code/docs for gaps, and interviews the user through STOP-AND-RETURN question rounds (it cannot ask live — relay its questions to the user and re-invoke with the answers; repeat until it writes the spec). Writes ONLY SPEC-NN-*.md files (plus the folder README index line) under a specs/ folder. Trigger phrases: 'write a spec', 'create a specification', 'SDD spec', 'напиши специфікацію', 'створи спеку'. Does NOT plan tasks (sdd-engineering:implementation-planner) and does NOT document shipped features.

Use during any coding session whenever you uncover a non-obvious finding worth preserving — a failure mode that surprised you, a tool/library quirk, an architectural decision made for a non-obvious reason, a recurring error and its fix, or an open question you could not resolve. Appends a single dated entry to the nearest INSIGHTS.md (the closest ancestor of the affected files, or the repo root) under one of seven fixed sections. Append-only. Skips anything obvious from reading the code.

Use to EXECUTE an Implementation Plan (`docs/plans/<feature>.md`) end-to-end in the main session: feature branch → implementer waves per the task DAG (or sequential steps in single-agent mode) → plan-verifier coverage gate (run inside a subagent) → capped gap-fix loop → architecture review gate with a capped fix loop (≤3, until PASS) → spec status flip → confirm and `gh pr create`. Trigger phrases: '/run-plan', '/impl', 'імплементуй план', 'implement the plan', 'run the plan', 'execute the plan', 'виконай план', 'запусти план'. NOT for writing plans (sdd-engineering:implementation-planner) or specs (sdd-engineering:spec-creator) — those are invoked manually, upstream of this skill.

Use to run a MANUAL retrospective of a multi-agent run (the SDD pipeline or any session with subagents): computes token metrics (input / output / cache-read / cache-creation, cache-hit rate), tool-call counts, durations, and parallelism — INCLUDING nested subagents, whose usage the parent does not count (deep mode reads their journals from disk) — then produces insights + concrete recommendations and appends a trend row to docs/retros/ledger.md. Trigger phrases: 'workflow retro', 'ретро прогону', 'retro the run', '/workflow-retro'. Manual only — never fired by a hook.