design-rationale

name	design-rationale
description	Produce a Design Rationale section for a design/spec/architecture artifact — justifying OOP/SOLID application, which design pattern(s) were considered and chosen (or why none applies), and which collection/data-structure was picked for each non-trivial data need, with the complexity/performance tradeoff that justifies it. Asks the developer clarifying questions when a structural choice (concurrency, cardinality, mutability, ordering, hot-path-vs-cold-path) is a genuine judgment call, rather than guessing. Language-agnostic — works for Java, Python, JavaScript/TypeScript, or any other stack. Use whenever a pipeline is about to lock in a design/spec for non-trivial work (new module, service, class hierarchy, data pipeline), or when a developer explicitly asks for a design/architecture review, "why this data structure", or "apply SOLID/design patterns here". Do NOT use for one-line fixes or purely mechanical changes with no structural decisions to make.
allowed-tools	Read
effort	medium

design-rationale

Implements STANDARDS rule #6: non-trivial design/spec work must show its engineering reasoning — OOP/SOLID application, design-pattern choice, and collection/data-structure choice — and must ask the developer before locking in a structural choice that is genuinely their call to make.

This skill produces a section, not a whole document. The calling pipeline/workflow owns its own design doc (design.md, an ADR, a PR description, whatever shape it uses) and splices this skill's output into it — exactly how file-doc-task never owns the feature's PR, this skill never owns the design doc.

When to use

• A pipeline is about to lock in a design/spec for non-trivial work: a new module, service, class hierarchy, API surface, or data pipeline that introduces real structural decisions (which collection, whether to abstract, whether a pattern fits).
• A developer explicitly asks for a design/architecture review, "why this data structure", "apply SOLID here", or similar.

When NOT to use

• One-line fixes, config tweaks, or purely mechanical changes (rename, formatting, dependency bump) with no structural decision being made. Skip silently — there is nothing to rationalize.

What "non-trivial" means here

A change is non-trivial for this skill's purposes if it introduces at least one of: a new class/module with more than one responsibility to divide, a new collection/data structure whose choice affects correctness or performance, more than one plausible way to structure the interaction between components, or a repeated/variant behavior that could be modeled as a pattern (strategy, factory, observer, etc.). If none of these apply, record N/A — <reason> in the Design Rationale section and stop; do not manufacture structure that isn't needed.

Steps

1. Load the checklist. Read references/design-standards.md in this skill's directory — the OOP/SOLID red-flag list, the design-pattern cheat-sheet, the collections/data-structure decision table, and the canonical clarifying-question bank.

2. Identify the language(s)/stack(s) in play for the artifact being designed (from the pipeline's own domain detection, an existing repo's tech stack, or the developer's stated intent). Use the matching column of the decision table; if the stack isn't one of the table's columns, apply the universal Big-O/access-pattern reasoning directly — the table is a quick-reference, not an exhaustive list.

3. Walk the design against the checklist:

   • OOP/SOLID: for each class/module the design introduces, check it against the five red flags in the reference doc. Note violations found and the fix, or state why the design is clean.
   • Design pattern(s): match the problem shape(s) in the design against the cheat-sheet. If a pattern fits and adds real value (not just ceremony), name it and say why. If none fits, or applying one would be over-engineering for the scope of the change, say so explicitly — that is a complete, valid answer.
   • Collections/data structures: for each non-trivial data need in the design, identify the access pattern (uniqueness, ordering, key lookup, priority, FIFO/LIFO, graph/tree relationship, etc.) and pick the structure from the decision table (or reason from Big-O directly). Record the reasoning, not just the chosen type.

4. Ask clarifying questions before finalizing, when a choice in step 3 turned on an assumption the developer is better positioned to answer than the model is — draw from the reference doc's clarifying-question bank (mutability/concurrency, expected cardinality, ordering/duplicate tolerance, hot-path vs. cold-path). Ask only the questions that are actually load-bearing for a decision already made in step 3 — don't interview for its own sake.

   • If the calling pipeline supports a halt-and-resume convention (e.g. sdd-pipeline's NEEDS_USER_INPUT: prefix), emit the question that way so the orchestrator can surface it and re-dispatch with the answer. Otherwise, ask directly and wait for the reply before finalizing.
   • Record the question and the developer's answer in the output — this is what makes the rationale auditable later, not just the final choice.

5. Return the filled Design Rationale section (markdown), following this shape:

   ## Design Rationale & Standards Compliance
   
   
   ", or "N/A — ">
   
   
   | Pattern | Applies? | Reasoning |
   |---|---|---|
   
   
   | Data need | Access pattern | Structure chosen | Why (complexity/perf) |
   |---|---|---|---|
   
   
   | Question | Answer | How it changed the design |
   |---|---|---|
   

References

• references/design-standards.md — the OOP/SOLID red flags, design-pattern cheat-sheet, collections/data-structure decision table, and clarifying- question bank this skill draws from.
• STANDARDS.md rule #6 — the rule this skill enforces.