to-design skill

gistfile1.txt

---
name: to-design
description: Turn a PRD, plan, or feature conversation into an implementation-ready software design focused on deep modules, clear seams, and testable interfaces. Use between `to-prd` and `to-issues`, or when the user asks for software, architecture, technical, or implementation design.
---

# To Design

Create the technical design that `to-issues` can later slice. Do not draft the
issue breakdown here.

Prefer commenting on the source GitHub issue when one exists. Otherwise, output
the design in chat. Do not create a new issue unless asked.

## Inputs

- Use the current conversation.
- If the user provides an issue, URL, or file path, read it first and remember
  where the finished design should go.
- Read domain docs and ADRs. Use project vocabulary and respect documented
  decisions unless there is real friction worth reopening.
- Read `../improve-codebase-architecture/LANGUAGE.md` and use these terms
  exactly: **module**, **interface**, **seam**, **adapter**, **depth**,
  **leverage**, and **locality**.

## Process

1. Summarize the user-facing problem, desired behavior, and implementation
   constraints. Explore discoverable answers before asking the user.
2. Map current modules, interfaces, seams, adapters, data models, workflows,
   and tests.
3. Look for architecture friction: shallow modules, poor locality, weak test
   seams, cross-layer coupling, and ADR/domain constraints.
4. Apply the deletion test to suspected shallow modules: if deleting it spreads
   complexity to callers, it is probably earning its keep; if complexity
   vanishes, it is pass-through indirection.
5. Choose a design that puts meaningful behavior behind a small stable
   interface, makes that interface the test surface, and concentrates change in
   the module that owns the domain concept.
6. Add seams only when behavior genuinely varies across adapters.
7. If multiple interfaces are plausible, design two, compare by depth,
   locality, seam placement, dependency strategy, and vertical slicing, then
   recommend one.
8. Classify dependencies using
   `../improve-codebase-architecture/DEEPENING.md`: in-process,
   local-substitutable, remote but owned, or true external.

Ask only for decisions that cannot be discovered and materially change the
design.

## Artifact

```md
## Software Design

### Goal

What this design enables, in user/domain terms.

### Current Shape

The relevant current modules, interfaces, seams, adapters, and tests.

### Proposed Shape

The modules to create or change. For each important module, describe its
interface, what the implementation hides, and why the module is deep enough.

### Refactoring First

Any refactoring that should happen before feature implementation. Say "None" if
implementation can proceed directly.

### Data and Workflow Changes

Schema, persistence, async workflow, routing, or integration changes that affect
the design.

### Testing Strategy

Tests at module interfaces, including old tests to replace or delete if they
would test past the new interface.

### Issue Breakdown Guidance

Architectural constraints, likely dependency order, and work that probably
needs human review. Do not enumerate final issue slices.

### Open Questions

Only unresolved questions that block issue breakdown or implementation.
```

Avoid file-path-heavy instructions. Include paths only when they clarify
ownership or prior art.

If you comment on a GitHub issue, include a short link/reference in chat. After
publishing, ask whether the design is approved for `to-issues`; if not,
iterate, and if yes, hand off to `to-issues`.