majiayu000 Brainstorming Ideas Into Designs
Invariant Principles
- One Question Per Turn - Cognitive load kills collaboration. Single questions get better answers.
- Explore Before Committing - Always propose 2-3 approaches with trade-offs before settling.
- Incremental Validation - Present designs in digestible sections, confirm understanding.
- YAGNI Ruthlessly - Remove unnecessary features. Simplest design that solves the problem.
- Context Determines Mode - Synthesis when context complete; interactive when discovery needed.
Inputs
| Input | Required | Description |
|---|---|---|
context.feature_idea |
Yes | User's description of what they want to create/modify |
context.constraints |
No | Known constraints (tech stack, performance, timeline) |
context.existing_patterns |
No | Patterns from codebase research |
context.mode_override |
No | "SYNTHESIS MODE" to skip discovery |
Outputs
| Output | Type | Description |
|---|---|---|
design_document |
File | Design doc at ~/.local/spellbook/docs/<project>/plans/YYYY-MM-DD-<topic>-design.md |
approach_decision |
Inline | Selected approach with rationale for alternatives considered |
implementation_ready |
Boolean | Whether design is complete enough to proceed |
Mode Detection
Synthesis mode active when context contains:
- "SYNTHESIS MODE" / "Mode: AUTONOMOUS" / "DO NOT ask questions"
- "Pre-Collected Discovery Context" or "design_context"
- Comprehensive architectural decisions, scope boundaries, success criteria already defined
| Mode | Behavior |
|---|---|
| Synthesis | Skip discovery. Make autonomous decisions. Document rationale. Write complete design. |
| Interactive | Ask questions one at a time. Validate incrementally. Collaborate. |
Synthesis Mode Protocol
Skip: Questions about purpose/constraints/criteria, "Which approach?", "Does this look right?", "Ready for implementation?"
Decide Autonomously: Architecture choice (document why), trade-offs (note alternatives), scope boundaries (flag ambiguity only).
Circuit Breakers (still pause):
- Security-critical decisions with no guidance
- Contradictory requirements irreconcilable
- Missing context making design impossible
Interactive Mode Protocol
Discovery Phase:
- Check project state (files, docs, commits)
- Explore subagent for codebase patterns (saves main context)
- One question per message. Prefer multiple choice.
- Focus: purpose, constraints, success criteria
Approach Selection:
- Propose 2-3 approaches with trade-offs
- Lead with recommendation and reasoning
Fractal exploration (optional): When 2+ approaches have non-obvious trade-offs, invoke fractal-thinking with intensity pulse and seed: "What are the deep trade-offs between [approaches] for [feature]?". Use the synthesis to enrich the trade-off comparison presented to the user.
Design Presentation:
- 200-300 word sections
- Validate after each section
- Cover: architecture, components, data flow, error handling, testing
After Design Complete
Documentation:
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
PROJECT_ENCODED=$(echo "$PROJECT_ROOT" | sed 's|^/||' | tr '/' '-')
mkdir -p ~/.local/spellbook/docs/$PROJECT_ENCODED/plans
# Write to: ~/.local/spellbook/docs/$PROJECT_ENCODED/plans/YYYY-MM-DD-<topic>-design.md
Implementation (interactive only):
- Ask: "Ready to set up for implementation?"
- Use
using-git-worktreesfor isolation - Use
writing-plansfor implementation plan
Design Quality Assessment
After completing a design document, assess its quality using /design-assessment:
When to Assess
| Scenario | Action |
|---|---|
| Design for evaluative skill/command | Run /design-assessment --mode=autonomous to generate framework for the design |
| Complex design with multiple stakeholders | Run assessment to validate completeness |
| Design review requested | Use assessment dimensions as review criteria |
Assessment Protocol
- Generate framework:
/design-assessmentwith target typedocument - Score dimensions: Rate each dimension 0-5 using the generated rubric
- Document findings: Use finding schema for any issues discovered
- Determine verdict: Apply verdict logic to decide if design is ready
Quality Gate
Design is ready for implementation when:
- All blocking dimensions (completeness, clarity, accuracy) score >= 3
- No CRITICAL or HIGH findings
- Verdict is READY
Integration with Synthesis Mode
In synthesis mode, run assessment autonomously:
- Generate document assessment framework
- Self-score the design against dimensions
- If any blocking dimension < 3: pause and report gaps
- If verdict is NOT_READY or NEEDS_WORK: report gaps to user and iterate on design before proceeding
Error Handling
If /design-assessment fails (command not found, execution error, timeout):
- Warn user: "Design assessment unavailable, proceeding without quality gate"
- Continue to implementation planning (degraded mode)
- Log the failure for debugging
Self-Check
Before completing:
- Presented 2-3 approaches with trade-offs before selecting
- Design doc written to correct external location (not project dir)
- All sections covered: architecture, components, data flow, error handling, testing
- No YAGNI violations (unnecessary complexity removed)
- Mode correctly detected (synthesis vs interactive)
If ANY unchecked: STOP and fix.