diff --git a/.beads/formulas/design.formula.toml b/.beads/formulas/design.formula.toml new file mode 100644 index 00000000..8dd4a595 --- /dev/null +++ b/.beads/formulas/design.formula.toml @@ -0,0 +1,333 @@ +# Design Convoy Formula +# +# A convoy-style formula that spawns multiple polecats in parallel, +# each exploring a different dimension of a design problem. Results +# are synthesized into a unified design document. +# +# Usage: +# gt formula run design --problem="Add notification levels to mayor" +# gt formula run design --problem="Redesign the merge queue" + +description = """ +Structured design exploration via parallel specialized analysts. + +Each leg examines the design problem from a different perspective. Findings +are collected and synthesized into a unified design proposal with options. + +## Legs (parallel execution) +- **api**: Interface design, ergonomics, developer experience +- **data**: Data model, storage, migrations, schema +- **ux**: User experience, CLI ergonomics, discoverability +- **scale**: Performance at scale, bottlenecks, limits +- **security**: Threat model, attack surface, trust boundaries +- **integration**: How it fits existing system, compatibility + +## Execution Model +1. Each leg spawns as a separate polecat +2. Polecats work in parallel +3. Each writes analysis to their designated output +4. Synthesis step combines all analyses into unified design + +## Output +A .designs// directory containing: +- Individual dimension analyses +- design-doc.md with unified proposal and decision points +""" +formula = "design" +type = "convoy" +version = 1 + +# Input variables - provided at runtime +[inputs] +[inputs.problem] +description = "Problem statement or feature request to design" +type = "string" +required = true + +[inputs.context] +description = "Additional context (existing code, constraints, etc.)" +type = "string" +required = false + +[inputs.scope] +description = "Scope hint: 'small' (1 file), 'medium' (package), 'large' (system)" +type = "string" +default = "medium" + +# Base prompt template - injected into all leg prompts +[prompts] +base = """ +# Design Analysis Assignment + +You are a specialized design analyst participating in a convoy design exploration. + +## Context +- **Formula**: {{.formula_name}} +- **Problem**: {{.problem}} +- **Your dimension**: {{.leg.focus}} +- **Leg ID**: {{.leg.id}} +- **Scope**: {{.scope}} + +{{if .context}} +## Additional Context +{{.context}} +{{end}} + +## Your Task +{{.leg.description}} + +## Output Requirements +Write your analysis to: **{{.output_path}}** + +Structure your output as follows: +```markdown +# {{.leg.title}} + +## Summary +(1-2 paragraph overview of this dimension) + +## Analysis + +### Key Considerations +(Bulleted list of important factors) + +### Options Explored +(For each option considered:) +#### Option N: +- **Description**: What is it? +- **Pros**: Benefits +- **Cons**: Drawbacks +- **Effort**: Low/Medium/High + +### Recommendation +(Your recommended approach for this dimension) + +## Constraints Identified +(Hard constraints discovered during analysis) + +## Open Questions +(Questions needing human input or cross-dimension discussion) + +## Integration Points +(How this dimension connects to other dimensions) +``` + +Be thorough but actionable. Flag decisions needing human input. +""" + +# Output configuration +[output] +directory = ".designs/{{.design_id}}" +leg_pattern = "{{.leg.id}}.md" +synthesis = "design-doc.md" + +# Leg definitions - each spawns a parallel polecat +[[legs]] +id = "api" +title = "API & Interface Design" +focus = "Interface design and developer ergonomics" +description = """ +Analyze the interface design for this feature. + +**Explore:** +- Command-line interface: flags, subcommands, ergonomics +- Programmatic API: function signatures, return types +- Configuration interface: files, environment variables +- Error messages and help text +- Naming conventions and discoverability +- Consistency with existing interfaces + +**Questions to answer:** +- How will users discover and learn this feature? +- What's the happy path vs edge cases? +- Does it follow existing CLI/API patterns? +- What would make this a joy to use? + +**Deliverable:** api-design.md with interface proposals +""" + +[[legs]] +id = "data" +title = "Data Model Design" +focus = "Data model, storage, and migrations" +description = """ +Analyze the data model requirements for this feature. + +**Explore:** +- Data structures: types, relationships, constraints +- Storage format: JSON, TOML, SQLite, in-memory +- Schema design: fields, indices, normalization +- Migration strategy: versioning, backwards compatibility +- Data lifecycle: creation, updates, deletion +- Persistence vs ephemeral considerations + +**Questions to answer:** +- What data needs to persist vs be computed? +- How will the data grow over time? +- What queries/access patterns are needed? +- How do we handle schema evolution? + +**Deliverable:** data-model.md with schema proposals +""" + +[[legs]] +id = "ux" +title = "User Experience Analysis" +focus = "User experience and CLI ergonomics" +description = """ +Analyze the user experience implications of this feature. + +**Explore:** +- Mental model: how users think about this +- Workflow integration: where does this fit in daily use? +- Learning curve: progressive disclosure +- Error experience: what happens when things go wrong? +- Feedback: how does the user know it's working? +- Discoverability: --help, docs, examples + +**Questions to answer:** +- What's the user's goal when using this? +- What's the minimum viable interaction? +- How do we handle power users vs beginners? +- What would surprise or confuse users? + +**Deliverable:** ux-analysis.md with UX recommendations +""" + +[[legs]] +id = "scale" +title = "Scalability Analysis" +focus = "Performance at scale and bottlenecks" +description = """ +Analyze the scalability implications of this feature. + +**Explore:** +- Scale dimensions: data size, request rate, user count +- Resource usage: memory, CPU, disk, network +- Bottlenecks: what limits growth? +- Complexity: algorithmic, space, time +- Caching opportunities +- Degradation modes: what happens at limits? + +**Questions to answer:** +- What happens at 10x, 100x, 1000x current scale? +- What are the hard limits? +- Where should we optimize vs keep simple? +- What needs to be lazy vs eager? + +**Deliverable:** scalability.md with performance analysis +""" + +[[legs]] +id = "security" +title = "Security Analysis" +focus = "Threat model and attack surface" +description = """ +Analyze the security implications of this feature. + +**Explore:** +- Trust boundaries: what trusts what? +- Attack surface: new inputs, outputs, permissions +- Threat model: who might attack this and how? +- Sensitive data: what's exposed or stored? +- Authentication/authorization implications +- Failure modes: what if security fails? + +**Questions to answer:** +- What's the worst case if this is exploited? +- What new permissions or access does this need? +- How do we validate/sanitize inputs? +- Are there defense-in-depth opportunities? + +**Deliverable:** security.md with threat analysis +""" + +[[legs]] +id = "integration" +title = "Integration Analysis" +focus = "How it fits existing system" +description = """ +Analyze how this feature integrates with the existing system. + +**Explore:** +- Existing components: what does this touch? +- Dependencies: what does this need from others? +- Dependents: what will depend on this? +- Migration path: how do we get from here to there? +- Backwards compatibility: what might break? +- Testing strategy: how do we verify integration? + +**Questions to answer:** +- Where does this code live? +- How does it affect existing workflows? +- What needs to change in dependent code? +- Can we feature-flag or gradually roll out? + +**Deliverable:** integration.md with integration plan +""" + +# Synthesis step - combines all leg outputs +[synthesis] +title = "Design Synthesis" +description = """ +Combine all dimension analyses into a unified design document. + +**Your input:** +All dimension analyses from: {{.output.directory}}/ + +**Your output:** +A synthesized design at: {{.output.directory}}/{{.output.synthesis}} + +**Structure:** +```markdown +# Design: {{.problem}} + +## Executive Summary +(2-3 paragraph overview of proposed design) + +## Problem Statement +(Clear statement of what we're solving) + +## Proposed Design + +### Overview +(High-level approach) + +### Key Components +(Main pieces and how they fit together) + +### Interface +(CLI/API summary from api dimension) + +### Data Model +(Schema summary from data dimension) + +## Trade-offs and Decisions + +### Decisions Made +(Key choices and rationale) + +### Open Questions +(Decisions needing human input - highlight these!) + +### Trade-offs +(What we're trading off and why) + +## Risks and Mitigations +(From security and scale dimensions) + +## Implementation Plan +(From integration dimension) + +### Phase 1: MVP +### Phase 2: Polish +### Phase 3: Future + +## Appendix: Dimension Analyses +(Links to full dimension documents) +``` + +Identify conflicts between dimensions. Flag decisions needing human input. +Be concrete and actionable. +""" +depends_on = ["api", "data", "ux", "scale", "security", "integration"]