peterbamuhigire/sdlc-design

Platform Notes

• Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

SDLC Design Skill

<!-- dual-compat-start -->

Use When

• Generate Design & Development documentation for SDLC projects. Covers System Design Document (SDD), Technical Specification, Interface Control Document (ICD), Database Design Document, Code Documentation standards, and API Documentation. Use when...
• The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

Do Not Use When

• The task is unrelated to sdlc-design or would be better handled by a more specific companion skill.
• The request only needs a trivial answer and none of this skill's constraints or references materially help.

Required Inputs

• Gather relevant project context, constraints, and the concrete problem to solve; load templates only as needed.
• Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

Workflow

• Read this SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
• Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
• Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

Quality Standards

• Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
• Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
• Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

Anti-Patterns

• Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
• Loading every reference file by default instead of using progressive disclosure.

Outputs

• A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
• Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
• References used, companion skills, or follow-up actions when they materially improve execution.

References

• Use the templates/ directory when the task needs a structured deliverable.

<!-- dual-compat-end -->

Generate a complete Design & Development documentation suite for software development projects. This skill produces 6 design documents that translate requirements (from sdlc-planning) into actionable technical architecture and implementation guidance.

Load Order

1. Load world-class-engineering.
2. Load system-architecture-design and database-design-engineering.
3. Load this skill to turn approved requirements into executable design artifacts.

Executable Design Standard

Design documents must define:

• critical flows, invariants, and failure handling
• release-aware architecture and migration posture
• observability, audit, and operational ownership expectations
• contract evolution rules for live systems

When to Use

• Translating an approved SRS into a technical architecture and system design
• Documenting database schemas, stored procedures, and data models for a new system
• Specifying API contracts for frontend, mobile, and third-party consumers
• Defining interface contracts between system components and external systems
• Establishing code documentation standards before development begins
• Creating technical specifications for complex features or modules

When NOT to Use

• Gathering raw requirements -- use project-requirements skill
• Project-level planning (SDP, QA Plan, Risk Plan) -- use sdlc-planning skill
• Planning a single feature (spec + implementation) -- use feature-planning skill
• Writing test plans and test cases -- use sdlc-testing skill
• Writing deployment or user documentation -- use sdlc-user-deploy skill
• Planning an Android companion app -- use android-saas-planning skill

Document Inventory

| # | Document | File | Purpose | Audience | Length | |---|----------|------|---------|----------|--------| | 1 | System Design Document | templates/system-design-document.md | Overall architecture, components, interactions | Architects, senior devs, tech leads | 20-40 pages | | 2 | Technical Specification | templates/technical-specification.md | Implementation details, algorithms, data structures | Developers implementing the system | 20-40 pages | | 3 | Interface Control Document | templates/interface-control-document.md | Interface contracts between components/systems | Integration engineers, API consumers | 15-30 pages | | 4 | Database Design Document | templates/database-design-document.md | Schema, data models, relationships, procedures | DBAs, backend developers | 20-40 pages | | 5 | Code Documentation Standards | templates/code-documentation-standards.md | Inline comments, docstrings, documentation rules | All developers | 10-20 pages | | 6 | API Documentation | templates/api-documentation.md | Endpoint specs, auth, errors, SDK examples | Frontend/mobile devs, integrators | 20-40 pages |

Prerequisites

Before generating design documents, ensure these inputs exist:

| Input | Source | Required? | |-------|--------|-----------| | Software Requirements Spec (SRS) | sdlc-planning skill output | Yes | | Project Vision & Scope | sdlc-planning skill output | Yes | | Tech stack decisions | Project context or defaults | Yes | | Approved feature list with priorities | SRS or stakeholder sign-off | Yes | | Module inventory | SRS or modular-saas-architecture | Recommended | | Existing database schemas (if migrating) | Codebase audit | If applicable | | API consumers list (mobile, web, 3rd party) | Project context | Recommended |

Generation Workflow

Generate documents in this order. Each builds on the previous.

Step 1: System Design Document (architecture baseline)
    |
Step 2: Database Design Document (data layer foundation)
    |
Step 3: Technical Specification (implementation details)
    |
