feat(formula): Add design convoy formula for structured exploration
Creates a convoy-style formula for structured design exploration with 6 parallel legs: - api: Interface design, developer ergonomics - data: Data model, storage, migrations - ux: User experience, CLI ergonomics - scale: Performance at scale, bottlenecks - security: Threat model, attack surface - integration: System integration, compatibility Each leg spawns a polecat that analyzes the design problem from its dimension. The synthesis step combines all analyses into a unified design document with options and decision points. Usage: gt formula run design --problem="Add notification levels to mayor" (gt-ubqeg.2) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
gastown/polecats/nux
committed by
Steve Yegge
Steve Yegge
parent
a6ae2c6116
commit
57cd8b887d
333
.beads/formulas/design.formula.toml
Normal file
333
.beads/formulas/design.formula.toml
Normal file
@@ -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/<design-id>/ 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: <name>
|
||||
- **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"]
|
||||
Reference in New Issue
Block a user