Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

architect-analyze

Analyze architecture for consistency between ADRs and AD, completeness, and quality issues. Use when validating generated or refined architecture artifacts, before feature development, during architecture review, or periodically to detect drift.

tikalk · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add tikalk/adlc-team-skills --skill architect-analyze

About this skill


name: architect-analyze description: Analyze architecture for consistency between ADRs and AD, completeness, and quality issues. Use when validating generated or refined architecture artifacts, before feature development, during architecture review, or periodically to detect drift. 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

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:

DocumentLocationPurpose
AD.mdProject rootFull Architecture Description (Rozanski & Woods)
adr/{REPO_ROOT}/.adlc/memory/System-level ADRs (individual files)
constitution.md{REPO_ROOT}/.adlc/memory/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 scripts/bash/setup-architect.sh 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}/.adlc/memory/adr/adr.md (canonical — Accepted ADRs)
      2. {REPO_ROOT}/.adlc/drafts/adr/ (working copy — Proposed/Discovered, individual file format)
    • Read {REPO_ROOT}/.adlc/memory/constitution.md if 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:

    ArtifactPathStatus
    System ADAD.mdFound/Missing
    System ADRs (canonical){REPO_ROOT}/.adlc/memory/adr/adr.mdFound/Missing
    System ADRs (drafts){REPO_ROOT}/.adlc/drafts/adr/Found/Missing
    Constitution{REPO_ROOT}/.adlc/memory/constitution.mdFound/Missing
    Feature ADsspecs/*/AD.mdCount: N
    Feature ADRsspecs/*/adr/Count: N

Phase 2: Determine Analysis Scope

Objective: Focus analysis based on user input

User InputScopeArtifacts Analyzed
(empty)FullAll system artifacts
"system"System onlyAD.md, system ADR locations
"adrs"ADR qualityAll ADR files
"views"AD completenessAD.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:

DimensionCheckSeverity if Missing
ContextProblem clearly stated, forces documentedMEDIUM
DecisionActionable, testable decision statementHIGH
Positive ConsequencesBenefits documentedMEDIUM
Negative ConsequencesTrade-offs acknowledgedHIGH
RisksIdentified with mitigationsMEDIUM
AlternativesAt least 2 options with neutral trade-offsHIGH
StatusValid status (Proposed/Accepted/Deprecated/Superseded/Discovered)LOW
Constitution AlignmentMUST principles complied withCRITICAL

ADR Quality Checklist:

For each ADR, verify:

  • Clear context explaining the prob
Read the complete source ↗