design-delta

What this skill does

# Delta Design Workflow

Write design rationale for a specific delta.

## Input

Delta ID: $ARGUMENTS (e.g., "DLT-001")

## Context

**You must load the following skills and read the following files before proceeding.**

### Skills
- `katachi:framework-core` - Workflow principles
- `katachi:working-on-delta` - Per-feature workflow
- `katachi:research-docs` - Mandatory workflow for fetching current documentation

### Delta inventory
- `docs/planning/DELTAS.md` - Delta definitions

### Delta spec
- `docs/delta-specs/$ARGUMENTS.md` - The specification we're designing for

### Project decisions
- `docs/architecture/README.md` - Architecture decisions (ADRs)
- `docs/design/README.md` - Design patterns (DES)

### Existing design (if present)
- `docs/delta-designs/$ARGUMENTS.md` - Current design to update or create

### Feature documentation (for context and impact discovery)
- `docs/feature-designs/README.md` - Feature design index
- `docs/feature-designs/` - Existing feature designs (read specific docs as needed)
- `docs/feature-specs/README.md` - Feature capability index (for understanding features)
- Reference existing feature designs to understand current architecture
- Use existing design patterns and decisions from feature docs

### Templates and Guides
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/delta-design.md` - Structure to follow
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/wireframing.md` - UI layout guide (if needed)
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/spike-template.md` - Spike investigation template (for shape unknowns)
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/technical-diagrams.md` - Technical diagram guidance
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/code-examples.md` - Code snippet guidance

## Pre-Check

Verify spec exists:
- If `docs/delta-specs/$ARGUMENTS.md` doesn't exist, suggest running `/katachi:spec-delta $ARGUMENTS` first
- Design requires a spec to design against

## Process

### 1. Check Existing State

If `docs/delta-designs/$ARGUMENTS.md` exists:
- Read current design
- **Check if this is a shape-only seed from spec phase:** If the design doc contains only a `## Shape` section with initial shape parts and the rest of the template sections are empty, treat it as a starting point — not an existing design to iterate on. Summarize the initial shape to the user, note any flagged unknowns (⚠️), and proceed with full design creation.
- **Otherwise (existing design with content):** Check for drift against spec, summarize design approach, key decisions, modeling choices. Ask: "What aspects need refinement? Or should we review the whole design?" Enter iteration mode as appropriate.

If no design exists: proceed with initial creation

Update status:
```bash
python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "⧗ Design"
```

### 2. Research Phase (Silent)

**Internal Research:**
- Read delta spec (`docs/delta-specs/$ARGUMENTS.md`)
- Read dependency specs if they exist
- Read relevant ADRs from index
- Read relevant DES patterns from index
- Explore related codebase areas if needed
- **Check if spec has User Flow section:**
  - If YES: Identify which places (screens) need wireframes
  - If NO: Check if UI component layer exists in design
  - Note which UI elements need wireframe documentation

**External Research (Mandatory — No Exceptions):**

Your training data is outdated. Current documentation is always more accurate. This step is not optional even when you feel confident about a library.

For each library, framework, or technical approach identified in the spec:

1. **Search current documentation** for ALL libraries/frameworks involved, following the `katachi:research-docs` skill guidance:
   - Search for specific topics/features and the patterns you need
   - Get current API signatures, recommended patterns, version-specific guidance
   - Check for deprecation notices or migration guides
   - Search even for libraries you have used before in this session

2. **Research alternative approaches** using WebSearch:
   - Query: "[problem domain] best practices [current year]"
   - Query: "[library name] vs alternatives [current year]"
   - Look for recent blog posts, conference talks, or official recommendations

3. **Research available up-to-date options**:
   - Search for current solutions to the problem domain (not just the library you know)
   - Query: "[problem we're solving] modern solution [current year]"
   - Discover options you might not have considered from training data
   - Compare approaches: performance, maintenance status, community adoption, compatibility

**Research must answer:**
- What are the current best solutions for this problem? (not just the ones we already know)
- Which options are actively maintained and recommended?
- What are the recommended patterns for our use case per current documentation?
- What alternatives exist and why should we prefer one over another?
- Are there newer, better approaches than what training data suggests?

**Enforcement:** If your design involves ANY external library and you performed zero documentation searches, you have violated this workflow. Stop and follow the `katachi:research-docs` guidance before continuing.

Build complete understanding without asking questions, but do not proceed to design until external research is complete.

### 3. User Interview

Now that I've researched the spec, existing patterns, and current documentation, I'll present my design thinking and ask about important decisions.

**Present your design understanding:**

Briefly summarize:
- Your initial design approach based on research
- Key architectural decisions you're leaning toward
- Technology/library options you've discovered and your initial assessment
- Areas where multiple valid approaches exist
- Any uncertainties or assumptions from the spec

**Identify and ask about important decisions:**

Use AskUserQuestion to ask focused questions about:

- **Architectural approach choices:**
  - "Based on current research, should we use [approach A] or [approach B]?"
  - Each option should describe the trade-offs clearly (complexity vs flexibility, etc.)

- **Technology/library selections:**
  - "For [problem area], current research shows [option A] and [option B] - which should we prefer?"
  - Include key differences from your research (maintenance status, community adoption, etc.)

- **Design trade-offs:**
  - "Should we prioritize [quality A] or [quality B]?"
  - Present options with clear implications (e.g., "performance" vs "simplicity of implementation")

- **Uncertainties from spec:**
  - "The spec mentions [ambiguous requirement] - how should this be handled?"
  - Present design options that address different interpretations

- **Integration with existing patterns:**
  - "This could follow [existing pattern X] or use [new pattern Y] - which is better?"
  - Reference specific ADRs or DES from your research

**Guidelines for effective questions:**
- Keep questions high-level and targeted toward important decisions
- Base questions on your external research findings (documentation, search results)
- Ask only about decisions that significantly affect the design direction
- Each question should present 2-4 specific options with clear trade-offs
- Include "Other" option automatically for user-provided alternatives
- Avoid asking about trivial implementation details - focus on architectural and strategic decisions
- Don't re-validate spec decisions unless they impact design approach
- Don't overwhelm - focus on the decisions that truly need user input

**After the interview:**
- Incorporate user's preferences into your design approach
- Note any areas where user deferred decisions
- Proceed to impact discovery with clarified design direction

### 4. Impact Discovery (Silent)

**Auto-discover affected feature designs by:**

1. **Read delta spec** - identify affected features from "Detected Impacts" sec