Step 4: Interface Control Document (component contracts)
    |
Step 5: API Documentation (consumer-facing specs)
    |
Step 6: Code Documentation Standards (team conventions)

Rationale: Architecture drives database design. Database and architecture together inform technical specs. Interface contracts are defined after components are known. API docs are consumer-facing views of interface contracts. Code standards apply across all layers.

Architecture Patterns Supported

| Pattern | Where Used | Skill Reference | |---------|------------|-----------------| | MVVM + Clean Architecture | Android (Presentation / Domain / Data layers) | android-development | | Three-Panel Web Architecture | /public/, /adminpanel/, /memberpanel/ | multi-tenant-saas-architecture | | REST API + Dual Auth | Session (web) + JWT (mobile) | dual-auth-rbac | | Row-Level Multi-Tenancy | franchise_id in every tenant-scoped query | multi-tenant-saas-architecture | | Pluggable Module Architecture | Enable/disable business modules per tenant | modular-saas-architecture | | Repository Pattern | Android data access abstraction | android-data-persistence | | Service Layer Pattern | PHP business logic encapsulation | php-modern-standards |

Cross-References to Existing Skills

Upstream Skills (use BEFORE this skill)

| Skill | Relationship | |-------|-------------| | sdlc-planning | Provides SRS, Vision & Scope, SDP as inputs. Design docs implement what planning docs specify. | | project-requirements | Raw requirements gathered via guided interview. Feed into SRS, then into design. |

Parallel Skills (use ALONGSIDE this skill)

| Skill | Relationship | |-------|-------------| | mysql-best-practices | Database Design Document references these standards. Do not duplicate; cross-reference. | | api-error-handling | API Documentation and Technical Spec reference error response patterns. | | api-pagination | API Documentation references pagination patterns (offset-based). | | php-modern-standards | Technical Spec and Code Documentation reference PHP 8+ standards. | | android-development | Technical Spec references Android architecture layers (MVVM + Clean). | | multi-tenant-saas-architecture | SDD references tenant isolation, three-panel architecture. | | dual-auth-rbac | SDD and ICD reference dual auth flows and RBAC model. | | vibe-security-skill | Security architecture sections in SDD. Always apply alongside. |

Downstream Skills (use AFTER this skill)

| Skill | Relationship | |-------|-------------| | feature-planning | Uses design docs as input for individual feature specs and implementation plans. | | sdlc-testing | Uses design docs to create test plans and test cases (future). | | sdlc-user-deploy | Uses design docs for deployment guides and user manuals. | | saas-seeder | Uses database design to bootstrap the SaaS template. |

Adaptation Rules

SaaS vs Standalone

| Aspect | Multi-Tenant SaaS | Standalone App | |--------|-------------------|----------------| | SDD scope | Three-panel architecture, tenant isolation | Single app architecture | | Database design | franchise_id on all tenant tables | No tenant scoping | | API auth | Dual auth (Session + JWT) | Single auth model | | ICD complexity | Backend-Mobile-Web + external integrations | Fewer interface types | | Security design | Zero-trust, audit trails, RBAC | Simpler security model |

Mobile + Web vs Web-Only

| Aspect | Android + Web | Web-Only | |--------|---------------|----------| | SDD components | PHP backend + Android layers + Web frontend | PHP backend + Web frontend | | ICD scope | REST API + internal Android layer boundaries | AJAX/fetch + internal PHP layers | | API docs | JWT auth + session auth sections | Session auth only | | Code docs | PHP + Kotlin + SQL standards | PHP + SQL standards |

MVP vs Full Product

| Aspect | MVP | Full Product | |--------|-----|--------------| | SDD depth | Core modules only (3-5) | All modules (10-20+) | | Database design | Core tables only | Complete schema | | API endpoints | Authentication + core CRUD | Full endpoint inventory | | ICD | Internal interfaces only | Internal + external integrations |

Output Structure

When generating design documents for a project, create this structure:

