Skip to content
Skills Library
Documents & office · Writing

meddev-design-docs

/meddev-design-docs

Guide creation and maintenance of Software Architecture (SAD) and Design Descriptions (SDD) that support safety, traceability, and compliance. Use when working on design docs in medical device software.

Licence
MIT
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Guide creation and maintenance of Software Architecture (SAD) and Design Descriptions (SDD) that support safety, traceability, and compliance. Use when working on design docs in medical device software.

Original author description

Guide creation and maintenance of Software Architecture (SAD) and Design Descriptions (SDD) that support safety, traceability, and compliance. Use when working on design docs in medical device software.

How it works

  1. Purpose
  2. When to Apply
  3. Requirements (testable)
  4. Recommended Practices
  5. Patterns
  6. Anti-Patterns (risks)
  7. Verification Checklist
  8. Traceability
  9. References
  10. Changelog
Original SKILL.md headings · 83 lines, 507 words
SKILL.md preview
---
name: meddev-design-docs
description: Guide creation and maintenance of Software Architecture (SAD) and Design Descriptions (SDD) that support safety, traceability, and compliance. Use when working on design docs in medical device software.
license: MIT
metadata:
  skill_id: DOC-DESIGN-DOCS
  version: 1.1.0
  last_updated: '2026-05-21'
  applies_to: Class A, Class B, Class C
  jurisdiction: Global
  prerequisites: REG-IEC62304, REG-ISO14971, DOC-INLINE
  category: documentation
---

# Design Documentation (SAD/SDD)

## Purpose
Guide creation and maintenance of Software Architecture (SAD) and Design Descriptions (SDD) that support safety, traceability, and compliance.

## When to Apply
- New systems/features; major refactors; architecture changes.
- Prior to safety classification decisions and verification planning.

## Requirements (testable)
1. Architecture from Requirements [Class B, C]: Document structure and software items that implement software requirements; verify architecture implements requirements including risk controls. Rationale: 5.3.1, 5.3.6 a.
2. Interface Architecture [Class B, C]: Document interfaces between items and between items and external hardware/software. Rationale: 5.3.2, 5.3.6 b.
3. SOUP Specifications [Class B, C]: For each SOUP item, document functional/performance needs for intended use and required system hardware/software to run it. Rationale: 5.3.3–5.3.4, 5.3.6 c.
4. Risk-Control Segregation [Class C]: Identify segregation between items required for risk control and how effectiveness is ensured. Rationale: 5.3.5.
5. Unit Decomposition [Class B, C]: Subdivide software to software units per architecture. Rationale: 5.4.1.
6. Detailed Design [Class C]: Document unit and interface design sufficient for correct implementation; verify against architecture without contradiction. Rationale: 5.4.2–5.4.4.
7. Traceability: Link design elements to requirements, hazards, and tests. Rationale: 5.3.6, 7.3.3.
8. Updates: Keep design docs current with code under change/configuration control. Rationale: prevent drift.

## Recommended Practices
- Use lightweight but structured docs; diagrams with textual descriptions.
- Keep a living “architecture decisions” log for significant choices.
- Version diagrams; keep source (e.g., PlantUML) in repo.

## Patterns
Architecture snippet (YAML):
```yaml
component: pump_control
class: Class C
interfaces:
  - name: ui_cmd_queue
    type: message_queue
    validation: len, CRC, bounds
hazards: [HZ-07]
controls: [RISK-CTRL-19]
```

SOUP entry:
```yaml
name: tiny-rtos
version: 1.4.2
role: scheduler
known_issues:
  - id: TR-77
    mitigation: disable nested mutex
    verification: TEST-RTOS-12
```

## Anti-Patterns (risks)
- Outdated design docs after code changes -> risk: audit gaps, wrong verification scope.
- Missing interface specs -> risk: integration defects.
- Undocumented SOUP -> risk: unmanaged vulnerabilities.
- No mapping to requirements/hazards -> risk: traceability failure.

## Verification Checklist
- [ ] Class B/C: architecture implements requirements and supports interfaces (5.3.6).
- [ ] Class B/C: SOUP functional and platform needs documented.
- [ ] Class C: segregation for risk control documented (5.3.5).
- [ ] Class C: detailed unit/interface design and verification against architecture (5.4).
- [ ] Design elements linked to requirements/hazards/tests.
- [ ] Docs updated with changes; under `DOC-SCM` / change control.

## Traceability
- Use IDs for design elements (`DES-###`) linked to `REQ-###`, `HZ-###`, `TEST-###`.
- Keep diagrams and text under version control; include in baselines/releases.

## References
- IEC 62304:2006+A1:2015, 5.3–5.4 (architectural and detailed design).
- ISO 14971:2019 (hazard linkage).
- `DOC-SW-REQ`, `ARCH-SAFETY-CLASS`, `REG-IEC62304-SWRM`.
- FDA/MDR tech file expectations (architecture, SOUP).

## Changelog
- 1.1.0 (2026-05-21): Split 5.3 architecture vs 5.4 detailed design; SOUP and Class C segregation aligned to IEC 62304.
- 1.0.0 (2026-01-04): Initial design documentation skill with architecture views, SOUP, and traceability.

## Audit History
- **2026-01-04**: Audit performed. Verified:
  - IEC 62304 architecture/design documentation requirements accurate
  - ISO 14971 hazard linkage requirements correct
  - FDA/MDR tech file expectations appropriately noted

Versions

The database has no other skills named meddev-design-docs.

Database snapshot: 13.11.2026 · package version 66078cd13c90 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100meddev-test-docs
    Define structure and content for test plans, protocols, and reports that support regulatory submissions and internal verification. Use when working on test docs in medical device software.
  • 100meddev-traceability
    Ensure bidirectional traceability between requirements, hazards/risks, design, code, tests, and anomalies for medical device software. Use when working on traceability in medical device software.
  • 100sdd-document-management
    【非推奨】要求の整合性チェックは requirement-management の reqctl.py validate に統合された。既存の docs/sdd/ を保守する場合にのみ使用する。SDDドキュメントの整合性チェック、実装同期確認、アーカイブ(CLAUDE.md同期含む)、ファイル最適化を行う。Do NOT use for 要求の矛盾検出(requirement-management を使用すること)。

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.