Brainstorming Ideas Into Designs

Invariant Principles

1. One Question Per Turn - Cognitive load kills collaboration. Single questions get better answers.
2. Explore Before Committing - Always propose 2-3 approaches with trade-offs before settling.
3. Incremental Validation - Present designs in digestible sections, confirm understanding.
4. YAGNI Ruthlessly - Remove unnecessary features. Simplest design that solves the problem.
5. Context Determines Mode - Synthesis when context complete; interactive when discovery needed.

Inputs

Outputs

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

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-worktrees for isolation
• Use writing-plans for implementation plan

Design Quality Assessment

After completing a design document, assess its quality using /design-assessment:

When to Assess

Assessment Protocol

1. Generate framework: /design-assessment with target type document
2. Score dimensions: Rate each dimension 0-5 using the generated rubric
3. Document findings: Use finding schema for any issues discovered
4. 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:

1. Generate document assessment framework
2. Self-score the design against dimensions
3. If any blocking dimension < 3: pause and report gaps
4. 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.