SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdesign-solution

design-solution

Coding & development

View repository

Updated 10-16 01:35

About this skill

Skill: Design Solution

Purpose

Transform validated requirements into a single, implementation-free design document. The design describes the architecture, components, data flow, and trade-offs so that downstream skills (e.g., "Break Down Tasks") can derive an executable task list without ambiguity.

Core Objective

Primary Objective: Produce a validated design document based on the requirements, serving as the single source of truth for implementation planning; no code or implementation steps are generated.

Success Criteria(all requirements must be met):

  1. ✅ Design document approved and retained: written to "docs/design-decisions/YYYY-MM-DD-.md" (or the project convention path per "docs/ARTIFACT_NORMS.md"), committed, and explicitly approved by the user
  2. ✅ Requirements traceability: the design explicitly references or summarizes the requirements it satisfies
  3. ✅ Documented alternatives: at least 2-3 approaches considered with trade-offs (pros/cons/best option)
  4. ✅ Error handling and testing strategy: key failure paths and verification methods (testing approach, not test code) are documented
  5. ✅ No implementation: zero code, scaffolding, or implementation tasks; design only
  6. ✅ Downstream readiness: a reader can break the design down into tasks with dependencies and acceptance criteria without asking clarifying questions

Acceptance Test: Can someone use this design document alone to generate a complete, ordered task list (e.g., via "breakdown-tasks") without asking clarifying questions?

Scope Boundaries (Scope Boundaries)

This skill is responsible for：

  • Requirements document → design document (architecture, components, data flow, interfaces)
  • Trade-off analysis and alternative approaches
  • Design approval and persistence as the single source of truth for implementation planning

This skill is not responsible for：

  • Eliciting or validating requirements (use "Analyze Requirements")
  • Converting the design into a task list (use "breakdown-tasks")
  • Writing code or implementing (any implementation skill)
  • Rough idea design without a requirements document (use this skill with a rough idea as input)

Handoff Point: When the design is approved and persisted, hand it off tobreakdown-tasksto generate tasks.md (or equivalent).

Use Cases (Use Cases)

  • Post-requirements design: You have a validated requirements document and need a detailed design before implementation.
  • Architecture from requirements: Requirements are clear; you need component boundaries, data flow, and technical trade-offs.
  • Single source of truth: You need a design document that implementation and task breakdown can rely on.

Behavior (Behavior)

Interaction (Interaction) Policy

  • Default: Requires a requirements artifact (path or content); if present, use the project specification for the design path
  • Choosing options: one question at a time when clarifying; provide "[A][B][C]" as design choices where useful
  • Confirmation: user must agree to the design before handoff; no implementation before approval

Hard Gate: No Implementation

DO NOT write code, scaffold projects, or produce implementation steps.
Output is design documentation only. Implementation is downstream (e.g. breakdown-tasks then execution).

Phase 1: Ingest Requirements

  1. Load requirements: Read the requirements document (e.g., requirements.md or docs/requirements-planning/*.md).
  2. Confirm scope: Briefly confirm with the user that this requirements document is the scope of this design (or an agreed subset).
  3. Identify constraints: Extract constraints, acceptance criteria, and out-of-scope items from the requirements.

Phase 2: Explore Alternatives and Trade-offs

  1. Propose 2-3 approaches: Architecture/component/data flow options that satisfy the requirements.
  2. Document trade-offs: For each option: pros, cons, "best suited for".
  3. Recommendation: State the recommended approach and rationale; ask the user to choose or adjust.

Phase 3: Generate Design Document

  1. Structure: Goals, architecture, components, data flow, error handling strategy (critical failure paths), testing strategy (verification methods, not test code), trade-offs considered, acceptance criteria (traceable to requirements).
  2. Scale to Complexity: Abbreviate for simple scope; provide more detail when needed so that task breakdown is clear.
  3. Resolution path: Check firstdocs/ARTIFACT_NORMS.md(project override); the default fallback is each specs/artifact-contract.md of docs/design-decisions/YYYY-MM-DD-<topic>.md。
  4. Write and save: Save the design with front matter (artifact_type: 设计、created_by: 设计解决方案、lifecycle: snapshot、created_at）。

Phase 4: Approval and Handoff

  1. User approval: Obtain explicit approval before declaring completion.
  2. Handoff: It is recommended to use "breakdown-tasks" with this design as input to generate tasks.md.

Input & Output

Role Content
Input Requirements document (path or content); optional project context, existing design, or ADR
Output Design document located at "docs/design-decisions/YYYY-MM-DD-.md" (or the project path per "docs/ARTIFACT_NORMS.md"); single source of truth for implementation and task breakdown

Limits (Restrictions)

Hard Boundaries

  • No implementation: Do not generate code, file layout, or step-by-step implementation instructions.
  • Requirements first: When requirements are ambiguous or missing, do not run this skill; first hand off to "analyze requirements".
  • Design only: Do not generate a task list; for that, hand off to "break down tasks".

Skill Boundaries (Avoid Overlap)

Do not do these (other skills can handle them)：

  • Requirements elicitation or validation → "analyze requirements"
  • Task breakdown or planning → 分解任务
  • Code implementation or refactoring → implementation techniques

Self-Check

  • Design document approved and retained: written to "docs/design-decisions/YYYY-MM-DD-.md" (or the project path per "docs/ARTIFACT_NORMS.md"), committed, explicitly approved by the user
  • Requirements are cited or summarized; traceability is clear
  • At least 2-3 alternatives with trade-offs are documented
  • Error handling and testing strategy: critical failure paths and verification methods are documented
  • No code or implementation steps in the output
  • Readers can generate a task list based on this design without further explanation.

Examples (Examples)

Example 1: Standard design for validated requirements

Invocation: "We have requirements in docs/requirements-planning/core-v1.md. Create a design document for it."

Agent: Use the design solution; read the requirements; propose 2-3 architecture options and their trade-offs; write the design to docs/design-decisions/YYYY-MM-DD-core-v1.md; obtain user approval; recommend running the decomposition task on this design to obtain tasks.md.

Example 2: Edge case — very small scope

Invocation: "The requirements for a small CLI tool have been captured in docs/requirements-planning/one-off-migration.md. Do we still need a full design document?"

Agent：

  • Confirm that the requirements are validated, but the scope is small.
  • Generate a concise design document that still covers architecture, data flow, and constraints, but keeps each section brief and focused.
  • Clearly state why a lightweight design is sufficient, and mark the document as the single source of truth for later regressions or repeated runs.
  • Obtain user approval, then recommend "decomposition tasks" if implementation is shared or repeated.