/architect-analyze

name: architect-analyze
description: Use when validating generated or refined architecture artifacts, before feature development, during architecture review, or periodically to detect ADR↔AD drift, completeness gaps, and quality issues.
disable-model-invocation: true

architect-analyze

What this skill does

Performs a **read-only** architecture consistency analysis between ADRs (Architecture Decision Records) and AD (Architecture Description). It identifies discrepancies, quality issues, and gaps without modifying any files.

Key analysis dimensions:

1. **ADR Quality** — Completeness, clarity, and standards compliance 2. **ADR to AD Consistency** — Bidirectional drift detection 3. **Internal Consistency** — Cross-artifact coherence 4. **Staleness Detection** — Outdated references and placeholders 5. **Mermaid Syntax** — Deterministic validity check over diagram blocks, with location + suggested patch (the mermaid detection pass)

This skill validates architecture artifacts for consistency, completeness, and quality.

When to use

• After `/architect-implement` — Validate generated AD.md
• After `/architect-clarify` — Verify ADR refinements
• Before feature development — Ensure architecture is solid
• During architecture review — Quality gate for architecture docs
• Periodically — Detect drift as the codebase evolves

Do **not** use when no architecture artifacts exist; use `/architect-init` or `/architect-specify` first. Do **not** use to create architecture — this is analysis-only.

Process

User Input

Consider the user input before proceeding (if not empty):

$ARGUMENTS

Examples:

• `"system"` — Focus on root-level AD.md and adr/ directory only
• `"feature auth"` — Focus on specific feature architecture
• `"adrs"` — Focus on ADR quality and inter-ADR consistency
• `"views"` — Focus on AD.md view completeness and internal consistency
• Empty input — Full analysis of all architecture artifacts

Goal

Perform read-only architecture consistency analysis. Identify discrepancies, quality issues, and gaps without modifying any files.

Operating Constraints

**STRICTLY READ-ONLY**: Do not modify any files. Output a structured analysis report. Offer remediation suggestions (user must explicitly approve before any follow-up editing commands would be invoked manually).

**Constitution Authority**: The project constitution (`memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL.

Role & Context

Act as an **Architecture Analyst** validating architecture documentation quality:

• Validate ADR completeness against MADR standards
• Detect drift between ADRs and AD.md
• Identify internal inconsistencies across artifacts
• Flag staleness and quality issues

Architecture document hierarchy:

| Document | Location | Purpose | |----------|----------|---------| | `AD.md` | Project root | Full Architecture Description (Rozanski & Woods) | | `adr/` | `{REPO_ROOT}/docs/adlc/memory/` (legacy `.adlc/memory/` fallback) | System-level ADRs (individual files) | | `constitution.md` | `{REPO_ROOT}/docs/adlc/memory/` (legacy `.adlc/memory/` fallback) | Governance principles and constraints |

Outline

1. **Initialize Analysis Context** — Load architecture artifacts 2. **Determine Analysis Scope** — System, feature, or full 3. **Execute Detection Passes** — A through G 4. **Assign Severities** — CRITICAL/HIGH/MEDIUM/LOW 5. **Generate Report** — Structured markdown analysis 6. **Provide Next Actions** — Remediation suggestions

Phase 1: Initialize Analysis Context

**Objective**: Load all architecture artifacts for analysis

1. **Run Setup Script**:

• Execute `{REPO_ROOT}/.agents/skills/architect-clarify/scripts/bash/setup-architect.sh` (Requires the `architect-clarify` skill: `adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify`). from repo root
• Parse JSON for file paths and existence status

2. **Load System-Level Artifacts**:

• Read `AD.md` (project root) if exists
• Read ADRs from all locations (priority order):

1. `{REPO_ROOT}/docs/adlc/memory/adr/adr.md` (canonical — Accepted ADRs; legacy `{REPO_ROOT}/.adlc/memory/adr/adr.md` fallback per dual-read) 2. `{REPO_ROOT}/.adlc/drafts/adr/` (working copy — Proposed/Discovered, individual file format)

• Read `{REPO_ROOT}/docs/adlc/memory/constitution.md` (legacy `{REPO_ROOT}/.adlc/memory/constitution.md` fallback) if either exists

3. **Load Feature-Level Artifacts** (if analyzing features):

• Scan `specs/*/AD.md` for feature architectures
• Scan `specs/*/adr/ADR-*.md` for feature ADRs

4. **Build Artifact Inventory**:

| Artifact | Path | Status | |----------|------|--------| | System AD | `AD.md` | Found/Missing | | System ADRs (canonical) | `{REPO_ROOT}/docs/adlc/memory/adr/adr.md` (legacy `.adlc/memory/adr/adr.md` fallback) | Found/Missing | | System ADRs (drafts) | `{REPO_ROOT}/.adlc/drafts/adr/` | Found/Missing | | Constitution | `{REPO_ROOT}/docs/adlc/memory/constitution.md` (legacy `.adlc/memory/constitution.md` fallback) | Found/Missing | | Feature ADs | `specs/*/AD.md` | Count: N | | Feature ADRs | `specs/*/adr/` | Count: N |

Phase 2: Determine Analysis Scope

**Objective**: Focus analysis based on user input

| User Input | Scope | Artifacts Analyzed | |------------|-------|-------------------| | (empty) | Full | All system artifacts | | `"system"` | System only | AD.md, system ADR locations | | `"adrs"` | ADR quality | All ADR files | | `"views"` | AD completeness | AD.md |

Phase 3: Execute Detection Passes

Focus on high-signal findings. Limit to **50 findings total**; aggregate remainder in overflow summary.

Pass A: ADR Quality Analysis

**Objective**: Validate each ADR against MADR standards

**Quality Dimensions**:

| Dimension | Check | Severity if Missing | |-----------|-------|---------------------| | Context | Problem clearly stated,