docs/design/
├── 01-system-design-document.md
├── 01-sdd/
│   ├── component-design.md
│   ├── security-architecture.md
│   └── deployment-architecture.md
├── 02-database-design-document.md
├── 02-database/
│   ├── entity-relationship.md
│   ├── table-definitions.md
│   └── stored-procedures.md
├── 03-technical-specification.md
├── 03-tech-spec/
│   ├── module-specifications.md
│   └── algorithm-details.md
├── 04-interface-control-document.md
├── 05-api-documentation.md
├── 05-api/
│   ├── authentication-endpoints.md
│   ├── module-endpoints.md
│   └── error-reference.md
└── 06-code-documentation-standards.md

Each file must stay under 500 lines. Split into subdirectories as needed.

Quality Checklist

Run after generating all documents:

• [ ] All 6 documents generated (or justified why one was skipped)
• [ ] Each document stays under 500 lines (split if needed)
• [ ] SDD references the correct tech stack with version numbers
• [ ] SDD includes ASCII architecture diagrams (system context, high-level, deployment) — visual-aid locations marked with [DIAGRAM-PROMPT: <description>]
• [ ] Every major design decision includes a ## Design Rationale block: chosen approach, rejected alternatives, trade-off reasoning
• [ ] Major architectural decisions captured as Architecture Decision Records (ADRs): Context → Decision → Alternatives Considered → Consequences
• [ ] Database Design references mysql-best-practices skill, not duplicate it
• [ ] All tenant-scoped tables include franchise_id column
• [ ] API Documentation references api-error-handling and api-pagination skills
• [ ] ICD covers all interface types (backend-mobile, backend-web, external)
• [ ] Technical Spec includes real PHP/Kotlin/SQL code examples in fenced code blocks with language identifiers
• [ ] Code Documentation Standards cover PHP, Kotlin, and SQL
• [ ] Security architecture addresses dual auth, RBAC, encryption, audit trails
• [ ] Deployment environments (Windows dev, Ubuntu staging, Debian prod) documented
• [ ] Rollout, migration, and rollback posture are explicit for live systems
• [ ] All documents cross-reference each other and upstream SRS
• [ ] No vague language -- all specifications are measurable and concrete
• [ ] Examples are tailored to the project's actual tech stack and domain

Anti-Patterns (What NOT to Do)

| Anti-Pattern | Why It Fails | Do This Instead | |-------------|-------------|-----------------| | Design without approved SRS | Architecture without requirements is guesswork | Complete sdlc-planning first | | One massive design doc | Exceeds 500-line limit, hard to maintain | Split into 6 focused documents | | No ASCII diagrams | Text-only architecture is hard to understand | Include system context, component, deployment diagrams — mark points needing visuals with [DIAGRAM-PROMPT: <description>] | | Copy MySQL standards into DB design | Duplicates mysql-best-practices, goes stale | Cross-reference the skill | | Skip tenant isolation design | Data leakage between tenants | Always document franchise_id strategy | | API docs without error codes | Consumers can't handle failures | Include complete error reference table | | No interface versioning strategy | Breaking changes cause outages | Document versioning in ICD | | God classes in component design | Violates SRP, untestable | Define clear component boundaries | | Design docs never updated | Docs become stale and misleading | Update at each phase gate | | Platform-generic examples | Developers can't apply them | Use your actual tech stack in examples | | Design decisions without rationale | Future maintainers cannot evaluate or change decisions | Add ## Design Rationale to every key decision: state the chosen approach, rejected alternatives, and the trade-off reasoning | | No Architecture Decision Records | Architecture history lost; audits fail | Capture each major architectural decision in a structured ADR: Context → Decision → Alternatives → Consequences |

Template Files

Each template provides the complete structure, section-by-section guidance, example excerpts, anti-patterns, and a quality checklist.

1. System Design Document
2. Technical Specification
3. Interface Control Document
4. Database Design Document
5. Code Documentation Standards
6. API Documentation

References

• ../sdlc-lifecycle.md: Shared SDLC execution model and lifecycle gates.

---

Back to: Skills Repository Related: sdlc-planning | feature-planning | mysql-best-practices | api-error-handling Last Updated: 2026-03-15 (strengthened per Adjei 2023, Winston, Etter 2016)