{'>'}_
English 繁體中文 日本語 한국어 Deutsch Español Français
Login

technical-spec-design

wjszxli/technical-spec-design

>

2 stars
0 forks
Python
7 views
View on GitHub Add to Favorites

SKILL.md

name: technical-spec-design description: > Transforms product requirements into structured technical specifications. Auto-triggers when requirements are unclear, multiple implementation approaches exist, or component-level/architecture design is needed.

Auto-trigger conditions:

  • User asks "how to implement a feature"
  • Requests design of technical specs / architecture / APIs / components
  • Mentions "multiple implementation approaches, need comparison"
  • Provides PRD / requirements description, wants technical specs
  • Requirements contain uncertainty or ambiguity

NOT applicable for:

  • Simple bug fixes
  • Simple features with clear implementation path
  • Pure coding tasks (no design decisions)

Technical Specification Design Skill

1. Input Contract

Accepts the following input types:

  1. Complete PRD document
  2. Brief requirements description (may be incomplete)
  3. Existing technical specification (for optimization/review)

2. Available Resources

Core Templates

Resource Purpose Usage Scenario
spec_template.md Main spec template Starting new technical specs
component_template.md Component design Designing individual components
requirements_analysis_template.md Requirements analysis Breaking down requirements

Examples

Resource Purpose
examples/sample_input.md Sample PRD input
examples/sample_output.md Complete spec example

Scripts

Script Purpose Usage
scripts/generate_spec.py Generate spec from template python scripts/generate_spec.py --interactive -o my_spec.md
scripts/validate.py Validate skill structure python scripts/validate.py

3. Output Contract

Output must be Markdown and strictly include the following structure (may be trimmed by mode):

Standard Structure

  1. Requirements Clarification (if needed)
  2. Requirements Analysis (the trifecta)
  3. Technical Specification Design
  4. Component/Module Design
  5. Technology Selection Comparison (if applicable)
  6. Risk and Boundary Analysis
  7. Pending Questions

4. Mode System (Auto-selected)

Mode A: Requirements Clarification Mode

Trigger conditions:

  • Insufficient input information
  • Key uncertainties exist

Output:

  • Only output "Requirements Clarification Questions"
  • Do not proceed with any design work

Mode B: Lightweight Specification Mode

Trigger conditions:

  • Simple features
  • Implementation path is relatively clear

Output:

  • Simplified requirements analysis
  • Core specification design
  • Brief component breakdown

Mode C: Full Technical Specification Mode (Default)

Trigger conditions:

  • Medium to large requirements
  • Involves architecture/component design/technology selection

Output complete structure

5. Execution Flow (Must Follow Strictly)

Step 1: Requirements Completeness Check

Check for missing information:

  • User goals
  • Requirements context
  • Inputs and outputs
  • Constraints
  • Edge cases

If missing: → Enter Mode A, output only clarification questions

Step 2: Requirements Analysis (The Trifecta)

1. Feature Breakdown

Format: Product requirement → Page/Module → Change points

2. Use Case Analysis

Describe complete user paths (cross-page)

3. Page Operation Specification

Format: Action + Condition + Object + Behavior

Step 3: Technical Specification Design

Include:

  • Architecture breakdown (frontend/backend/services)
  • Data flow design
  • State management
  • Core processes (pseudocode acceptable)

Step 4: Component/Module Design

Requirements:

  • Must drill down to component/module level
  • Clear responsibility boundaries
  • Describe dependencies

Step 5: Technology Selection Comparison (If Multiple Options)

Must use table format:

| Approach | Description | Pros | Cons | Use Cases |

Step 6: Risk and Boundary Analysis

Must include:

  • Edge cases
  • Performance concerns
  • Scalability
  • Exception handling

Step 7: Output Pending Questions

List all issues still requiring product/business confirmation

6. Output Constraints (Mandatory)

Prohibited

  • ❌ Output runnable code (JS / TS / Java / SQL, etc.)
  • ❌ Skip requirements analysis and write specs directly
  • ❌ Make assumptions based on "common cases"
  • ❌ Use vague language (e.g., "maybe", "typically")

Required

  • ✅ Use structured expression
  • ✅ Use pseudocode for process descriptions
  • ✅ All changes must map to components/modules
  • ✅ Explicit boundaries and exceptions

7. Technology Research Guidelines

When multiple approaches exist, must use comparison tables—plain text descriptions are not allowed.

8. Red Flags (Must Stop)

If any of these thoughts occur, must stop and return to the process:

  • "Just write a rough spec first"
  • "Handle it the common way"
  • "Design while coding"
  • "This requirement is simple, no analysis needed"

9. Quick Checklist

Before output, must confirm:

  • Requirements clarified
  • Trifecta complete
  • Component design included
  • Pseudocode used
  • Edge cases analyzed
  • Pending questions documented

10. Examples (Few-shot)

Example 1: Ambiguous Requirements (Mode A)

Input: "Build a comment feature"

Output:

  • Do comments support replies?
  • Is pagination needed?
  • Is liking/upvoting needed?
  • Is moderation required?

Example 2: Simple Requirements (Mode B)

Input: "Show success message after form submission"

Output:

  • Brief feature breakdown
  • State transitions
  • Toast/notification component design

Example 3: Complex Requirements (Mode C)

Input: "Design an admin system with multi-role permissions"

Output: Complete technical specification structure (including technology comparison)

Core Principles (Summary)

The essence of technical specifications: eliminate uncertainty before coding.