design

Generate a feature design (design.md) in specs/{feature}/ with user stories, acceptance criteria, technical approach, API contracts, and research decisions.

Coco Design Skill

Generate a feature design from a natural language description, combining specification (what to build) and implementation planning (how to build it) into a single artifact.

When to Use

  • Creating a feature design as part of the coco pipeline
  • Called by /coco:phase (Step A) or /coco:planning-session tactical
  • When a design.md is needed in specs/{feature}/ before task generation

For single-issue fixes, use the hotfix skill instead.

Setup

  1. Read .coco/config.yaml for project.specs_dir (default: specs).
  2. Determine the feature from conversation context:
    • If a feature name or description was provided in the current conversation, use it
    • If on a feature/* git branch, extract the feature name from the branch
    • If a spec directory was recently discussed, use that
    • If none of the above, ask the user for a feature description
  3. Load .coco/memory/constitution.md if it exists.
  4. Load the design template from .coco/templates/design-template.md if it exists, otherwise use ${CLAUDE_PLUGIN_ROOT}/templates/design-template.md.
  5. Load {specs_dir}/{feature-name}/discovery.md if it exists. When present, this discovery brief provides pre-validated user intent, scope decisions, and constraints gathered via the interview skill.

Execution

1. Generate Feature Identity

  • Analyze the description and generate a 2-4 word short name (e.g., "user-auth", "analytics-dashboard")
  • Use action-noun format when possible; preserve technical terms
  • Determine the feature directory: {specs_dir}/{feature-name}/
  • If a directory with this name already exists, append a numeric suffix

2. Create Feature Branch & Directory

Read pr.branch.feature_prefix from .coco/config.yaml (default: feature).

git checkout -b {feature_prefix}/{feature-name}

mkdir -p {specs_dir}/{feature-name}

The branch is feature/{feature-name} (e.g., feature/user-auth). The spec directory is {specs_dir}/{feature-name}/ (without the prefix).

3. Generate Design Document

Fill the design template following this workflow:

Specification phase (WHAT and WHY):

  1. Parse user description, extract key concepts (actors, actions, data, constraints). When discovery.md exists, use it as the primary source for actors, goals, scope, and constraints -- treat the discovery brief as pre-validated input.
  2. For unclear aspects:
    • Make informed guesses based on context and industry standards
    • Only mark with [NEEDS CLARIFICATION: specific question] if the choice significantly impacts scope or UX and no reasonable default exists
    • Maximum 3 markers total (or maximum 1 marker when discovery.md exists, since most ambiguities should already be resolved), prioritized by: scope > security > UX > technical
  3. Fill User Stories section with prioritized, independently testable user stories with BDD acceptance scenarios. When discovery.md exists, derive user stories from the User Intent and Scope sections.
  4. Generate testable Functional Requirements (use reasonable defaults; document assumptions)
  5. Define measurable, technology-agnostic Success Criteria
  6. Identify Key Entities (if data involved)

Technical planning phase (HOW):

  1. Fill Technical Approach section (language, dependencies, storage, testing, platform, project type, performance, constraints)
  2. For each "NEEDS CLARIFICATION" in Technical Approach:
    • Research the unknown using web search or codebase exploration
    • Document findings in the Research & Decisions table (decision, rationale, alternatives)
  3. Fill Project Structure section with the concrete source layout
  4. Generate API Contracts section (if feature exposes APIs) -- inline endpoint contracts
  5. Fill Constitution Check section from constitution (if exists)
    • Evaluate gates -- ERROR if violations are unjustified
    • Document any justified violations in the Complexity Tracking table

Write the design document to {specs_dir}/{feature-name}/design.md.

4. Generate Data Model (Conditional)

Only generate data-model.md if the feature involves significant data modeling (3+ entities with relationships, state transitions, or complex validation rules). Skip for UI-only features or simple CRUD.

If generated, extract from design.md Key Entities:

  • Entity name, fields, relationships
  • Validation rules from requirements
  • State transitions if applicable

Write to {specs_dir}/{feature-name}/data-model.md.

5. Validate Design

Run inline validation against these criteria (no separate checklist file):

Specification quality:

  • No implementation details leak into User Stories or Functional Requirements
  • Focused on user value and business needs
  • All mandatory sections completed
  • No unresolved [NEEDS CLARIFICATION] markers remain (or max 3 critical ones)
  • Requirements are testable and unambiguous
  • Success criteria are measurable and technology-agnostic
  • Edge cases identified

Technical quality:

  • Technical Approach fields are all resolved (no remaining NEEDS CLARIFICATION)
  • Project Structure matches the chosen project type
  • API Contracts are complete (if applicable)
  • Constitution gates pass (if constitution exists)

Fix issues (max 3 iterations). If [NEEDS CLARIFICATION] markers remain (max 3), present them to the user as a table with options and implications. Wait for responses, then update the design.

6. Clarification Pass (Optional)

After design generation, perform a structured ambiguity scan. When discovery.md exists, narrow the scan to categories NOT already covered in the discovery brief -- skip categories where the discovery brief provides clear, validated answers.

Ambiguity Scan: Check coverage across these categories, marking each as Clear / Partial / Missing:

  • Functional Scope: Core user goals, success criteria, explicit out-of-scope
  • Domain & Data Model: Entities, attributes, relationships, state transitions, scale
  • Interaction & UX Flow: Critical journeys, error/empty/loading states
  • Non-Functional Quality: Performance, scalability, reliability, security, compliance
  • Integration: External services/APIs, data formats, failure modes
  • Edge Cases: Negative scenarios, rate limiting, conflict resolution
  • Constraints & Tradeoffs: Technical constraints, rejected alternatives
  • Terminology: Canonical terms, consistency
  • Completion Signals: Acceptance criteria testability, Definition of Done

If no meaningful ambiguities found: Report "No critical ambiguities detected" and skip to Report.

If Partial/Missing categories found: Present up to 5 sequential clarification questions:

  • Multiple-choice: Recommend the best option prominently with reasoning, then present all options in a table. Include "Short answer" option if appropriate.
  • Short-answer: Provide a suggested answer with reasoning. Constrain to <=5 words.
  • Accept "yes" / "recommended" / "suggested" to use your recommendation.
  • Stop when: all critical ambiguities resolved, user says "done", or 5 questions asked.
  • Prioritize by Impact * Uncertainty. Cover highest-impact unresolved categories first.

Integrate Answers: After each accepted answer:

  1. Ensure a ## Clarifications section exists in the design (create after the overview section if missing)
  2. Under ### Session YYYY-MM-DD, append: - Q: <question> -> A: <answer>
  3. Apply the clarification to the appropriate design section:
    • Functional -> update Functional Requirements
    • Data -> update Key Entities
    • Technical -> update Technical Approach or Research & Decisions
    • Non-functional -> add measurable criteria
    • Edge case -> add to Edge Cases
    • Terminology -> normalize across design
  4. Replace any invalidated statements (don't leave contradictions)
  5. Save the design file after each integration

7. Report

Output:

  • Branch name
  • Design file path
  • Data model file path (if generated)
  • Validation results
  • Constitution compliance status (if applicable)
  • Clarification summary (questions asked, sections updated) if clarification pass ran
  • Suggested next step: tell the user to ask Claude to "generate the task list" (this triggers the tasks skill automatically -- skills are NOT slash commands, so never suggest /coco:tasks)

Light Mode

When invoked for a Light-tier feature (1-3 files, single user story, no internal dependencies):

  1. Simplified design: Generate a minimal design containing:
    • One-paragraph overview
    • Single user story
    • 3-5 acceptance criteria
    • No Technical Approach, API Contracts, Research & Decisions, Data Model, or Constitution Check sections
  2. Skip clarification pass (Step 6) entirely
  3. Skip detailed validation -- just verify the acceptance criteria are testable
  4. Suggest next step: Tell the user to ask Claude to "import the design into the tracker" (this triggers the import skill automatically -- skills are NOT slash commands, so never suggest /coco:import)

Light mode is triggered by:

  • /coco:planning-session tactical routing to Light tier
  • /coco:phase classifying the feature as Light tier
  • Explicit request for a "light" or "minimal" design

Guidelines

  • User Stories and Functional Requirements focus on WHAT users need and WHY -- avoid HOW (no tech stack, APIs, code structure in those sections)
  • Technical Approach, API Contracts, and Project Structure focus on HOW -- informed by the spec sections
  • Make informed guesses using industry standards; document assumptions
  • Every requirement must be testable
  • Success criteria: measurable, technology-agnostic, user-focused, verifiable
  • Use absolute paths throughout
  • ERROR on gate failures or unresolved clarifications in Technical Approach
  • Do NOT generate tasks.md -- that is the tasks skill
  • Never modify files outside the feature's spec directory