@rune-kit/rune 2.13.0 → 2.14.0

package/skills/ba/references/context-md-format.md

@@ -0,0 +1,136 @@
+# CONTEXT.md — Project Glossary Format
+
+Persistent vocabulary for the project's domain — what nouns mean, how concepts relate, which words are aliases of which. Lives at the repo root (or per-bounded-context root in multi-context repos).
+
+## Where it lives
+
+```
+<repo-root>/
+├── CONTEXT.md                   ← single-context repo
+└── src/
+
+# OR for multi-context repos:
+<repo-root>/
+├── CONTEXT-MAP.md               ← lists each context + relationships
+└── src/
+    ├── ordering/CONTEXT.md
+    └── billing/CONTEXT.md
+```
+
+If `CONTEXT-MAP.md` exists at root, the repo has multiple contexts; otherwise it's single-context.
+
+## Lazy creation
+
+CONTEXT.md is created **only when there's a non-trivial term to record**. Empty file = bad signal. Absent file = silent OK.
+
+`ba` checks via Glob; absence is **not** flagged as a project gap. Don't suggest "you should create one." Wait until a term needs sharpening.
+
+## Format
+
+```markdown
+# Project Glossary
+
+One-line description of what this project is and why this glossary exists.
+
+## Language
+
+| Term | Definition | Aliases to avoid | Status |
+|------|------------|-------------------|--------|
+| **Order** | A customer's request to purchase items | Purchase, transaction | canonical |
+| **Invoice** | A request for payment sent after delivery | Bill, payment request | canonical |
+| **Customer** | A person or organization that places orders | Client, buyer, account | canonical |
+| **User** | An authentication identity in the system | Login, account | canonical |
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+- A **Customer** may or may not be a **User** (guests can place orders)
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
+
+## Flagged ambiguities
+
+- "account" was used for both **Customer** and **User** — resolved: distinct concepts. **Customer** places orders; **User** is an authentication identity.
+- "transaction" sometimes meant **Order** and sometimes **Payment** — resolved: avoid the word entirely.
+```
+
+## Term schema
+
+Each row in the **Language** table:
+
+| Column | Required | Description |
+|--------|----------|-------------|
+| Term | ✅ | Bold, kebab-case-friendly singular noun (or short phrase) |
+| Definition | ✅ | One sentence. Defines what it IS, not what it does. |
+| Aliases to avoid | optional | Other words the team has used; agents and humans must avoid them in code, comments, and conversation |
+| Status | ✅ | `canonical` (settled) \| `pending` (waiting on domain-expert confirmation) \| `conflicted` (active disagreement, needs resolution) |
+
+## Update protocol
+
+### Inline sharpen (during a BA session)
+
+When the user uses a term whose meaning is ambiguous, propose a precise canonical version. When confirmed, update CONTEXT.md right there. Don't batch.
+
+> "You used 'account' twice — once meaning **Customer** (the person ordering), once meaning **User** (the login). I'll record these as distinct in CONTEXT.md."
+
+### Cross-reference (HARD-GATE)
+
+When the user asserts behavior — "the system cancels Orders when X" — `ba` MUST grep the codebase to verify before recording in CONTEXT.md. If grep contradicts the user, surface the conflict and ask which is canonical.
+
+> User: "Yes, partial cancellation is supported."
+> Agent (after grepping `src/orders/cancel.ts`): "The code path I see only handles full cancellation (`cancel(orderId)` returns `Order` with status `cancelled`, no partial-quantity argument). Either the code is incomplete, or partial cancellation isn't implemented yet. Which is the canonical behavior?"
+
+This gate stops AI agents from silently recording user-asserted behavior that contradicts the code — a frequent source of "the docs say X but the code does Y" drift.
+
+### Conflict gate
+
+When a new term has ≥0.7 token overlap with an existing one, force a user choice:
+
+| Choice | Action |
+|--------|--------|
+| Merge | Combine the new term's aliases into the existing entry |
+| Rename | Pick a distinct slug for the new term |
+| Keep distinct | Confirm the overlap is coincidental; record both |
+
+Agents must NOT silently re-define existing terms.
+
+## Single vs multi-context
+
+**Single context (most repos)**: one `CONTEXT.md` at the repo root.
+
+**Multiple contexts**: a `CONTEXT-MAP.md` at the root lists where each context lives:
+
+```markdown
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+
+## Relationships
+
+- **Ordering → Billing**: Ordering emits `OrderPlaced` events; Billing consumes them
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+`ba` infers structure:
+- If `CONTEXT-MAP.md` exists → multi-context; read it to find the right CONTEXT.md
+- If only root `CONTEXT.md` exists → single-context
+- If neither exists → silent skip; create root CONTEXT.md lazily on first term resolution
+
+## What does NOT belong in CONTEXT.md
+
+- Generic programming concepts (timeouts, error types, function signatures) — these aren't domain terms.
+- Module / class names — they belong in code, not glossary, unless they have meaning to a domain expert.
+- Implementation details — CONTEXT.md is the *what* (concept), not the *how* (data shape).
+
+Before adding a term, ask: would a non-engineer domain expert recognize this and care? If no, don't add it.
+
+## Relationship to CLAUDE.md
+
+CLAUDE.md describes *how to work in this repo* — conventions, danger zones, deploy commands. CONTEXT.md describes *what these words mean* — the domain glossary. The scopes are mutually exclusive; never duplicate.

package/skills/ba/references/explore-first.md

@@ -0,0 +1,107 @@
+# Explore-First Gate
+
+The explore-first rule: **never ask the user a question whose answer is in the codebase, the user's message, or the project metadata.** Every question burns user attention; an inferable question burns it for nothing.
+
+This is enforced as a HARD-GATE at Step 2.0 of `ba`, before any of the 5 elicitation questions are emitted.
+
+## The 4-item pre-check
+
+For each question the agent intends to ask, walk through this checklist:
+
+1. **Is the answer in `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / `pom.xml`?**
+   - Stack, framework, language version, dependencies, scripts → all live here.
+2. **Is the answer in `README.md` or `CLAUDE.md` or `docs/`?**
+   - Project description, target audience, conventions, deploy process.
+3. **Is it inferable from file extensions, directory structure, or config files?**
+   - `.tsx` files → React frontend. `Dockerfile` → containerized deploy. `.github/workflows/*` → CI exists.
+4. **Has the user answered it earlier in this conversation?**
+   - Read back through the conversation; cached answers are reusable.
+
+If ANY of the 4 checks would yield the answer, the question is inferable. **Don't ask it.** Read the source, infer, and proceed.
+
+## Tool-call evidence requirement (HARD-GATE)
+
+For every question Q the agent emits, there MUST be prior tool-call evidence in the same session:
+
+- At least 1 `Read`, `Glob`, or `Grep` related to Q's domain, OR
+- An explicit declaration: *"Q cannot be answered from project artifacts because [specific reason]."*
+
+Without one of these, Q is BLOCKED. The receiving validator (preflight, completion-gate) checks the tool-call log for evidence before allowing the question to count toward the 5-question budget.
+
+This prevents lazy questioning. The gate is "tried to infer" — not "must succeed in inferring." If the file simply doesn't have the answer, that's fine; the attempt is the gate.
+
+## Worked examples
+
+### ❌ Wrong — skips inference
+
+User: "I want to add a payment integration."
+
+Agent: "What language and framework are you using?"
+
+Failure: `package.json` (or equivalent) answers this. No grep needed.
+
+### ✅ Right — infers first
+
+User: "I want to add a payment integration."
+
+Agent: *(reads `package.json` — sees `"react": "^18"`, `"next": "^14"`)*
+Agent: "I see you're on Next.js 14 with React 18. For the payment integration, are you targeting Stripe, PayPal, or something else?"
+
+The first question is now non-trivial — it's the question only the user can answer.
+
+### ❌ Wrong — re-asks cached answer
+
+Earlier in the session: User said "the deadline is end of Q2."
+
+Agent (later): "What's the timeline for this?"
+
+Failure: cached answer exists. Re-asking is redundant.
+
+### ✅ Right — uses cached answer
+
+Agent: "Given the Q2 deadline you mentioned, [follow-up question that builds on it]."
+
+### ❌ Wrong — asks shape questions for inferable values
+
+User: "Build me a CLI tool that..."
+
+Agent: "Are you using TypeScript or JavaScript?"
+
+Failure: check `tsconfig.json` and `package.json`'s `type: "module"`. Or check existing files' extensions.
+
+### ✅ Right — narrow to genuine unknowns
+
+Agent: *(checks tsconfig + sample file)*
+Agent: "I see you're on TypeScript with strict mode. For the CLI tool, are you targeting Node 20+ or do we need to support older runtimes?"
+
+## What questions ARE worth asking
+
+Questions that survive the explore-first filter typically:
+
+- **Reveal user intent** that's not in the code ("what's the success metric for this feature?")
+- **Choose between credible alternatives** the code doesn't disambiguate ("auth: JWT vs session cookies?")
+- **Set scope** that the user hasn't yet bounded ("should this also handle anonymous users?")
+- **Capture domain expertise** the codebase doesn't encode ("when an Order is cancelled, do we refund automatically or wait for review?")
+
+These are the high-leverage questions. Aim for 5 of them, not 5 of "what stack are you using?"
+
+## Caching results
+
+When explore-first finds an inferable answer, record it in the requirements doc as a cached fact:
+
+```
+**Inferred from package.json**: TypeScript 5.4, Next.js 14.2, React 18.3
+**Inferred from .github/workflows/**: CI runs on PRs targeting main
+**Inferred from CLAUDE.md**: Strict TypeScript, no `any`, semantic commits
+```
+
+Future BA sessions reuse these without re-running grep.
+
+## When the rule relaxes
+
+Two narrow exceptions:
+
+1. **Stack/conventions are not yet in the repo** (greenfield, brand-new project) — explore-first finds nothing, so questions are necessary. Note "no project metadata available" in the question rationale.
+2. **User explicitly asked a redundant question themselves** — sometimes the user wants confirmation. "Yes, you're on TypeScript — the `tsconfig.json` confirms it. Anything else to verify?"
+
+Otherwise, the rule applies. Burn no user attention on questions agents can answer alone.

