Epic PRD to Markdown architecture specification

Author's original introduction

Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document.

SkillPi interpretation

Tasks

Structure an Epic architecture document covering approach, layered Mermaid diagram, features, technical enablers, stack, technical value and size estimate.

Audience

Software architects and developers translating a product manager's Epic PRD into a high-level technical plan.

Inputs and outputs

Input: the Epic PRD Markdown. Output: /docs/ways-of-work/plan/{epic-name}/arch.md with the specified sections and Mermaid diagram; only pseudocode is allowed where technical explanation needs it.

Software, accounts and paid services

An agent with access to the PRD and the documentation path; Mermaid rendering is needed to view the diagram graphically. Docker, TypeScript/Next.js, Turborepo, tRPC and Stack Auth are source design assumptions, not proof of deployed services or paid subscriptions. Confirm actual file access and external-service permissions in your host. Domains referenced in the documents (not a runtime allowlist): No HTTP(S) domain stated.

Limits and differences

Produces an architecture specification, not implementation code or a deployment. The context favors a particular stack; estimates and architecture choices still require project review.

Testing

Not tested

Security rating and access scope

caution · Static evidence review; not a runtime safety guarantee.

An agent with access to the PRD and the documentation path; Mermaid rendering is needed to view the diagram graphically. Docker, TypeScript/Next.js, Turborepo, tRPC and Stack Auth are source design assumptions, not proof of deployed services or paid subscriptions. Confirm actual file access and external-service permissions in your host. Domains referenced in the documents (not a runtime allowlist): No HTTP(S) domain stated.

Before use, confirm and authorize actual file access, external services and network destinations in your host. This review grants no runtime permissions.

Original SKILL.md

---
name: breakdown-epic-arch
description: 'Prompt for creating the high-level technical architecture for an Epic, based on a Product Requirements Document.'
---

# Epic Architecture Specification Prompt

## Goal

Act as a Senior Software Architect. Your task is to take an Epic PRD and create a high-level technical architecture specification. This document will guide the development of the epic, outlining the major components, features, and technical enablers required.

## Context Considerations

- The Epic PRD from the Product Manager.
- **Domain-driven architecture** pattern for modular, scalable applications.
- **Self-hosted and SaaS deployment** requirements.
- **Docker containerization** for all services.
- **TypeScript/Next.js** stack with App Router.
- **Turborepo monorepo** patterns.
- **tRPC** for type-safe APIs.
- **Stack Auth** for authentication.

**Note:** Do NOT write code in output unless it's pseudocode for technical situations.

## Output Format

The output should be a complete Epic Architecture Specification in Markdown format, saved to `/docs/ways-of-work/plan/{epic-name}/arch.md`.

### Specification Structure

#### 1. Epic Architecture Overview

- A brief summary of the technical approach for the epic.

#### 2. System Architecture Diagram

Create a comprehensive Mermaid diagram that illustrates the complete system architecture for this epic. The diagram should include:

- **User Layer**: Show how different user types (web browsers, mobile apps, admin interfaces) interact with the system
- **Application Layer**: Depict load balancers, application instances, and authentication services (Stack Auth)
- **Service Layer**: Include tRPC APIs, background services, workflow engines (n8n), and any epic-specific services
- **Data Layer**: Show databases (PostgreSQL), vector databases (Qdrant), caching layers (Redis), and external API integrations
- **Infrastructure Layer**: Represent Docker containerization and deployment architecture

Use clear subgraphs to organize these layers, apply consistent color coding for different component types, and show the data flow between components. Include both synchronous request paths and asynchronous processing flows where relevant to the epic.

#### 3. High-Level Features & Technical Enablers

- A list of the high-level features to be built.
- A list of technical enablers (e.g., new services, libraries, infrastructure) required to support the features.

#### 4. Technology Stack

- A list of the key technologies, frameworks, and libraries to be used.

#### 5. Technical Value

- Estimate the technical value (e.g., High, Medium, Low) with a brief justification.

#### 6. T-Shirt Size Estimate

- Provide a high-level t-shirt size estimate for the epic (e.g., S, M, L, XL).

## Context Template

- **Epic PRD:** [The content of the Epic PRD markdown file]

Copyright and license notice

MIT License

Copyright GitHub, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.