Design Exploration
Gather codebase context and explore design approaches before implementation. This skill bridges the gap between "we have an idea" and "we have a concrete direction" by grounding proposals in what actually exists in the codebase.
When this supports a task, use ../setup/references/task-context.md
to resolve the repository, linked task and applicable local instructions. Return findings to the
caller; the caller records them once in the task context instead of creating a parallel artifact.
When This Skill Runs
Typically invoked by /brainstorm or /nf, but can also run standalone when someone needs to understand how a feature fits into the existing architecture. The caller provides:
- Feature name and initial description
- Known constraints or requirements
- Specific areas to focus on (if known)
- The current goal: feature framing, design choice, or pre-implementation fit check
Process
Step 1: Parallel Context Gathering
Use references/exploration-checklist.md as a menu, selecting only the feature-type checklist
items that affect the caller's decision. Use one focused scan by default; fan out independent
angles only when broad coverage materially changes the decision and the host provides the worker.
Do not fan out to satisfy a fixed count. Use a faster model unless the task clearly needs deeper
reasoning.
Common scan angles:
- Closest prior art: similar features, modules, screens, services, or flows
- Core data or state model: entities, schemas, stores, contracts, or domain concepts
- Integration boundaries: APIs, shared utilities, routing, permissions, jobs, or external dependencies
- User-facing surface: routes, screens, components, or interactions, if the feature has UX implications
- Constraints and conventions: architecture rules, test patterns, shared abstractions, docs, and known limitations
Only go as deep as needed for the caller's goal. When invoked from /nf, prefer fit, viable options, constraints, and risks over implementation decomposition.
Step 2: Synthesize Findings
After agents return, compile a structured findings report:
## Codebase Findings
### Existing Patterns
- [Pattern name]: [Where it's used, how it works]
### Current Fit
- [Where this feature would likely belong or extend]
### Integration Points
- [Where new code connects to existing code]
### Constraints Discovered
- [Things the codebase enforces that the design must respect]
### Relevant Prior Art
- [Existing flow, screen, module, or service worth reusing or extending]
Step 3: Propose Approaches
Present 2-3 design approaches with trade-offs. Lead with your recommendation and explain why.
For each approach:
- What: Brief description (2-3 sentences)
- How it fits: Which existing patterns it follows
- Trade-offs: Pros and cons grounded in codebase evidence
- Effort signal: Relative complexity (low / medium / high)
- Risk signal: Key uncertainty, dependency, or downside to watch
Step 4: Incremental Design Summary
Once the user picks an approach (or you have a clear winner):
Present one compact, clearly labeled summary covering only the areas that materially affect the
caller's decision:
- Where the feature fits in the current product or architecture
- How the user flow or system flow would likely work
- Which data, state, or contracts are affected
- What constraints or dependencies shape the design
- What risks, open questions, or irreversible choices remain
- Implementation-heavy details only if they materially affect discovery or planning
Ask for revision only when a specific unresolved choice blocks the caller; otherwise return the
summary without an artificial continue loop.
When invoked from /nf, stop short of full tech decomposition. The goal is to clarify direction, not to write the implementation plan.
Output Contract
When this skill completes, it returns to the caller:
- Key codebase findings — existing patterns, current fit, integration points, and constraints discovered
- Design approaches — viable options, with a recommendation if one stands out
- Open questions — anything that still needs user judgment or further exploration
- Risk flags — issues, dependencies, or scope cautions that could affect direction
Key Principles
- Evidence-based: Every design recommendation references actual codebase patterns
- YAGNI: Each proposed approach should cover only what the caller's goal requires. If an approach adds abstraction beyond the stated goal, either drop it or label the extra clearly as "optional — not required by the brief."
- Follow existing conventions: New code should look like it belongs in the codebase
- Caller-sensitive depth: Tune depth to the caller's goal instead of always pushing into implementation detail
- Multiple choice preferred: Use
AskUserQuestion with options when clarifying
- Parallel exploration: Launch independent Explore scans simultaneously when fan-out is justified; keep narrow questions focused
1---2name: design-exploration3description: >-4 Explore codebase and design approaches before implementation. Use when asked5 'explore the design', 'how would this fit', 'design exploration', 'what patterns6 exist for', 'how is X implemented', or when another skill (brainstorm, nf) needs7 codebase context to ground a design proposal.8 NOT for code review (use /sr), NOT for static analysis (use /code-analysis).9allowed-tools:10 - Read11 - Glob12 - Grep13 - Agent14 - AskUserQuestion15metadata:16 source: https://skillmd.com/skills/alexandrbasis/design-exploration17---1819# Design Exploration2021Gather codebase context and explore design approaches before implementation. This skill bridges the gap between "we have an idea" and "we have a concrete direction" by grounding proposals in what actually exists in the codebase.2223When this supports a task, use [`../setup/references/task-context.md`](../setup/references/task-context.md)24to resolve the repository, linked task and applicable local instructions. Return findings to the25caller; the caller records them once in the task context instead of creating a parallel artifact.2627## When This Skill Runs2829Typically invoked by `/brainstorm` or `/nf`, but can also run standalone when someone needs to understand how a feature fits into the existing architecture. The caller provides:30- Feature name and initial description31- Known constraints or requirements32- Specific areas to focus on (if known)33- The current goal: feature framing, design choice, or pre-implementation fit check3435## Process3637### Step 1: Parallel Context Gathering3839Use `references/exploration-checklist.md` as a menu, selecting only the feature-type checklist40items that affect the caller's decision. Use one focused scan by default; fan out independent41angles only when broad coverage materially changes the decision and the host provides the worker.42Do not fan out to satisfy a fixed count. Use a faster model unless the task clearly needs deeper43reasoning.4445Common scan angles:461. **Closest prior art**: similar features, modules, screens, services, or flows472. **Core data or state model**: entities, schemas, stores, contracts, or domain concepts483. **Integration boundaries**: APIs, shared utilities, routing, permissions, jobs, or external dependencies494. **User-facing surface**: routes, screens, components, or interactions, if the feature has UX implications505. **Constraints and conventions**: architecture rules, test patterns, shared abstractions, docs, and known limitations5152Only go as deep as needed for the caller's goal. When invoked from `/nf`, prefer fit, viable options, constraints, and risks over implementation decomposition.5354### Step 2: Synthesize Findings5556After agents return, compile a structured findings report:5758```59## Codebase Findings6061### Existing Patterns62- [Pattern name]: [Where it's used, how it works]6364### Current Fit65- [Where this feature would likely belong or extend]6667### Integration Points68- [Where new code connects to existing code]6970### Constraints Discovered71- [Things the codebase enforces that the design must respect]7273### Relevant Prior Art74- [Existing flow, screen, module, or service worth reusing or extending]75```7677### Step 3: Propose Approaches7879Present **2-3 design approaches** with trade-offs. Lead with your recommendation and explain why.8081For each approach:82- **What**: Brief description (2-3 sentences)83- **How it fits**: Which existing patterns it follows84- **Trade-offs**: Pros and cons grounded in codebase evidence85- **Effort signal**: Relative complexity (low / medium / high)86- **Risk signal**: Key uncertainty, dependency, or downside to watch8788### Step 4: Incremental Design Summary8990Once the user picks an approach (or you have a clear winner):9192Present one compact, clearly labeled summary covering only the areas that materially affect the93caller's decision:94 - Where the feature fits in the current product or architecture95 - How the user flow or system flow would likely work96 - Which data, state, or contracts are affected97 - What constraints or dependencies shape the design98 - What risks, open questions, or irreversible choices remain99 - Implementation-heavy details only if they materially affect discovery or planning100101Ask for revision only when a specific unresolved choice blocks the caller; otherwise return the102summary without an artificial continue loop.103104When invoked from `/nf`, stop short of full tech decomposition. The goal is to clarify direction, not to write the implementation plan.105106## Output Contract107108When this skill completes, it returns to the caller:1091101. **Key codebase findings** — existing patterns, current fit, integration points, and constraints discovered1112. **Design approaches** — viable options, with a recommendation if one stands out1123. **Open questions** — anything that still needs user judgment or further exploration1134. **Risk flags** — issues, dependencies, or scope cautions that could affect direction114115## Key Principles116117- **Evidence-based**: Every design recommendation references actual codebase patterns118- **YAGNI**: Each proposed approach should cover only what the caller's goal requires. If an approach adds abstraction beyond the stated goal, either drop it or label the extra clearly as "optional — not required by the brief."119- **Follow existing conventions**: New code should look like it belongs in the codebase120- **Caller-sensitive depth**: Tune depth to the caller's goal instead of always pushing into implementation detail121- **Multiple choice preferred**: Use `AskUserQuestion` with options when clarifying122- **Parallel exploration**: Launch independent Explore scans simultaneously when fan-out is justified; keep narrow questions focused