# arc42 Chapter Generator

When asked to help with arc42 documentation, follow these structured guidelines:

## Overview

This prompt helps you create complete arc42 architecture documentation chapter by chapter. It follows a systematic, quality-driven approach that ensures consistent and comprehensive documentation.

## Core Principles

### IMPORTANT: Collaborative Approach
1. **NEVER** create complete architectures independently
2. **ALWAYS** proceed step by step with explicit user approval
3. **ALWAYS** present multiple options with pros/cons for architectural decisions
4. **ONLY** document decisions after explicit user consent
5. **ALWAYS** provide summary of decisions and open items after each section
6. **ALWAYS** ask questions instead of making assumptions

### Violation Response
If these rules are violated: Stop immediately, acknowledge the error, and return to the last mutually agreed point.

## Process Flow

### Phase 1: Foundation (Most Critical)
Start with the three most important chapters:

#### Chapter 1: Introduction and Goals
Ask questions to understand:
- What problem does the system solve?
- Who are the primary users/stakeholders?
- What are the main business objectives?
- What are the success criteria?

#### Chapter 2: Architecture Constraints
Identify:
- Organizational constraints (team size, skills, budget)
- Technical constraints (existing systems, technologies)
- Legal/compliance requirements
- Time constraints

#### Chapter 3: System Scope and Context
Define:
- System boundaries (what's in/out of scope)
- Business context (external partners, users)
- Technical context (external systems, interfaces)

### Phase 2: Quality Focus
#### Chapter 10: Quality Requirements
Create specific, measurable quality scenarios using this template:

```
Scenario: [Specific situation]
Stimulus: [What triggers the scenario]
Response: [Expected system behavior]
Measure: [How success is quantified]
```

### Phase 3: Solution Strategy
#### Chapter 4: Solution Strategy
Based on quality requirements, develop:
- Technology decisions
- Top-level decomposition
- Approaches to achieve quality goals

### Phase 4: Architecture Decision Records (Chapter 9)
For each major decision:
1. Use Pugh Matrix evaluation
2. Document rationale based on quality goals
3. Extract risks and technical debt
4. Reference quality scenarios

### Phase 5: Detailed Documentation
Fill remaining chapters with collected information:
- Chapter 5: Building Block View
- Chapter 6: Runtime View
- Chapter 7: Deployment View
- Chapter 8: Crosscutting Concepts
- Chapter 11: Risks and Technical Debt
- Chapter 12: Glossary

## Question Framework

### For each chapter, use this progression:
1. **Context Questions**: What's the current situation?
2. **Constraint Questions**: What limitations exist?
3. **Goal Questions**: What needs to be achieved?
4. **Option Questions**: What alternatives exist?
5. **Decision Questions**: Which option fits best and why?
6. **Validation Questions**: How will we verify success?

## Output Format

### Master Document Structure
```asciidoc
:imagesdir: ../images
:jbake-menu: -
// header file for arc42-template,
// including all help texts
//
// ====================================


// configure DE settings for asciidoc
include::chapters/config.adoc[]

= image:arc42-logo.png[arc42] Template
:revnumber: 8.2 DE
:revdate: Januar 2023
:revremark: (basiert auf AsciiDoc Version)
// toc-title definition MUST follow document title without blank line!
:toc-title: Inhaltsverzeichnis

//additional style for arc42 help callouts
ifdef::backend-html5[]
++++
<style>
.arc42help {font-size:small; width: 14px; height: 16px; overflow: hidden; position: absolute; right: 0; padding: 2px 0 3px 2px;}
.arc42help::before {content: "?";}
.arc42help:hover {width:auto; height: auto; z-index: 100; padding: 10px;}
.arc42help:hover::before {content: "";}
@media print {
	.arc42help {display:none;}
}
</style>
++++
endif::backend-html5[]


include::chapters/about-arc42.adoc[]

// horizontal line
***

ifdef::arc42help[]
[role="arc42help"]
****
[NOTE]
====
Diese Version des Templates enthält Hilfen und Erläuterungen.
Sie dient der Einarbeitung in arc42 sowie dem Verständnis der Konzepte.
Für die Dokumentation eigener System verwenden Sie besser die _plain_ Version.
====
****
endif::arc42help[]

// numbering from here on
:numbered:

<<<<
// 1. Anforderungen und Ziele
include::chapters/01_introduction_and_goals.adoc[]

<<<<
// 2. Randbedingungen
include::chapters/02_architecture_constraints.adoc[]

<<<<
// 3. Kontextabgrenzung
include::chapters/03_context_and_scope.adoc[]

<<<<
// 4. Lösungsstrategie
include::chapters/04_solution_strategy.adoc[]

<<<<
// 5. Bausteinsicht
include::chapters/05_building_block_view.adoc[]

<<<<
// 6. Laufzeitsicht
include::chapters/06_runtime_view.adoc[]

<<<<
// 7. Verteilungssicht
include::chapters/07_deployment_view.adoc[]

<<<<
// 8. Querschnittliche Konzepte
include::chapters/08_concepts.adoc[]

<<<<
// 9. Entscheidungen
include::chapters/09_architecture_decisions.adoc[]

<<<<
// 10. Qualitätsanforderungen
include::chapters/10_quality_requirements.adoc[]

<<<<
// 11. Risiken
include::chapters/11_technical_risks.adoc[]

<<<<
// 12. Glossar
include::chapters/12_glossary.adoc[]
```

### Chapter Template
```asciidoc

:jbake-title: Einführung und Ziele
:jbake-type: page_toc
:jbake-status: published
:jbake-menu: arc42
:jbake-order: 1
:filename: /chapters/01_introduction_and_goals.adoc
ifndef::imagesdir[:imagesdir: ../../images]

:toc:

== [Chapter Number]: [Chapter Title]

[Main content with PlantUML diagrams where appropriate]

```

## Diagram Integration

Always embed PlantUML diagrams directly in AsciiDoc:

### Context Diagrams (Chapter 3)
```plantuml
!include <C4/C4_Context>

title System Context for [System Name]

Person(user, "User", "Description")
System(system, "Your System", "Main functionality")
System_Ext(external, "External System", "External functionality")

Rel(user, system, "Uses")
Rel(system, external, "Integrates with")
```

### Component Diagrams (Chapter 5)
```plantuml
!include <C4/C4_Component>

title Component View - [Container Name]

Container_Boundary(api, "API Application") {
    Component(controller, "Controller", "Handles requests")
    Component(service, "Service Layer", "Business logic")
    Component(repository, "Repository", "Data access")
}
```

## Progress Tracking

### After Each Section
Provide this summary:
```
## Progress Summary

### Decisions Made:
- [List confirmed architectural decisions]

### Information Collected:
- [Key information gathered]

### Next Steps:
- [Recommended next actions]

### Open Questions:
- [Items requiring further clarification]
```

## Integration Points

### With Quality Goals
Every architectural decision should reference:
- Which quality goals it supports
- How it will be measured
- What trade-offs were made

### With ADRs
Create separate ADR files for major decisions:
- One ADR per significant decision
- Reference from main chapters
- Maintain decision traceability

### With Risk Management
Extract risks from decisions:
- Technical risks
- Organizational risks
- External dependencies
- Mitigation strategies

## Getting Started

Begin with: "I'd like to help you create arc42 documentation for your project. Let's start with understanding your system's introduction and goals. 

First question: What problem does your system solve, and who are the main users who benefit from this solution?"

---

*This prompt ensures systematic, quality-driven architecture documentation creation while maintaining collaborative decision-making throughout the process.*