| name | brainstorming |
| description | MANDATORY architectural and intent alignment phase. Must be executed before any code generation, feature modification, or stack scaffolding. Resolves constraints, map semantic contexts, and secures design approval. |
Agentic Brainstorming & Architecture Design (2027 Workflow)
Bridge the gap between raw intent and high-performance execution. This skill maps project constraints, prevents architectural drift, and ensures total alignment before a single line of code is written.
Do NOT invoke any implementation skill, write functional code, scaffold files, or execute state changes until the technical architecture is explicitly approved by the user. The ONLY valid transition from this state is to the implementation planning phase (`writing-plans`).
The 2027 Anti-Pattern: "Context Blindness"
Assuming a feature is too simple for a design doc is why codebases rot. In automated and AI-assisted repositories, minor unvetted assumptions break semantic indexes, corrupt component boundaries, and cause infinite loops of code refactoring. Every structural change requires a fast, high-density alignment cycle.
Core Checklist
Execute these phases sequentially. Do not skip steps:
- Context & Semantic Analysis — Deep dive into active code graphs, MCP tools, configuration scopes, and active project rules.
- Dynamic UI/UX Evaluation — Assess if the feature dictates visual interaction (Generative UI, component layouts). If yes, offer the interactive visual companion immediately as a standalone option.
- High-Density Clarification — Ask precise, high-signal questions. Group options into structured multiple-choice matrices rather than loose text loops to save token context.
- Multi-Architecture Trade-offs — Present 2-3 technical approaches (e.g., edge vs. centralized, native vs. polymorphic components) highlighting performance, complexity, and scalable boundaries.
- Incremental Specification — Present the system architecture in isolated, logical blocks (Data Flow, API Contracts, State, Error Boundaries).
- Spec File Generation & Commit — Write the approved architecture directly to
docs/specs/YYYY-MM-DD-<topic>-design.md.
- Automated Spec Review — Scan the final document for placeholders, structural contradictions, or coupling leaks before handoff.
Architectural Guidelines for AI-Native Environments
Extreme Isolation & Loose Coupling
- Design components and modules as black boxes with deterministic inputs/outputs.
- If a file or component requires an LLM to hold more than 400 lines of active code in context to understand its side effects, reject the architecture and decompose it.
- Explicitly define boundaries so that subsequent autonomous agent runs can edit internal logic without cascading breaks across the codebase.
Working with Modern Stacks
- Standardize on native platform capabilities first (native Web APIs, Container Queries, native state isolation).
- Avoid proposing external architectural dependencies unless absolutely required by performance limits.
- Integrate smoothly with existing code patterns. If an existing architecture is flawed and impacts the task, include a targeted, scoped refactoring step within the proposal.
The Visual Companion Protocol
When a task involves interface layout, generative UI modules, or complex spatial flows, isolate the visual proposal:
"Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
Note: This prompt must be sent standalone, clean of other technical text, allowing the user to opt-in or continue via terminal constraints.
Transition to Execution
Once the architecture is fully approved:
- Write and save the specification file.
- Run the spec review checklist to purge any "TODO" or "TBD" tags.
- Invoke the
writing-plans skill. Do not slide into implementation, file writing, or style tasks here. Handoff is strict.
