architecture-docs

What this skill does

# Architecture Documentation Skill

This skill provides comprehensive guidelines for creating and maintaining ARCHITECTURE.md files using the standardized template from ARCHITECTURE_DOCUMENTATION_GUIDE.md. It enforces consistency across all documentation sections through the **Foundational Context Anchor Protocol** — a dependency-aware editing workflow that loads required upstream context before any downstream section edit, requires source attribution for derived claims, and detects downstream impact when any section changes.

### CRITICAL: Section Number vs File Prefix Disambiguation

Internal section numbers (S1-S13) and file prefix numbers (01-11) are **independent** and do NOT align.

| Internal Section | Name | File |
|---|---|---|
| S1+S2 | Executive Summary + System Overview | `docs/01-system-overview.md` |
| S3 | Architecture Principles | `docs/02-architecture-principles.md` |
| S4 | Architecture Layers | `docs/03-architecture-layers.md` |
| S5 | Component Details | `docs/components/` |
| S6 | Data Flow Patterns | `docs/04-data-flow-patterns.md` |
| S7 | Integration Points | `docs/05-integration-points.md` |
| S8 | Technology Stack | `docs/06-technology-stack.md` |
| S9 | Security Architecture | `docs/07-security-architecture.md` |
| S10 | Scalability & Performance | `docs/08-scalability-and-performance.md` |
| S11 | Operational Considerations | `docs/09-operational-considerations.md` |
| S12 | ADRs | `adr/` directory |
| S13 | Risks and Technical Debt | `docs/10-risks-and-technical-debt.md` |

**Rules:**
- When a user says "update Section 9" → resolve to **S9** = `docs/07-security-architecture.md`, NOT `docs/09-*`
- `docs/09-operational-considerations.md` = **S11**, not Section 9
- Always use S-prefix (S1-S13) to identify sections, file paths to identify files
- NEVER assume file prefix `NN` equals section number `N`
- **Legacy layouts** (created before S13 existed) place References at `docs/10-references.md` with no `docs/10-risks-and-technical-debt.md`. Any workflow operating on an existing multi-file project MUST run Workflow 11 (Layout Migration Gate) as a preflight before proceeding.

## When This Skill is Invoked

Automatically activate when:
- User asks to create architecture documentation
- User asks to update or edit ARCHITECTURE.md
- User mentions documenting system architecture
- User requests architecture review, audit, or analysis (triggers Design Drivers calculation prompt)
- User explicitly asks to "calculate design drivers" or "update design drivers"
- User asks about architecture documentation structure or best practices
- User edits Section 1 Executive Summary Key Metrics (triggers metric consistency check)
- User edits any downstream section (S4–S11) → triggers Context Anchor load
- User requests metric consistency check, verify metrics, or audit metrics
- **User asks informational questions about the documented architecture** (if ARCHITECTURE.md exists)
  - "What is our [authentication/scaling/data flow/etc.] approach?"
  - "How does [component/system/integration] work?"
  - "What technologies do we use for [purpose]?"
  - "Tell me about the architecture of [system]"
- **User asks to generate, create, add, or update diagrams in architecture documentation** (triggers Workflow 8)
  - "Generate my architecture diagrams"
  - "Create Mermaid diagrams from ARCHITECTURE.md"
  - "Add diagrams to my architecture"
  - "Update my architecture diagrams"
  - "Refresh / regenerate diagrams to reflect recent changes"
- **User asks to release, freeze, or tag an architecture version** (triggers Workflow 10)
  - "Release architecture version"
  - "Bump architecture to v1.2.0"
  - "Freeze architecture baseline"
  - "Tag architecture version"

### Version Drift Detection (informational, every invocation)

On any invocation of this skill, if `ARCHITECTURE.md` contains a `<!-- ARCHITECTURE_VERSION: -->` comment AND the project is under git:

1. Read the doc version from the comment
2. Run `git tag -l 'architecture-v*' --sort=-version:refname | head -1` to get the latest `architecture-v*` tag
3. If doc version > latest tag: emit `ℹ️ Architecture v{doc} is not tagged in git. Run Workflow 10 (Release Architecture Version) to publish a tag.`
4. If doc version < latest tag: emit `⚠️ Architecture tag architecture-v{tag} exists in git but the doc shows v{doc}. Possible regression — verify before committing.`
5. If doc version == latest tag: silent (no message)

Drift detection is **informational only** — it does not block other workflows. See `RELEASE_WORKFLOW.md` → "Drift Detection" for full details.

### Query Pattern Triggers

This skill automatically activates when users ask questions about documented architecture, including:

**Reference Patterns**:
- "According to my architecture documentation..."
- "Based on the architecture..."
- "What does the architecture use/require/implement for..."
- "My architecture documentation shows/says..."
- "The architecture specifies/defines..."
- "Check/Validate/Verify the architecture [aspect]..."
- "Audit the [architecture component/pattern]..."

**Technical Query Keywords**:
- **Components**: "components", "services", "modules", "microservices", "systems"
- **Data**: "data structures", "data flow", "database", "schema", "models", "entities"
- **Integration**: "APIs", "integrations", "external systems", "endpoints", "interfaces"
- **Security**: "authentication", "authorization", "encryption", "security", "compliance"
- **Performance**: "scaling", "performance", "SLA", "capacity", "throughput", "latency"
- **Deployment**: "deployment", "cloud provider", "infrastructure", "environments", "regions"
- **Technology**: "tech stack", "languages", "frameworks", "tools", "libraries", "versions"
- **Decisions**: "why choose", "decision", "trade-offs", "alternatives", "ADR", "rationale"
- **Validation**: "check", "validate", "verify", "audit", "alignment", "BIAN", "META", "service domain", "layer", "standards", "compliance check"

**Multi-section Queries**:
- Questions requiring synthesis across multiple sections
- Cross-cutting concerns (e.g., "How does authentication work with external systems?")
- Implementation details spanning components, data, and deployment

**Do NOT activate for** (redirect to the correct skill):
- Requirements deviation checks, requirements traceability, or PO Spec coverage analysis → use `architecture-traceability` skill
- Component migration to C4, component index sync, add/remove/update components → use `architecture-component-guardian` skill
- Peer review or architecture quality assessment → use `architecture-peer-review` skill
- Compliance contract generation → use `architecture-compliance` skill

**Component Operations Delegation Rule**:
All structural operations on `docs/components/` MUST delegate to `architecture-component-guardian`:
- Creating, renaming, or deleting component files → delegate to guardian
- Creating or updating `docs/components/README.md` → delegate to guardian (`sync` action)
- Migrating flat components to C4 multi-system structure → delegate to guardian (`migrate` action)
- Adding C4 metadata (Type, C4 Level, system folders) → delegate to guardian
This skill may **read** component files for context (editing sections, propagation checks) but must NOT directly create, restructure, or modify the component index.

---

## 🎯 AUTOMATIC WORKFLOW DETECTION

**IMPORTANT**: Immediately upon skill invocation, analyze the user's request to detect their intent.

### Detection Logic

Check the user's original message (before `/architecture-docs` was invoked) for these patterns:

#### Workflow 8: Diagram Generation
**Triggers:**
- Keywords: "generate", "create", "add", "update", "make" + "diagram", "diagrams", "Mermaid diagram", "architecture diagram"
- Examples: "generate my architecture diagrams", "create diagrams from ARCHITECTURE.md", "add diagrams to my architecture"
- Section-specific: "generate diagrams for Section 4", "create data flow diagrams"
- Format mentions: "Mermai