Architecture Docs

Architecture Documentation Skill

This skill provides comprehensive guidelines for creating and maintaining ARCHITECTURE.md files using the standardized template from ARCHITECTUREDOCUMENTATIONGUIDE.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 `` 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 /dev/null

**1d. Handoff scan** — For each fact-delta keyword (component names, technology names, pattern names), grep `handoffs/` for matching terms.

**1e. Merge and deduplicate** — Combine results from 1b+1c+1d. Remove duplicates and remove the edited file itself.

#### Phase 1.5: Principle Alignment Audit (S3 edits only)

Runs **only** when the edited file is `docs/02-architecture-principles.md` AND Phase 1a's fact-delta extraction reported substantive word-level changes in any of {Description, Implementation, Trade-offs} subsections.

**Trigger gate** — skip Phase 1.5 silently when:
- The diff contains only whitespace, punctuation, link reformatting, or markdown structure changes (no word-level changes inside D/I/T blocks).
- The Section 3 Enforcement Gate above failed and the principles file was regenerated wholesale (the regenerated file is treated as a first-write, not an edit, and the orchestrator already re-ran the gate).
- Phase 1a's diff is empty (no substantive changes detected).

**Audit procedure** when the gate fires:

1. **Extract per-principle deltas** from the diff. For each principle that changed, capture:
   - `principleNumber`, `principleName`
   - Which subsection(s) changed (Description / Implementation / Trade-offs)
   - A 1-line summary of the change (what was added, removed, or rephrased)
   - **Token set for pruning** — derived from the *raw* added/removed lines of the changed subsections (not from the 1-line summary). Build a single de-duplicated set containing:
     - **Principle names** — the `principleName` of every changed principle.
     - **ADR IDs** — every `ADR-NNN` token (regex `ADR-\d{3}`) that appears in either the before-text or the after-text of changed Description / Implementation / Trade-offs subsections.
     - **Affected tech tokens** — every named tech term that appears on an added or removed diff line AND is enumerated in `docs/06-technology-stack.md` (i.e., a tech this system actually uses). Intersecting with the tech stack avoids matching English words that happen to be tech-name-shaped. Compare case-insensitive on whole-token boundaries.

   This token set powers the pruning step below; if the set ends up empty (e.g., the diff only rephrased Description prose with no concrete principle names, ADR IDs, or system-tech tokens) the fall-back is conservative — fan out to all candidates without pruning.

2. **Pre-fan-out pruning** — Token-grep each candidate downstream file against the token set from step 1 to drop files with zero references to anything that changed. The reviewer is Opus and the median S3 edit touches one principle's Implementation, so most downstream files don't even mention the changed content. Skipping them on the basis of a cheap structural grep avoids spending Opus on guaranteed `NO_IMPACT` verdicts.

   **Candidate set** = the reverse dependency files for S3 (S4–S11 + every `docs/components/**/*.md` listed in `docs/components/README.md`).

   **Pruning rule (per candidate file):**
   - If the token set from step 1 is empty → KEEP the file (conservative: nothing concrete to grep against; fall through to fan-out).
   - Else, run a single composite case-insensitive grep over the file using a regex alternation of every token in the set (escape regex metacharacters in principle names; whole-line match is fine — we only need a hit/no-hit signal). Examples:
     ```bash
     grep -liE 'Principle Name 1|Principle Name 4|ADR-005|ADR-012|Spring Boot|PostgreSQL|Redis' \
       docs/03-architecture-layers.md docs/04-data-flow-patterns.md \
       docs/05-integration-points.md docs/06-technology-stack.md \
       docs/07-security-architecture.md docs/08-scalability-and-performance.md \
       docs/09-operational-considerations.md docs/components/*.md
     ```
   - File path emitted by grep → KEEP for the fan-out in step 3.
   - File NOT emitted → SKIP. Record one Phase 2 note for the user:
     ```
     ℹ️  {file} — no token references to changed principles, cited ADRs, or affected tech; semantic review skipped (Phase 1.5 pruning).
     ```

   **Empty kept-set after pruning** — when zero candidate files token-match (and the token set was non-empty, so the prune was real), emit one consolidated Phase 2 note ("Principle Alignment Audit: no downstream files reference any of the changed principles, cited ADRs, or affected tech — nothing to review.") and skip steps 3–6 of this Audit procedure. Phase 2 still runs with the structural impact list from Phase 1b–1d.

   **Fail-open** — if `grep` is unavailable or returns an unexpected error, emit a one-line Phase 2 warning ("Phase 1.5 pruning unavailable; fanned out to the full candidate set") and fall through to step 3 with all candidates kept. Pruning is an optimization, not a gate.

   **Why this is recall-safe** — the token set includes principle names AND cited ADR IDs AND affected tech, all three. Most "implicit contradiction" cases (a downstream file paraphrases a principle without naming it) still surface because the file usually mentions either the cited ADR or the affected tech. The conservative empty-set fallback covers the long tail (pure prose changes with no concrete tokens).

