design-documentation_skill

Overview

This skill transforms approved requirements into comprehensive technical designs that serve as a blueprint for implementation. It defines system architecture, component responsibilities, data models, interfaces, error handling, and testing strategy to guide development. The output is a clear, reviewable design document suitable for handoff to engineers and stakeholders.

How this skill works

Start by analyzing functional and non-functional requirements, constraints, and integration points. Research technology options and record findings that affect design choices. Produce a structured design document covering architecture diagrams, component interfaces, data models, error and recovery strategies, testing plans, and decision records. Include a quality checklist and clear mapping from requirements to design artifacts.

When to use it

• After requirements are approved and you need an implementation blueprint
• When multiple engineers or teams will implement the feature
• Before making architecture or technology decisions that affect the system
• For features with non-trivial integrations or data model changes
• When traceability between requirements, design, and tests is required

Best practices

• Keep designs requirement-driven; avoid speculative future features
• Define clear component boundaries and explicit interfaces
• Document assumptions, trade-offs, and decision rationales
• Include concrete error handling and recovery strategies for failures
• Provide test plans that map directly to requirements and critical paths

Example use cases

• Designing a new user profile service with storage, image handling, and caching
• Specifying a feature that integrates with third-party APIs and requires retries/fallbacks
• Defining data migration and schema changes for a storage upgrade
• Preparing an architecture that supports horizontal scaling and performance targets
• Creating an API contract and component responsibilities for a cross-team integration