Dagger Design Proposals

Guidelines for writing design proposals for Dagger features.

Before Writing

Always research first:

1. Check existing skills (dagger-codegen, cache-expert, etc.) for relevant context
2. Look at related code in the Dagger codebase:
   • GraphQL schema: core/schema/*.go
   • CLI commands: cmd/dagger/*.go
   • Core types: core/*.go
3. Understand existing patterns before proposing new ones

Structure

# Part N: Title

*Builds on [Part N-1: Title](link)*

## Table of Contents
- [Problem](#problem)
- [Solution](#solution)
- [Core Concept](#core-concept)
- [CLI](#cli)
- [Status](#status)

## Problem

Numbered, concise limitations:

1. **Short title** - One sentence explanation.
2. **Short title** - One sentence explanation.

## Solution

One paragraph summary.

## Core Concept

GraphQL type definitions with inline docstrings:

```graphql
"""
Type description here.
"""
type Example {
  """Method description."""
  method(arg: String!): Result!
}

Go for implementation examples:

func New(ws dagger.Workspace) *Example {
    // ...
}

CLI

Real command examples:

$ dagger command --flag
OUTPUT

Status

One line.

• Previous: Part N-1
• Next: Part N+1 or “Part N+1: Title (coming soon)”

## Style

- **Concise** - Trust the reader. Remove fluff.
- **Tables** - Use for comparisons.
- **GraphQL for APIs** - Type definitions, not Go interfaces.
- **Go for implementation** - Examples showing how modules use the API.
- **Real examples** - go-toolchain, node-toolchain, not abstract Foo/Bar.
- **Less is more** - Remove sections when challenged.

## What to Avoid

- Separate "Methods" sections (use GraphQL docstrings)
- "Design Rationale" sections unless specifically valuable
- "Open Questions" that aren't real blockers
- Go for type definitions (use GraphQL)
- Layout examples that might confuse
- Over-explaining

## Process

1. **Gists as source of truth** - Publish early, iterate in gist
2. **Link parts together** - Previous/Next at bottom, "Builds on" at top
3. **Each part stands alone** - But builds on previous
4. **Iterate quickly** - User feedback drives changes

## Iterating with User

When you have clarifying questions or notes:
1. **List them first** - Present a high-level numbered list of all questions/notes
2. **One at a time** - Walk through each item individually, waiting for user response
3. **Don't dump** - Never present all questions with full details at once

## Codebase References

When writing proposals, reference actual Dagger code:

| Topic | Location |
|-------|----------|
| GraphQL schema definitions | `core/schema/*.go` |
| CLI commands | `cmd/dagger/*.go` |
| Core types (Directory, File, etc.) | `core/*.go` |
| Engine internals | `engine/*.go` |
| SDK codegen | `cmd/codegen/*.go` |

Example: To understand how `Host.findUp` works before proposing `Workspace.findUp`:
```bash
# Find the schema definition
grep -r "findUp" core/schema/host.go

# Find the implementation
grep -r "FindUp" core/host.go

Publishing

# Create new gist
gh gist create file.md --desc "Dagger Design: Part N - Title" --public

# Update existing gist
gh gist edit GIST_ID file.md

# Post changelog comment (always do this after updates)
gh api --method POST /gists/GIST_ID/comments -f body="## Changelog
- Change 1
- Change 2"

Always post a changelog comment after updating a gist with significant changes.

Related Skills

Check for other Dagger skills that may help with research:

• dagger-codegen – SDK codegen, templates, bindings
• cache-expert – Caching internals, invalidation