software-design-creation

Overview

Create a software design specification that developers can use to plan and implement a feature or standalone software system. The skill should expand a minimal or ambiguous prompt into a structured design artifact, asking clarifying questions when important requirements are missing.

Use this skill when the user wants a design spec, technical plan, feature specification, architecture outline, or implementation-ready requirements document. Do not use it when the main task is to write production code, review code, or create a workflow or agent.

Steps

1. Identify the design target:
   • determine whether the request is for a new feature, a product change, or a standalone software system
   • restate the problem in plain language
   • identify the intended users, operators, or stakeholders if known
2. Assess whether the prompt is complete enough to draft a useful spec:
   • if critical information is missing, ask concise clarifying questions before writing the full spec
   • prioritize questions about user goals, scope boundaries, constraints, integrations, platforms, data, security, and success conditions
   • if the interaction is one-shot or back-and-forth is limited, ask at most a few critical questions and then proceed with explicit assumptions rather than blocking on missing answers
   • if the user does not know all answers, record reasonable assumptions explicitly instead of blocking progress
3. Convert the request into a fuller design brief:
   • summarize the problem being solved
   • describe the user need or business objective
   • distinguish core requirements from optional enhancements
   • define what is in scope and out of scope
4. Draft the design specification with the sections that fit the task:
   • title and summary
   • background or context
   • goals and non-goals
   • users or actors
   • use cases or user flows
   • functional requirements
   • non-functional requirements such as performance, reliability, accessibility, security, privacy, compliance, observability, and maintainability
   • system design or architecture overview
   • components, services, and responsibilities
   • data model or important entities when relevant
   • APIs, interfaces, or integration points when relevant
   • dependencies, assumptions, constraints, and risks
   • rollout or migration considerations when relevant
5. Make the design actionable for implementation:
   • write acceptance criteria that are specific, testable, and tied to user-visible or system-visible outcomes
   • ensure acceptance criteria describe observable behavior, interfaces, or system qualities rather than implementation tasks
   • separate must-have criteria from optional follow-up work when useful
   • note open questions and decisions still needed
   • include suggested implementation slices or milestones only when they help clarify delivery
6. Tailor the level of detail to the user request:
   • for a vague idea, produce a lightweight but structured spec with explicit assumptions
   • for a mature request, provide a more complete design with clearer architecture, interfaces, and constraints
   • avoid inventing unnecessary complexity
7. Before finishing, check the spec quality:
   • ensure the document is internally consistent
   • ensure acceptance criteria are observable and not vague
   • ensure assumptions and unknowns are clearly labeled
   • ensure the output supports downstream planning and implementation
8. Always persist the completed design:
   • write the design to .stencila/designs/{name}.md using write_file, where {name} is a concise kebab-case name for the design (e.g. user-auth-flow)
   • create the .stencila/designs/ directory if it does not exist (the write_file tool creates parent directories automatically)
   • for updates to an existing design, prefer edit_file or apply_patch over rewriting the entire file