| name | didyouknow-v2 |
| description | Universal clarity utility - deep think 5 critical insights and discuss conversationally to build shared understanding. Run after any spec/plan/tasks/code. Domain-aware 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:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**#N: [Short Title]**
Did you know [one-sentence insight]?
This matters because [one sentence on why it's important].
**Recommendation**: [one-line recommendation]
What do you think?
```
**Enhance mode:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
**#N/N: [Short Title]**
What if we [one-sentence enhancement idea]?
This would improve [one sentence on the benefit].
**Recommendation**: [one-line suggestion]
Worth adding?
```
That's it. Short. Punchy. The human will do one of:
- **Agree** → capture decision, move on
- **Disagree/discuss** → engage naturally, reach alignment
- **"Tell me more"** → expand with implications, examples, deeper analysis
- **"Give me options/alternatives"** → present 2-4 concrete options with pros, cons, complexity (CS), and your recommendation. Include enough detail per option that the human can choose confidently.
**Do NOT front-load** the deep dive, options matrix, numbered consequences, or examples. Only expand when asked. Match the depth to what the human asks for.
**Rules:**
- **ONE insight per message. STOP after each. WAIT for the human to reply.** Never present two or more insights in the same message. This is non-negotiable.
- Use "we/our/us" — collaborative language
- Ask real questions, not rhetorical ones
- Start with the insight, no preamble ("Can we talk about..." — NO)
### 4) After Each Insight
Once a decision is reached:
```
✓ [What was decided] — [one-line rationale]
```
If the decision requires doc updates, make them immediately. Confirm briefly:
```
Updated [file]: [what changed]
```
Do NOT defer updates to the end.
### 5) Session Summary
After all insights/ideas are complete, output a brief summary:
```
**Did You Know — Complete**
1. [Title] → [Decision]
2. [Title] → [Decision]
3. [Title] → [Decision]
4. [Title] → [Decision]
5. [Title] → [Decision]
[Count] decisions made, [count] files updated.
Next: [suggested next action]
```
Then append a compact record to the source document:
```markdown
---
## Critical Insights ([date])
| # | Insight | Decision |
|---|---------|----------|
| 1 | [One-sentence insight] | [What was decided] |
| 2 | [One-sentence insight] | [What was decided] |
| 3 | [One-sentence insight] | [What was decided] |
| 4 | [One-sentence insight] | [What was decided] |
| 5 | [One-sentence insight] | [What was decided] |
Action items: [list any, or "None"]
```
No new files created — insights are appended to the analyzed document.
## Validation
- Default mode: exactly 5 insights. Enhance mode: N ideas (default 5, or user-specified count). Always one at a time.
- Human responds to each before proceeding
- Each insight is 3-5 lines on first presentation (not a wall of text)
- Deep dives only happen when the human asks
- Updates applied immediately after each decision
- Insights span multiple perspectives
- Ordered by impact (highest first)
## Anti-Patterns
- **Dumping all 5 at once or presenting more than one insight per message (MOST COMMON FAILURE — never do this)**
- Front-loading deep dives, options matrices, and examples
- Not waiting for human responses — you MUST stop and wait after each insight
- Stating obvious facts from the docs
- Being overly formal or academic
- Deferring document updates to the end
- In enhance mode: suggesting out-of-scope or tangential features
- **Forcing domain insights when there's nothing interesting to say about domains**
## Integration
Standalone utility — invoke whenever needed. No other commands depend on it.
Common moments to run it:
- After `/plan-1b` (spec) — surface implications of what we're building
- After `/plan-3` (plan) — discuss what we're about to implement
- Before `/plan-6` (implement) — clarify task interactions
- After implementation — understand what changed
