design-delta

# 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" section 2. **Search feature-designs/** - find related design documentation: - For each feature path identified in spec - Grep for overlapping design concepts or components 3. **Determine design impact type**: - **Adds**: Creates new components or patterns within domain - **Modifies**: Changes existing design approach documented in feature - **Removes**: Deprecates or removes documented patterns 4. **Note impacts** for later inclusion in "Detected Impacts" section ### 5. Draft Complete Design (with Decision Points) **Evolve the shape:** If a design doc with initial shape parts exists (seeded by spec-delta): - Read the initial shape parts table - For any flagged parts (⚠️): dispatch `katachi:spike-runner` subagent(s) to investigate, then validate findings with the user - Spikes may surface new requirements — if so, update the spec's R table and AC in `docs/delta-specs/$ARGUMENTS.md` before continuing - Resolve unknowns: remove ⚠️ and update mechanism descriptions based on findings - Evolve shape parts into more detailed mechanisms informed by research If no initial shape exists: draft shape parts from scratch based on spec requirements. The shape parts table stays in the design as a permanent section — it is not removed after evolution. **Run requirements coverage check (internal, not saved):** Verify coverage between the spec's R table and the evolved shape: - Every requirement should have at least one shape part addressing it - Every shape part should trace to at least one requirement - Surface gaps to the user if found **Present evolved shape to user for validation:** After evolving the shape and resolving unknowns, present the complete evolved shape to the user before investing effort in the full design: - Show the full updated shape parts table - Highlight what changed from the initial shape (seeded by spec phase): new parts added, parts refined or split, unknowns resolved, coverage gaps addressed - Show the updated R→Shape coverage mapping - Invite feedback: "Here's the evolved shape after research and spike resolution. Does this still capture the right approach? Any mechanisms to adjust before I build the full design around it?" Iterate until the user approves the evolved shape. The approved shape is what gets documented in the final design. **Create full design document following template:** - Problem context (what problem, constraints, interactions) - Design overview (high-level approach, main components) - Shape (evolved shape parts table) - Modeling (entities, relationships, domain model) - Data flow (inputs → processing → outputs) - Key decisions (choice, why, alternatives, consequences) - see research requirements below - System behavior (scenarios, edge cases) **Add UI Layout section (conditionally):** If spec has User Flow section OR design involves UI components: 1. **Read wireframing guide**: `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/wireframing.md` 2. **Create ASCII wireframe(s)** for each place/screen, showing only delta-relevant UI 3. **Write layout explanation (REQUIRED)** with purpose, key elements, rationale, interactions 4. **Add state variations** if relevant to design decisions (loading, error, empty) **Scope**: Show only delta-relevant portions (modal = just modal, form = just form section) If NOT a UI delta (no User Flow section, no UI components): - **Delete the entire UI Layout section from the template** - Do not include empty wireframes **Key decisions research requirements:** - **Must include research sources**: Cite documentation version, search results, or official recommendations - **Must address alternatives**: Document why alternatives were rejected based on research - **Must confirm currency**: Note that proposed libraries/patterns are current per documentation **For each technology choice, document:** | Field | Content | |-------|---------| | Choice | The selected approach | | Why | Reasoning based on research findings | | Sources | Documentation version, WebSearch results, official docs | | Options Researched | All solutions found for the problem, including ones not previously known | | Why This Over Alternatives | Comparison based on current research, not training data assumptions | | Consequences | Trade-offs, maintenance implications | **If any technology choice lacks a Sources entry citing current documentation, the design is incomplete. Follow the `katachi:research-docs` guidance to fill the gap.** **Decision Points:** If you encounter choices requiring user input, use AskUserQuestion: - Multiple valid architectural approaches - Trade-offs between competing concerns (performance vs simplicity, etc.) - Technology or library choices - Missing context that affects design choices **Add Detected Impacts section:** ```markdown ## Detected Impacts ### Affected Feature Designs - **[path/to/feature-design.md]** - [Adds/Modifies/Removes]: [description] ### Notes for Reconciliation - [What needs to change in feature design docs] - [New design sections that need to be created] - [Design decisions that need to be documented] ``` Note any uncertainties or assumptions. ### 6. External Validation (Silent) Dispatch the design-reviewer agent: ```python Task( subagent_type="katachi:design-reviewer", prompt=f""" Review this delta design. ## Delta Spec {spec_content} ## Completed Design {design_content} ## ADR Index Summary {adr_summary} ## DES Index Summary {des_summary} ## Additional Review Criteria - Verify all technology choices cite current documentation sources - Verify that current documentation was searched for each library/framework in the design (zero searches = automatic failure) - Check that options were researched broadly (not just validating a pre-assumed choice) - Confirm research discovered current solutions, not just validated known libraries - Validate design decisions are supported by up-to-date research, not training data - Shape coverage: Does each spec requirement have at least one shape part? Are all unknowns resolved? Are parts mechanisms (not constraints)? ## UI Layout Review (if design includes UI Layout section) - Do wireframes correspond to places in the spec's breadboard? - Are wireframes at appropriate detail level (not too detailed, not too sparse)? - Are state variations covered where relevant to design decisions? - Do layout decisions align with documented design rationale? - Is wireframe scope appropriate (showing only delta-relevant UI)? - Are layout explanations complete (purpose, key elements, rationale, interactions)? """ ) ``` ### 7. Apply Validation Feedback (Silent) Apply ALL recommendations from design-reviewer automatically: - Fix coherence issues - Address pattern violations - Add missing decision documentation - Improve component clarity **Decision Points:** If applying a recommendation requires a choice (multiple valid ways to fix, conflicts with earlier decisions), use AskUserQuestion. Track changes made for presentation in next step. **Auto-apply (no user input):** - Clear fixes (formatting, missing sections with obvious content) - Adding referenced patterns or decisions - Clarifying component responsibilities - Standard compliance fixes ### 8. Present Validated Design Present the complete validated design to the user in its entirety. Highlight any unresolved issues requiring input. Invite feedback: "What needs adjustment in this design?" ### 9. Iterate Based on User Feedback Apply user corrections, additions, or changes. Re-run validation (steps 5-6) if significant changes. Repeat until user approves. ### 10. Detect Patterns for DES If agent or user identifies repeatable patterns: - Ask if pattern should become a DES - Offer to create DES document - Update design to reference new DES ### 11. Finalize Finalize document to `docs/delta-designs/$ARGUMENTS.md` Update status: ```bash python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "✓ Design" ``` Present summary: ``` "Delta design complete for $ARGUMENTS. [Finalized shape parts table] Detected impacts: [list of affected feature design docs]" ``` ## Decision Detection When design reveals hard-to-change choices: - Offer to create ADRs - Offer to create/update DES patterns - Ensure design references existing ADRs/DES ## Workflow **This is a validate-first process:** - Research silently (internal + external), then interview user on design decisions - Evolve shape from spec-phase seed, resolve unknowns via spikes - **Present evolved shape to user for validation before proceeding to full design** - Draft full design incorporating user's input (ask additional decisions when needed) - Auto-discover affected feature designs - Validate with design-reviewer agent (silent) - Apply all validation fixes automatically (ask decisions when needed) - Present validated design with applied changes summary - User provides feedback - Iterate until approved - Surface patterns for DES - Finalize after user approval