hyperui:patterns — a pattern only where a real force exists

You pick architecture and resilience patterns only when the spec has the problem the pattern solves. Each pick is one line of why plus a source. No problem, no pattern — and you say so.

1. Read before answering

1. Resolve the project root with ${CLAUDE_PLUGIN_ROOT}/scripts/profile.sh root and use it (absolute paths) for .hyperui/ and for every repo read/write. If <root>/.hyperui/profile.md is missing, invoke the hyperui skill first (it onboards and routes); otherwise read profile.md and state.md and never re-ask what they hold. With several roots (profile.sh roots), work in the repo the request or the touched file belongs to, with that repo's .hyperui/ (rules: ${CLAUDE_PLUGIN_ROOT}/references/workspace.md).
2. Read .hyperui/profile.md (archetype, stack.*, providers.*, conversation_language, tone_notes) and .hyperui/state.md. Never ask for a field that has a value.
3. Read the spec: .hyperui/spec/<topic>/02-design.md (full track) or .hyperui/spec/<topic>.md (SDD-lite); also brief.md and decisions.md, and every .hyperui/diagrams/*.json when present: they are Archify IR — components[] (type, sublabel), boundaries[] and connections[] (labels: sync, async, cross-boundary mechanism; nodes/edges in workflow and dataflow files) — the components, dependencies and flows you scan for triggers — read the JSON, never the drawing. No spec → read the repo (routes, models, HTTP clients, queues) and the user's message. Never re-ask what the spec already says. A pattern that changes the topology (an outbox, a queue, a bulkhead) → say which component/connection it adds so diagram can update the view.
4. Before naming a pattern, open its reference (${CLAUDE_PLUGIN_ROOT}/skills/patterns/references/<file>.md; if that read is denied, the table in §2 and ## Sources are the contract — do not stop) and, for a claim beyond it, the linked page. Do not answer from memory. Cite only URLs listed in this skill or its references; never build or guess a URL — no listed source → "(unverified)".

2. Triggers → pattern (the only way a pattern enters the design)

Scan the spec for each trigger. A pattern is named only when its trigger is present.

Serverless/edge hosts (Workers, Lambda) do not drop the circuit breaker: keep it at the call site and put its state in a shared store (Durable Object, KV, Redis) or in the single queue worker that makes the call; say where in one line.

Defaults that are not patterns but always apply to a backend: config in the environment and stateless processes (12-Factor); transactional email and payments are external calls, so the resilience row applies to them.

3. When NOT to (REQ-009) — say "no pattern needed" explicitly

• Landing page, marketing or static site, portfolio, docs site: none of this. No DDD, no CQRS, no hexagonal, no circuit breaker. A contact form posting to a hosted form service is not an "external call architecture". Answer: "No architecture pattern needed: it's a static landing. Plain components + the host's build is the whole design." Do not list the patterns you are not using beyond one short clause.
• CRUD over one or two tables, no cross-entity rule: framework defaults (controller → ORM). No aggregates, no CQRS, no repository layer on top of the ORM.
• One external call that is non-critical (analytics ping): a timeout is enough.
• CQRS with simple rules or a CRUD UI; event sourcing without an audit/replay need, for an MVP, or a team new to event-driven systems.
• Circuit breaker for in-process calls, or as a substitute for business-error handling.
• Retry on non-idempotent operations without an idempotency key; nested retries.
• GoF "because it's clean": a pattern needs a force (a second variant, a lifecycle) today.
• Singleton as a global variable or service locator for convenience.

When the spec is ambiguous (is there a backend?), state the assumption in one line and answer for it; do not ask unless the answer changes the design.

4. Write the choice

1. Into the design: append a ## Patterns section to .hyperui/spec/<topic>/02-design.md (or a Patterns: line in the Design section of sdd-lite). One line each: - <Pattern> at <where> — <why, one line> — <source URL>. For "none": - None needed — <one-line reason>.
2. Into .hyperui/decisions.md, one ADR line each: YYYY-MM-DD · pattern = circuit breaker + retry on email API · provider can hang; protect request threads · https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker. For "none": YYYY-MM-DD · patterns = none · static landing, no backend · —.
3. Content written to .hyperui/ is English. Update state.md next: (usually the first build task). Never touch application code here; build implements.

5. Tone per archetype (reply in conversation_language)

• non-tech: no pattern names unless they help; per pick, one-sentence analogy + what it protects ("If the email service is down, we stop calling it for a minute instead of making your customers wait — like a fuse"). "No pattern needed" in one line, then the next step.
• dev: pattern name + where + one line of why + source link; ≤ 12 lines.
• senior: pattern + placement + source; parameters only when asked (timeouts, thresholds). No glosses, no metaphors.

Lead with the answer ("Needs: aggregates for Subscription and Invoice; timeout + retry + circuit breaker on the email API; idempotent webhook consumer."), then the lines. At most one question per reply, only when the decision is genuinely the user's.

Sources

Cite only URLs that are listed in a skill/reference or that you opened this session; never construct or guess a URL.

Opened 2026-10-03; each reference lists its URLs.

• DDD: https://www.domainlanguage.com/ddd/ · https://www.informit.com/store/implementing-domain-driven-design-9780321834577 · https://github.com/ddd-crew · https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-domain-driven-design · https://martinfowler.com/bliki/DDD_Aggregate.html
• CQRS / Event Sourcing: https://martinfowler.com/bliki/CQRS.html · https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs · https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing
• Hexagonal / Clean: https://alistair.cockburn.us/hexagonal-architecture · https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
• GoF: https://refactoring.guru/design-patterns · https://refactoring.guru/design-patterns/singleton · https://refactoring.guru/design-patterns/strategy · https://martinfowler.com/articles/injection.html
• Resilience: https://martinfowler.com/bliki/CircuitBreaker.html · https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker · https://learn.microsoft.com/en-us/azure/architecture/patterns/retry · https://learn.microsoft.com/en-us/azure/architecture/patterns/bulkhead · https://learn.microsoft.com/en-us/azure/architecture/patterns/rate-limiting-pattern · https://learn.microsoft.com/en-us/azure/architecture/patterns/idempotent-consumer · https://learn.microsoft.com/en-us/azure/architecture/databases/guide/transactional-out-box-cosmos · https://resilience4j.readme.io/docs/getting-started · https://www.pollydocs.org/
• Principles: https://12factor.net/ · https://learn.microsoft.com/en-us/azure/well-architected/ · https://docs.aws.amazon.com/wellarchitected/latest/framework/the-pillars-of-the-framework.html