didyouknow-v2

Please deep think / ultrathink as this is a complex task.

didyouknow

Universal clarity builder - analyze any context (spec, plan, tasks, subtask, code) and surface critical "Did you know?" insights through natural conversation. Supports two modes: default (risks, gotchas, hidden assumptions) and enhance (scoped improvement ideas).

User input:

$ARGUMENTS

Expected usage patterns:
```bash
/didyouknow --spec <path>      # Analyze a feature specification
/didyouknow --plan <path>      # Analyze an implementation plan
/didyouknow --tasks <path>     # Analyze phase tasks
/didyouknow --subtask <path>   # Analyze a subtask
/didyouknow --code <path>      # Analyze code file(s)
/didyouknow                    # Auto-detect most recent context
/didyouknow --enhance          # Enhancement mode (5 ideas, scoped to feature)
/didyouknow --enhance 3        # Enhancement mode with custom count
/didyouknow --enhance --spec <path>  # Enhance mode on a specific spec
```

## Modes

### Default Mode (clarity)
Surface risks, gotchas, hidden assumptions, and non-obvious implications in what already exists. Always 5 insights.

### Enhance Mode (`--enhance [N]`)
Surface scoped improvement ideas — UX polish, missing quality-of-life features, enhancements to the existing feature. Does NOT suggest tangential or out-of-scope ideas. Defaults to 5 ideas; the user may specify a custom count (e.g. `--enhance 3`, `--enhance 10`).

## Purpose

Build shared understanding between human and AI. In **default mode**, surface non-obvious implications, gotchas, and critical insights. In **enhance mode**, surface improvement ideas scoped to the feature being analyzed. This is a **clarity and ideation tool** — run it whenever you need to step back and really understand or improve what's being built.

## Flow

### 1) Context Loading

- Parse flags to determine context type (spec/plan/tasks/subtask/code)
- Detect mode: if `--enhance` is present, activate enhance mode. Parse optional count (default 5).
- If auto-detect mode (no flags): search `docs/plans/` for most recent plan or spec
- Read the primary context document completely
- Load related documents for full picture:
  * If analyzing plan → also read the spec
  * If analyzing tasks → also read the plan and spec
  * If analyzing code → read relevant docs if they exist
- **Domain awareness**: If `docs/domains/registry.md` exists, scan relevant domain.md files for context. If `docs/domains/domain-map.md` exists, read the topology to understand contract relationships and potential issues (circular deps, orphans, god domains). Note which domains the current artifact targets (from spec `## Target Domains` if present). This is background context — domain insights surface naturally alongside other lenses, not as a forced category.

### 2) ULTRA-DEEP THINKING (Most Critical Step)

**Spend significant thinking time here.**

#### Default Mode Lenses

- **User Experience** — what changes for users? What's surprising?
- **System Behavior** — new constraints, assumptions, data flow changes?
- **Technical Constraints** — platform limits, API restrictions, won't-work-if?
- **Integration & Ripple Effects** — what else does this touch? Downstream impact?
- **Hidden Assumptions** — what are we betting on that could fail?
- **Edge Cases & Failure Modes** — unusual conditions, cascading failures?
- **Performance & Scale** — bottlenecks, resource concerns at scale?
- **Security & Privacy** — exposed data, auth gaps, vulnerabilities?
- **Deployment & Operations** — coordination needed, rollback risks?
- **Domain Boundaries** — are concepts in the right domain? Reaching into another domain's internals? Missing contract? Duplicating something in another domain? Wrong dependency direction?
- **Concept Documentation** — are domain concepts discoverable? Missing `§ Concepts` section in domain.md? Stale concepts that no longer match implementation? Concept reuse opportunity across domains? Related contracts scattered across domains that should be unified under one concept?

**Domain insights are not mandatory.** They surface when genuinely relevant. If domains are clean, they may not make the top 5. That's fine.

**When CS scores exist** (plans/tasks), challenge them:
- CS-1/2: What could make this NOT trivial?
- CS-3: How do we prove this works?
- CS-4/5: What's the rollback plan? Need subtask decomposition?

**Select the 5 most impactful insights** — non-obvious, actionable, ordered by impact, spanning different perspectives.

#### Enhance Mode Lenses

- **UX Polish** — what would make this smoother, more intuitive, more delightful?
- **Missing Conveniences** — quality-of-life features users would expect but aren't specified?
- **Robustness** — error messages, fallbacks, graceful degradation that would improve trust?
- **Consistency** — does this align with patterns elsewhere in the codebase/product?
- **Developer Experience** — logging, debugging hooks, configurability that would help future maintainers?
- **Domain Health** — would a contract make this more composable? Reuse opportunity across domains?

**Stay scoped to the feature being analyzed.** Do NOT suggest tangential features or out-of-scope additions. Every idea must directly enhance what's already planned.

**Select the N most valuable ideas** (default 5, or user-specified count) — ordered by value, practical, and scoped to the existing feature.

### 3) CONVERSATIONAL PRESENTATION (One at a Time)

**⚠️ CRITICAL — HARD RULE: Present ONLY ONE insight per message. Output ONE insight, then STOP and WAIT for the human to respond before presenting the next. Do NOT present insight #2 until the human has replied to #1. This is the most important rule in this entire prompt.**

For each insight/idea, present it like this:

**Default mode:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━