| name | design-contribute |
| description | Enables collaborative design contributions to dev-strategy implementation plans through human-in-the-loop sessions. Use when roadmap phases have "Design" objectives, you need to "design the [component]", "figure out the [approach]", "determine the [architecture]", or refinement before implementation. Works with `.plans/plan-[FEATURE-NAME]/` directories only. Produces lean design docs (< 100 lines) through interactive exploration with ruthless focus on simplicity. |
| skills-depend-on | ["contribution-system","design-principles"] |
Design Contribute Skill
Make structured design contributions to dev-strategy implementation plans through interactive, collaborative design sessions with ruthless focus on simplicity.
What This Skill Does
Enables design at the Last Responsible Moment through human collaboration:
- Reading existing plan and implementation learnings
- Interactively exploring design options with the user
- Creating lean design documentation (< 100 lines target)
- Documenting design decisions for implementers
- Maintaining project continuity between design and implementation
Works with: Plans created by dev-strategy skill in .plans/plan-[FEATURE-NAME]/
Context & Philosophy
Two-Gate System Context
This skill operates at Gate 2 of the Two-Gate System Against Over-Engineering. Design was deferred during planning (Gate 1) to gather implementation constraints. Now design with those learned constraints.
See contribution-system/references/two-gate-system.md for full explanation.
Human-in-the-Loop Design Philosophy
Design is inherently collaborative and iterative. Use AskUserQuestion to:
- Understand priorities and validate assumptions
- Present 2-3 options with clear trade-offs (simplest first)
- Get explicit user choice through dialogue, not inference
- Iterate based on user feedback (max 2-3 rounds)
See contribution-system/references/constraint-discovery.md for interactive techniques and patterns.
Token Efficiency in Dialogue
Design sessions are conversation-heavy, and every reply is re-read on each subsequent turn:
- Interactive replies: lead with the outcome, one level of detail. No process narration, no teaching material — the user asks if they want more. When presenting options, state each in a few lines with its trade-off; save depth for the option the user picks.
- Keep decisions, trade-offs, and failures in the reply. Omitting one triggers a follow-up round-trip over the full context, costlier than the sentence that preempts it.
- Artifacts are the opposite case. design-doc.md and context-handoff.md are read by fresh-context implementers that can't ask follow-ups — the < 100 / < 30 line targets mean complete-but-lean, not minimal.
Execution Overview
To create a robust design contribution, three outcomes must be achieved:
Outcome 1 (UNDERSTANDING): Context is clear
- Current plan state is understood (roadmap, prior decisions, constraints visible)
- Implementation learnings are captured
- Design objective is clear and scoped
- Assumptions about design are validated
Outcome 2 (EXPLORATION): Design is validated with user
- Options are presented (2-3 approaches, simplest first)
- Trade-offs are explicit
- User validates choice explicitly
- Design follows simplicity principles
Outcome 3 (DOCUMENTATION): Design is durable and transferable
- Design doc exists (< 100 lines target)
- Decisions are recorded
- Context is handed off (< 30 lines)
- Contribution folder exists with sequential numbering
These criteria are owned here; references restate them for execution convenience only. For the generic outcome pattern shared by all skills, see contribution-system/references/execution-template.md.
Key Outputs
Every design contribution generates exactly 3 files:
- design-doc.md - Target < 100 lines (combines design spec + implementer handoff)
- decision-log.yaml - Design decisions in unified YAML schema
- context-handoff.md - Target < 30 lines (what was solved + reading guide)
That's it. Just 3 files. No code, no prototypes, no comprehensive specs.
For artifact schemas, see contribution-system/references/design-artifacts.md.
How to Use This Skill
For tactics available for each outcome, see references/tactics.md.
Core Principles
For all core principles (YAGNI, Last Responsible Moment, KISS, Sufficient Design), see design-principles skill.
Prerequisites
Before using this skill, read contribution-system skill to understand:
- Design contribution folder naming (NNN-phase-X-design-[topic]-design-contribute)
- Design artifact schemas (design-doc.md, decision-log.yaml, context-handoff.md)
- Unified decision-log YAML schema (with empty code_impacts for design)
- Directory structure (contributions/ folder is required)
- Progressive disclosure strategy for reading design contributions
All design contributions created by this skill must conform to contribution-system conventions.
