---
name: design-proposal
description: Creates a design proposal before coding starts. Defines components, interfaces, coupling decisions, and test approach — forces architectural thinking before the first line of code.
metadata:
  author: janmarkuslanger
  version: "1.0"
---

# Design Proposal

When this skill is activated, produce a `DESIGN.md` file that captures the architectural design for a feature or module *before* implementation begins. The goal is to make coupling decisions, interface contracts, and testability explicit upfront.

## Clarifying Questions

Before writing the design, ask the engineer the following questions. Skip any already clearly answered in the conversation. **Wait for the answers before proceeding.**

1. What exactly needs to be built? Describe the feature in one or two sentences — what problem does it solve for whom?
2. Which parts of the existing codebase must this feature integrate with or extend?
3. Are there functional constraints — required APIs, protocols, data formats, or interfaces that must be respected?
4. Are there non-functional requirements — performance targets, security requirements, scalability expectations?
5. Are there any solutions or approaches already ruled out? Why were they rejected?
6. What does "done" look like — how will this feature be verified to work correctly?
7. What are the open questions or risks you're already aware of before design starts?

## Steps

1. Use the answers above as the basis for the design; supplement with exploration of the existing codebase
2. Explore the existing codebase to understand the current architecture, naming conventions, and module boundaries
3. Identify which components need to be created or modified
4. Define clear interface contracts between components
5. Reason explicitly about coupling: what is intentionally coupled, what must remain decoupled, and why
6. Define the test approach per component before any code exists

## Output

Write a file called `DESIGN.md` in the project root (or feature folder if more appropriate) with the following sections:

### 1. Problem Statement
One short paragraph: what needs to be built and why. No implementation details yet.

### 2. Components
For each new or significantly modified component:
- **Name** and proposed location
- **Single Responsibility**: one sentence describing exactly what this component does — nothing more
- **Public Interface**: the methods, functions, events, or APIs this component exposes. Use pseudocode or the actual language syntax.
- **Dependencies**: what this component depends on (other components, external services, infrastructure)

Include a Mermaid diagram showing all components and their relationships:

```mermaid
graph TD
    A[ComponentA] -->|uses| B[ComponentB]
    A -->|calls| C[ExternalService]
```

### 3. Coupling Decisions
A table documenting every significant coupling in this design:

| From | To | Type | Intentional? | Rationale |
|------|----|------|-------------|-----------|
| ComponentA | ComponentB | direct call | yes | same bounded context, stable interface |
| ComponentA | Database | via interface | yes | testability — allows in-memory stub |

**Types**: `direct call`, `event`, `shared data`, `via interface`, `via DI container`

### 4. Interface Contracts
For every interface or abstract boundary, define:
- The contract (method signatures, event shapes, data types)
- What the consumer can rely on
- What the producer is free to change without breaking the consumer

### 5. Test Approach
For each component, define:
- **Unit test scope**: what can be tested in isolation and how (what gets stubbed)
- **Integration test scope**: which couplings need to be tested end-to-end
- **What NOT to test**: explicitly name things that are not worth testing here

### 6. Open Questions
Unresolved decisions or risks that must be answered before or during implementation.

## Rules

- Write this document *before* implementation — it is a thinking tool, not post-hoc documentation
- Be explicit about trade-offs; "we could do X but chose Y because Z" is more valuable than just stating the decision
- Interfaces must be concrete enough that two engineers could implement both sides independently
- If a coupling cannot be justified, it should be removed from the design
- Keep it short enough to read in 10 minutes — this is a briefing, not a spec