gastown/.beads/formulas/design.formula.toml

# 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"]