design-doc-high-level

name	design-doc-high-level
description	Generate a high-level architecture design document from a requirements document. Covers technology choices, compute platforms, databases, data models, data flows, and security posture — no code snippets or code structure.
argument-hint	[prefix] [constraints or technology preferences, or leave blank]

Generate a high-level architecture design document from an existing requirements document through an interactive discovery process.

This document answers "what are we building and what technology choices support it?" — it does NOT include code snippets, class structures, or implementation-level details.

Input

The user may provide: $ARGUMENTS (design prefix, technology constraints, preferences, or context)

Expected Folder Structure

design/
├── {prefix}-requirements.md          # Input: must exist
└── {prefix}-high-level-design.md     # Output: this skill creates this

Process

Phase 1: Locate and Read Requirements

1. If $ARGUMENTS provides a prefix, look for design/{prefix}-requirements.md
2. Otherwise, scan design/ for files matching *-requirements.md (also check for unprefixed requirements.md for backwards compatibility)
3. If exactly one match: use it and infer the prefix from the filename (e.g., client-requirements.md means the prefix is client)
4. If multiple matches: use AskUserQuestion to list all discovered options and ask which design to work with
5. If no matches: use AskUserQuestion to ask the user where the requirements are
6. If no prefix was determined yet (e.g., an unprefixed requirements.md was found, or the user provided a custom path), use AskUserQuestion to ask: "What design prefix should be used? This allows multiple designs to coexist (e.g., 'client', 'server', 'auth')."
7. Read and understand the requirements document thoroughly before proceeding

Phase 2: Gather Architectural Constraints

Ask the user about key architectural decisions using AskUserQuestion. Adapt questions to the specific system, but common areas include:

Runtime Environment

• Where will this run? (Kubernetes, bare metal, serverless, local only, edge)
• Cloud provider preferences? (AWS, GCP, Azure, local/on-prem)
• Single region or multi-region?

Compute Platform

• Container orchestration? (Kubernetes, ECS, Docker Compose, none)
• Serverless components? (Lambda, Cloud Functions, none)
• Background job processing? (dedicated workers, queues, cron)

Programming Language

• Implementation language? (Go, Python, Rust, TypeScript, Java, etc.)
• Are there team constraints or existing ecosystem considerations?

Data Storage

• Primary database? (PostgreSQL, MySQL, SQLite, DynamoDB, etc.)
• Caching layer? (Redis, Memcached, none)
• Object/file storage? (S3, GCS, local filesystem)
• Message queue or event streaming? (Kafka, SQS, RabbitMQ, none)

Networking & Communication

• Synchronous communication patterns? (REST, gRPC, GraphQL)
• Asynchronous patterns? (message queues, event bus, webhooks)
• Service mesh or API gateway?

Security Posture (High Level)

• Authentication mechanism? (OAuth2, API keys, mTLS, SAML)
• Authorization model? (RBAC, ABAC, simple permissions)
• Data encryption requirements? (at rest, in transit, field-level)
• Compliance requirements? (SOC2, HIPAA, PCI-DSS, none)

Deployment & Operations

• CI/CD approach? (GitHub Actions, GitLab CI, Jenkins, etc.)
• Observability stack? (CloudWatch, Datadog, Prometheus/Grafana, etc.)
• Deployment strategy? (blue/green, rolling, canary)

Ask 2-4 focused questions at a time. Provide reasonable default options with one marked "(Recommended)" based on the requirements. Continue until you have enough clarity for architectural decisions.

Phase 3: Generate High-Level Design

Create design/{prefix}-high-level-design.md using the template in template.md with these sections:

1. Overview — What the system does and the key technology choices at a glance
2. Architecture Summary — Mermaid diagram showing major components and their relationships
3. Core Components — What each component does, why it exists, and what it owns
4. Data Models — Logical data model with entity relationships (Mermaid erDiagram), key attributes, and relationship cardinalities. No schema DDL — just the conceptual model.
5. Data Flows — How data moves through the system for key operations (Mermaid flowcharts or sequence diagrams). Cover the happy path and significant failure paths.
6. Key Design Decisions — Decisions made with rationale and alternatives considered
7. Security Architecture — Authentication/authorization model, encryption boundaries, trust boundaries, network segmentation. Mermaid diagrams for trust boundaries where helpful.
8. Deployment Model — How it runs in production vs. locally, what infrastructure is needed
9. Technology Choices — Table of all technology selections with rationale
10. What This Design Defers — Explicitly out of scope for v1
11. Open Questions — Decisions that still need user input

Design Principles:

• Favor the simplest architecture that meets requirements
• Make explicit what is deferred vs. included
• Document every decision with rationale and alternatives considered
• Identify open questions that need user input

Conventions:

• Use Mermaid diagrams (NOT ASCII art) — flowchart, erDiagram, sequenceDiagram, C4Context
• Tables for structured comparisons
• Clear section headers for scannability
• NO code snippets, NO class definitions, NO directory structures, NO implementation details

Mermaid Diagram Rules (required for renderer compatibility — GitLab, GitHub, VS Code use older Mermaid.js):

• Always quote flowchart node labels: A["Start here"] not A[Start here]
• Always quote decision nodes: B{"Is it ready?"} not B{Is it ready?}
• Always quote subgraph titles: subgraph sg["My Group"] not subgraph sg[My Group]
• Prefer A -- "label" --> B link syntax over A -->|"label"| B
• Use plain text participant aliases in sequence diagrams: participant SVC as my-service
• Keep labels short — move detail into surrounding prose
• NO <br/> in any label or node text
• NO par / and blocks in sequence diagrams — use Note over A,B: description instead
• NO <--> bidirectional arrows — use two separate directed arrows
• NO }o--|| at start of erDiagram lines — reverse to ||--o{
• NO special characters in state/flowchart labels: () . / → __ — use plain words

Phase 4: Solicit Feedback

After generating the high-level design, summarize:

• Key architectural decisions made
• What is explicitly deferred
• Open questions that need user input

Invite the user to review and provide feedback. Iterate on the document based on their input.

Phase 5: Sync to Grimoire

After writing the local file, sync it to the grimoire so it's searchable and accessible across projects.

1. Derive the project name from the project context:

   • Check design/{prefix}-requirements.md title or the project's root directory name
   • Use a short, lowercase, hyphenated name (e.g., my-api-server, data-pipeline)
   • If unclear, use AskUserQuestion to ask the user what to call this project

2. Write the file to the grimoire:

   ~/.grimoire/files/technical-designs/{project-name}/{prefix}-high-level-design.md
   

   Copy the full contents of design/{prefix}-high-level-design.md to this path.

3. Register metadata using the grimoire-cli CLI:

   grimoire-cli create-file-metadata \
     --file "files/technical-designs/{project-name}/{prefix}-high-level-design.md" \
     --source-agent "design-doc-high-level" \
     --tags "type/high-level-design,project/{project-name},topic/technical-design" \
     --summary "High-level architecture design for {project name}"
   

   If the file already exists in the grimoire, use update-file-metadata instead.

4. If the grimoire CLI is not available (command not found), skip this phase silently — the local file is the primary output.

Output

Create design/{prefix}-high-level-design.md (create design/ directory if needed). Also synced to ~/.grimoire/files/technical-designs/{project-name}/{prefix}-high-level-design.md if the grimoire is available.

The high-level design should be:

• Architecture-focused: Technology choices, component boundaries, data flows — not implementation details
• Decision-rich: Every significant choice documented with rationale
• Reviewable: Clear enough for stakeholders to approve before moving to low-level design
• Diagram-heavy: Visual representations of architecture, data models, data flows, and security boundaries