3. **Fan out to `principle-quality-reviewer`** in `mode: downstream-impact`. The orchestrator MUST construct the sub-agent prompt using the **stable-prefix → dynamic-suffix template** below so parallel calls in the same batch share the maximum cacheable prefix (Anthropic prompt cache hits on byte-identical prefixes within the 5-min TTL).

   **Read-once foundational context.** Before dispatching any sub-agent in this fan-out, read the four foundational files **once** in the orchestrator's session and capture their content. The five blocks below are byte-identical across every sub-agent call in the fan-out, so inlining them lets calls 2..N hit the prompt cache for the entire prefix instead of each agent re-Reading the same files independently:

   - `docs/02-architecture-principles.md` (post-edit) → `` block
   - `docs/01-system-overview.md` → `` block
   - `docs/03-architecture-layers.md` → `` block
   - `docs/06-technology-stack.md` → `` block
   - `Glob('adr/*.md')` ID list (one `ADR-NNN` per line, sorted) → `` block (the IDs alone — bodies are not needed for existence checks)

   **Prompt template** — positional, order must not change. Lines above the marker are stable across the batch; only `downstream_file` (last line) differs per call:

   ```
   mode: downstream-impact
   round: 
   arch_type: 
   principles_file: docs/02-architecture-principles.md
   principles_diff: |
     

   
   {full content of docs/02-architecture-principles.md (post-edit)}
   

   
   {full content of docs/01-system-overview.md}
   

   
   {full content of docs/03-architecture-layers.md}
   

   
   {full content of docs/06-technology-stack.md}
   

   
   {one ADR-NNN id per line, sorted}
   

   # === Stable prefix ends here. Only the line below differs per call. ===

   downstream_file: {absolute path to the specific downstream file under audit}
   ```

   The agent's Step 1 consumes the five inlined blocks directly — it does NOT re-Read the four foundational files when the blocks are present. See `agents/reviewers/principle-quality-reviewer.md` Step 1 (Inlined-blocks fast path) for the consumption contract.

   **Why the order matters**: Anthropic's prompt cache is a prefix matcher. Any per-call discriminator above the marker would split the cache and force every parallel call to be a cache miss. Keep `downstream_file` as the LAST line; keep `principles_diff` and the five inlined blocks above it; keep them in the order shown so all calls in the batch share a byte-identical prefix.

   **Backward compatibility**: when running the reviewer outside this orchestrator (e.g., direct invocation, older callers), the agent still accepts path-only inputs and falls back to `Read` / `Glob`. The path parameters (`system_overview_file`, `arch_layers_file`, `tech_stack_file`, `adr_index_glob`) remain in the prompt as fallback values; they are ignored when the inlined blocks are present.

   **Parallelism**: dispatch in batches of 4 (mirrors v3.16.0 explorer fan-out pattern). Wait for each batch before starting the next.

   **Cache-warm sequencing (first batch only)**: in the FIRST batch of any Phase 1.5 fan-out, fire **one** sub-agent call first and wait for its response to settle before firing the remaining 1–3 calls in parallel. The first call's response writes the byte-identical stable prefix (the five inlined blocks above) into Anthropic's prompt cache; the remaining calls in that batch — and every call in every subsequent batch within the 5-min cache TTL — read the prefix from cache instead of re-paying it. After the first batch completes, dispatch subsequent batches normally (full parallel of 4); the cache is already warm.

   The latency cost is one extra serialized call (~30–60s) paid only on the first batch of each Phase 1.5 fan-out. For typical S3 edits where step 2 pruning leaves 2–4 candidate files, this adds /` exists and contains any of the matched asset types. Exclude components with no asset directory or no matching asset files on disk.

If zero components remain after filtering → skip silently.

**Step 5c — Present advisory**:

─────────────────────────────────────────────────────────── ASSET REGENERATION ADVISORY ───────────────────────────────────────────────────────────

The propagation above updated handoff document text, but the following scaffolded assets may now be stale:

Component: {component-name} → openapi.yaml (changes mention: endpoint, API) → ddl.sql (changes mention: table, column)

Component: {component-name-2} → deployment.yaml (changes mention: container, port)

These assets were generated by the dev-handoff skill and contain structured specs derived from architecture docs. In-place text patches do not regenerate them.

Would you like to regenerate handoff documents and assets for the affected components?

[Yes] → I will provide the commands to run [No] → No action needed right now

Note: You can regenerate all handoffs at any time with: /skill architecture-dev-handoff ───────────────────────────────────────────────────────────

If propagation was **skipped**: prepend to the advisory:
> `Note: Propagation was skipped — handoff document text was also not updated. Full regeneration is recommended.`

**Wait for user response.**

- **Yes** → Display one line per affected component: `Run: /skill architecture-dev-handoff` (for each affected component by name). Do NOT invoke the skill automatically.
- **No** → Acknowledge and proceed with no further action.

---

6. **Verification**
   - After edits, re-read the modified `docs/` file to verify changes
   - Use Grep to search for specific content without loading multiple files

### Discovering Available Files

When the target section is not obvious, read `ARCHITECTURE.md` first:

```python
# Step 1: Read navigation table
nav_content = Read(file_path="ARCHITECTURE.md")

# Step 2: Parse the Documentation table to find the target file
# Example row: | 8 | Security Architecture | [docs/07-security-architecture.md](docs/07-security-architecture.md) | ... |

# Step 3: Read that specific docs/ file in full
target_content = Read(file_path="docs/07-security-architecture.md")

Technology Context Enrichment (context7) — Component Documentation

When creating NEW component documentation (Workflow 1, Section 5), and the component's Technology field references specific frameworks, libraries, or tools, use the context7 MCP tool to fetch current documentation for those technologies.

Prerequisite: The context7 MCP tool must be available (resolve-library-id and get-library-docs functions

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shadowX4fox
• Source: shadowX4fox/solutions-architect-skills
• License: MIT

Install and usage instructions live in the source repository linked above.