package/skills/ba/references/out-of-scope-format.md

@@ -0,0 +1,152 @@
+# `.out-of-scope/` Knowledge Base — Format & Matching
+
+A persistent record of rejected feature requests so AI agents stop re-litigating the same decision across sessions. Project-scoped, version-controlled, durable.
+
+## Where it lives
+
+```
+<repo-root>/
+├── .out-of-scope/
+│   ├── dark-mode.md
+│   ├── plugin-system.md
+│   └── graphql-api.md
+```
+
+One file per **concept**, not per issue. Multiple incoming requests for the same thing are appended to a single concept file's `prior_requests` list.
+
+## File format
+
+YAML frontmatter (for machine parsing) + Markdown body (for humans).
+
+```markdown
+---
+concept: dark-mode
+aliases: [night-theme, dark-theme, theme-switcher]
+decision: rejected
+rejected_at: 2026-04-27
+rejected_by: review-intake
+priority_to_revisit: low      # low | medium | high
+prior_requests:
+  - id: gh-issue-42
+    summary: Add dark mode support
+    closed_at: 2025-08-01
+  - id: discord-thread-2026-02-14
+    summary: Night theme for accessibility
+    closed_at: 2026-02-15
+conflicts_with: []            # paths to ADRs that this rejection contradicts
+revisit_if:
+  - "team adds front-end engineer"
+  - "user count crosses 50k"
+---
+
+# Dark Mode
+
+This project does not support runtime dark mode.
+
+## Why out of scope
+
+[Substantive reasoning — references project scope, technical constraints, or strategic decisions. NOT temporary circumstances ("we're busy now" — that's a deferral, not a rejection).]
+
+The rendering pipeline assumes a single color palette resolved at build time. Adding runtime theming would require:
+
+- A theme context provider wrapping every render
+- Per-component theme-aware style resolution
+- A persistence layer for user theme preferences
+
+This is a significant architectural change that conflicts with the project's focus on author-time content and downstream-consumer flexibility.
+
+## What would change our mind
+
+- A user paying for theme switcher specifically (revenue signal)
+- A team member with deep expertise on theme-aware CSS pipelines
+- A platform requirement (e.g., partner integration mandates dark mode)
+```
+
+## Frontmatter fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `concept` | string | ✅ | kebab-case slug; matches filename without `.md` |
+| `aliases` | string[] | ✅ | Other phrasings of the same concept; used by similarity matcher |
+| `decision` | enum | ✅ | `rejected` (only — deferrals do not belong here) |
+| `rejected_at` | ISO date | ✅ | When the decision was made |
+| `rejected_by` | enum | ✅ | `ba` \| `review-intake` \| `incident` \| `cook` |
+| `priority_to_revisit` | enum | optional | `low` \| `medium` \| `high`; default `low` |
+| `prior_requests` | object[] | ✅ | At least one entry; appended on every re-request |
+| `conflicts_with` | string[] | optional | Paths to ADRs this contradicts (rare, surface for review) |
+| `revisit_if` | string[] | optional | Concrete signals that should trigger re-evaluation |
+
+## Slug rules
+
+- kebab-case, lowercase
+- max 40 chars
+- recognizable without opening the file (`dark-mode` good; `feature-x-v2` bad)
+- distinct from existing concepts — if a new slug has ≥0.7 alias overlap with an existing one, the writer MUST prompt: merge or pick distinct slug.
+
+## Concept-similarity matching
+
+When `ba` Step 1.5 runs intake on a new request, it builds a hash-keyed map:
+
+```
+Map<lowercased_token, [concept_slugs]>
+```
+
+For each `.out-of-scope/*.md` file, it indexes:
+- `concept` field tokens (split on `-`)
+- `aliases` field tokens
+- 1–3-word phrases from the body's title and first paragraph
+
+For incoming request, it tokenizes the same way, computes overlap with each indexed concept, and returns:
+
+| Confidence | Range | Action |
+|------------|-------|--------|
+| Exact match | ≥0.8 | Surface immediately: "This matches a prior rejection (`<slug>`). Do you still feel the same way?" |
+| Similar | 0.5–0.79 | Mention as similar prior decision, offer to read the file together |
+| Weak / no match | <0.5 | Ignore (don't pollute conversation with low-confidence matches) |
+
+The matcher is purely lexical — agents do NOT call out to a model to compute similarity. Lexical is fast (~1ms per file), deterministic, and good enough for the ≥0.8 threshold. Domain-specific concept clustering is a future enrichment.
+
+## When to write a new file
+
+Only when:
+1. An **enhancement** (not a bug) is rejected as `wontfix` / `out of scope`
+2. The reasoning is **durable** (project-scope, technical constraint, strategic decision) — NOT a temporary deferral
+3. A future similar request would benefit from finding this record
+
+If the rejection reason is "we're busy this quarter" → that's a deferral, route to a backlog issue, not `.out-of-scope/`.
+
+## When to append to an existing file
+
+When the matcher finds an exact concept match, append to `prior_requests`:
+
+```yaml
+prior_requests:
+  - id: gh-issue-42
+    summary: Add dark mode support
+    closed_at: 2025-08-01
+  - id: gh-issue-87        # <-- new
+    summary: Night theme for accessibility
+    closed_at: 2026-02-15  # <-- new
+```
+
+Do NOT create a duplicate file. Update the existing one.
+
+## When to delete a file
+
+When the maintainer decides to actually build the rejected feature. The file gets deleted in the same commit that opens the new tracking issue. Historical issues (in `prior_requests`) are not reopened — they're snapshots.
+
+## Conflicts with ADRs
+
+If a rejection contradicts an existing ADR (e.g., ADR says "we use REST" but a request asks for GraphQL and the rejection cites different reasons), populate `conflicts_with: [docs/adr/0007-rest-only.md]`. `audit` later flags this for cross-reference.
+
+## Validation (compiler test)
+
+`compiler/__tests__/out-of-scope-format.test.js` validates:
+- Frontmatter parses as YAML
+- Required fields present
+- `decision == "rejected"`
+- `concept` matches filename
+- `prior_requests` has ≥1 entry
+- Slug rules pass
+
+Failures here block the merge that introduced the broken file.

package/skills/brainstorm/SKILL.md

@@ -3,7 +3,7 @@ name: brainstorm
 description: Creative ideation and solution exploration. Generates multiple approaches with trade-offs, uses structured frameworks (SCAMPER, First Principles), and hands off to plan for structuring.
 metadata:
   author: runedev
-  version: "0.5.0"
+  version: "0.6.0"
   layer: L2
   model: opus
   group: creation
@@ -43,6 +43,23 @@ Activated for product-level rethinks — not "how to implement X" but "should we
 3. MUST apply the "10-star experience" lens: what would a 1-star, 5-star, and 10-star version look like?
 4. MUST challenge assumptions: "why does this need to be a page?" "why does the user need to do this at all?"
 
+### Design-It-Twice Mode
+Activated when exploring alternative *interface shapes* for a deepening candidate. Spawns N=3-4 parallel subagents, each pinned to a radically different design constraint (minimize / maximize-flexibility / optimize-common-case / ports-and-adapters), computes a diversity score over feature vectors, and presents sequentially with an opinionated recommendation. Used by `improve-architecture` when a deepened module's interface is non-obvious.
+
+**Design-It-Twice triggers:**
+- `improve-architecture` (Step 7 hand-off) when the picked candidate has multiple credible interface shapes
+- User says "design it twice", "explore interfaces", "what are the API options"
+- Manual: `/rune brainstorm design-it-twice <module>`
+
+**Design-It-Twice constraints:**
+1. MUST spawn N=3 (minimum) or N=4 (when dependency category is remote-owned or true-external) parallel subagents
+2. Each subagent pinned to exactly ONE of the 4 standard constraints — enforced via prompt template
+3. Diversity score MUST be >= 0.4 before presenting (re-spawn once if below)
+4. Recommendation MUST be opinionated with a concrete hedge condition — "it depends" is BLOCKED
+5. Hybrid synthesis (Step 4.5) is opt-in when 2 designs have complementary strengths
+
+Full doctrine: [references/design-it-twice.md](references/design-it-twice.md).
+
 ### Rescue Mode
 Activated when an approach has been tried and **fundamentally failed** — not a bug, but a wrong approach. Rescue mode forces **category-diverse** alternatives instead of variants of the failed approach.
 
@@ -102,6 +119,7 @@ Direct API call ≠ Wrapper/middleware layer ≠ Reverse engineering ≠ Browser
 - User: `/rune brainstorm <topic>` direct invocation (Discovery Mode)
 - User: `/rune brainstorm rescue <context>` manual rescue (Rescue Mode)
 - `ba` (L2): when multiple requirement approaches exist
+- `improve-architecture` (L2): when a deepened module's interface needs Design-It-Twice exploration
 
 ## Cross-Hub Connections
 
@@ -143,6 +161,7 @@ CRAZY 8s         — 8 ideas in 8 minutes (rapid ideation)
 ### Step 0 — Detect Mode
 
 Check the invocation context:
+- If `mode="design-it-twice"` is set, or caller is `improve-architecture` Step 7, or user says "design it twice / explore interfaces" → **Design-It-Twice Mode** (jump to Step 2.5 directly)
 - If `mode="vision"` is set, or user says "rethink/reimagine/step back" → **Vision Mode**
 - If `mode="rescue"` is set, or caller is Approach Pivot Gate / 3-Fix Escalation → **Rescue Mode**
 - Otherwise → **Discovery Mode**
@@ -209,6 +228,7 @@ When Step 1 or Step 1.5 reveals gaps, ask structured clarifying questions using
 
 **Discovery Mode**: Produce exactly 2–3 distinct approaches.
 **Rescue Mode**: Produce exactly 3–5 approaches, each a **different category** from the failed approach.
+**Design-It-Twice Mode**: skip to Step 2.5.
 
 Each approach must be meaningfully different — not just variations of the same idea. For each approach provide:
 - **Name**: short memorable label
@@ -220,6 +240,21 @@ Each approach must be meaningfully different — not just variations of the same
 
 If the domain is unfamiliar or data is needed, invoke `rune:research` before generating options. For product/market context, invoke `rune:trend-scout`.
 
+### Step 2.5 — Constraint Matrix Spawn (Design-It-Twice Mode only)
+
+Spawn N=3 parallel subagents (or N=4 if dependency category is `remote-owned` / `true-external`). Each is pinned to exactly one constraint via Task tool spawn:
+
+| Constraint ID | Pinning |
+|---------------|---------|
+| C1 | "Minimize the interface — aim for 1–3 entry points. Maximize leverage per entry point." |
+| C2 | "Maximize flexibility — support many use cases, extension surface." |
+| C3 | "Optimize for the most common caller — make the default case trivial. Rare cases pay cost." |
+| C4 | "Design around ports and adapters for cross-seam dependencies." (only when applicable) |
+
+Use the spawn prompt template from [references/design-it-twice.md](references/design-it-twice.md). Include CONTEXT.md domain terms in the prompt so each design names things consistently with project domain language.
+
+Each subagent returns a YAML block: interface, usage example, what's hidden, dependency strategy/adapters, tradeoffs.
+
 ### Step 3 — Evaluate
 
 **Discovery Mode** — Apply the most relevant framework:
@@ -243,6 +278,26 @@ Additionally in Rescue Mode:
 
 For approaches with many interacting variables, invoke `rune:sequential-thinking` to reason through trade-offs systematically.
 
+### Step 3.5 — Diversity Gate (Design-It-Twice Mode only)
+
+After subagents return, compute the diversity score:
+
+```
+feature_vector(design) = [
+  count(methods), count(return_types), count(adapter_kinds),
+  count(dependencies), paradigm_tag, has_async, has_streaming
+]
+diversity = 1 - mean(pairwise_jaccard(feature_vectors))
+```
+
+| Diversity | Action |
+|-----------|--------|
+| ≥ 0.6 | Proceed to Step 4 |
+| 0.4 – 0.59 | Surface to user: "designs are similar in [shared trait] — re-spawn with different constraints?" |
+| < 0.4 | Re-spawn once with rotated constraints; if still <0.4, give up and present what's there with a diversity-low warning |
+
+Emit `diversity_score` in chain_metadata.
+
 ### Step 4 — Recommend
 
 Select ONE approach as the recommendation. State:
@@ -288,6 +343,20 @@ For product-level brainstorming (Vision Mode or when approaches have strategic i
 - Skip this step for pure technical brainstorming (no product/strategy dimension)
 - If all tiers look equally expensive → approach may be too complex for Quick Win
 
+### Step 4.5 — Hybrid Synthesis (Design-It-Twice Mode, optional)
+
+If two designs have complementary strengths (e.g., C1's leverage + C4's seam discipline), propose a 4th option that combines them. Skip this step when no two designs have clear complementary strengths.
+
+```
+Option D (Hybrid C1 + C4):
+  - Interface: 3 methods (from C1's minimization)
+  - Adapters: HttpAdapter + InMemoryAdapter (from C4's port discipline)
+  - Pros: small surface AND testable across the seam
+  - Cons: more upfront design work; locks the port early
+```
+
+The hybrid is the recommended default in many cases. Be opinionated.
+
 ### Step 5 — Return to Plan
 Pass the recommended approach back to `rune:plan` for structuring into an executable implementation plan. Include:
 - The chosen option name
@@ -306,6 +375,9 @@ If the user rejects the recommendation, return to Step 2 with adjusted constrain
 6. [Rescue Mode] MUST NOT generate variants of the failed approach — each approach must be a different CATEGORY
 7. [Rescue Mode] MUST use Collision-Zone or Inversion framework — conventional thinking already failed
 8. [Rescue Mode] MUST include at least 1 unconventional/hacky approach — sometimes the "dirty" solution is the only one that works
+9. [Design-It-Twice Mode] MUST spawn parallel subagents with one constraint pinned per agent — fake diversity (one agent producing N options) is BLOCKED
+10. [Design-It-Twice Mode] MUST emit `diversity_score` and re-spawn (once) if below 0.4 floor
+11. [Design-It-Twice Mode] MUST NOT produce "it depends" recommendations — pick one design with a concrete hedge condition
 
 ## Output Format
 
@@ -363,6 +435,10 @@ Known failure modes for this skill. Check these before declaring done.
 | [Rescue] All approaches are "clean/proper" — no hacky option | MEDIUM | At least 1 must be unconventional — wrappers, reverse-engineering, debug mode abuse, proxy layers |
 | Calling plan directly instead of presenting options first | CRITICAL | Steps 2-3 are mandatory — present options, get approval, THEN call plan |
 | "Creative" options that ignore stated constraints | MEDIUM | Every option must satisfy the constraints declared in Step 1 |
+| [Design-It-Twice] Single agent producing N options instead of N parallel subagents | HIGH | Step 2.5 — constraint pinning happens at spawn, not in a loop. Each constraint = one Task call |
+| [Design-It-Twice] Diversity score below 0.4 ignored | HIGH | Step 3.5 gate — re-spawn once; if still low, present with explicit "low-diversity" warning |
+| [Design-It-Twice] "It depends" recommendation | HIGH | Step 4 — must pick one with a hedge; if genuinely tied, propose hybrid (Step 4.5) and recommend that |
+| [Design-It-Twice] Forgetting to include CONTEXT.md domain terms in subagent prompt | MEDIUM | Step 2.5 spawn template requires domain glossary be passed through |
 
 ## Done When