Cloud Architecture Best Practices Docs

Cloud Architecture Best Practices Docs

This skill turns the Senior Cloud Architect's Definition of Done into an executable architecture-document check so {app}_Architecture.md deliverables do not ship with missing sections, incomplete diagram explanations, or broken Mermaid structure.

When to invoke

• "Validate this architecture document before presenting it."
• "Review {app}_Architecture.md for required sections and diagrams."
• "Confirm the Mermaid diagrams and diagram explanations are complete."
• "Run the architecture document Definition of Done."

Prerequisites and context

• Pair this with the deploy-managed architecture workflow: the responsible agent designs and writes {app}_Architecture.md, then runs this gate before presenting.
• The validation script is standard-library Python and self-contained; no install is needed.

Criteria

Required content

• Required sections are present: Executive Summary, System Context, Component Architecture, Deployment Architecture, Data Flow, Risks and Mitigations.
• The five required diagrams are present: System Context, Component, Deployment, Data Flow, Sequence.
• Each diagram's section includes the seven explanation parts: Overview, Key Components, Relationships, Design Decisions, NFR Considerations, Trade-offs, Risks and Mitigations.

Mermaid structure

• Every Mermaid block is fenced and non-empty.
• Every Mermaid block declares a known diagram type such as graph, flowchart, sequenceDiagram, erDiagram, or stateDiagram-v2.
• Brackets are balanced.
• Diagram types that need edges or messages include them.

Repository copy conventions

• No em dashes appear.
• "GitHub Copilot" is never abbreviated to bare "Copilot".
• No unfilled template placeholders remain: {app}, [Diagram], TODO, or TBD.
• Numbers in an architecture document, including NFR targets and costs, are sourced or labeled as assumptions; the gate flags conventions, not factual accuracy, so keep the data integrity rule yourself.

Script workflow

1. Write or update the architecture document as {app}_Architecture.md.

2. Run the gate:

   python .github/skills/architecture-doc/scripts/validate_arch.py <App_Architecture.md>
   

3. Fix every reported error, then rerun until it passes.

4. Record the result at the end of the document as a short "Validation" note.

5. Override the minimum diagram count only when justified: --min-diagrams 6.

Output template

Return exactly this structure:

# Architecture document validation result

**Status:** passed | failed | blocked
**Document:** <path to architecture document>
**Summary:** <one-sentence compliance summary>

### Details
- Required sections: <pass/fail and missing items>
- Required diagrams: <pass/fail and missing items>
- Diagram explanations: <pass/fail and missing parts>
- Repository copy conventions: <pass/fail and findings>

### Validation evidence
- Command: `python .github/skills/architecture-doc/scripts/validate_arch.py <App_Architecture.md>`
- Exit status: <0 or non-zero>
- Errors: <none or list>
- Warnings: <none or list>

Limits

• Do not use this skill for creating cloud diagrams.
• Use azure-draw-io-diagram-generator (skill) instead when the deliverable is an editable diagram file or rendered cloud diagram.
• Use markdown-writer (skill) instead when the task is generic Markdown writing.
• Use agentic-architecture-patterns (skill) instead when designing agent architecture.
• The script cannot fully render Mermaid; it uses high-signal structural checks.

Gotchas

• If a Mermaid diagram is very complex, simplify it rather than risk a render error.
• Do not present a document that fails the gate.

Progressive disclosure and bundled resources

At discovery time, only name and description are loaded. Execute the script only when validating a real architecture document.

• scripts/validate_arch.py: architecture Markdown gate for required sections, diagrams, Mermaid structure, and conventions.

Related primitives

Quality gate

• Required sections are present.
• The five required diagrams are present.
• Mermaid blocks are structurally valid by the script's checks.
• Every diagram section includes the seven explanation parts.
• Repository copy conventions pass.
• The validation command was run and evidence is reported.
• Any warnings are reviewed and any errors are fixed.
• The response follows ## Output template exactly.
• Every bundled resource referenced above exists.