architect-analyze

Scope rule: scripts stay skill-local — never source a script from another skill. For another skill's operations, invoke that skill (e.g. architect-clarify, product-clarify, team-boot) via the Skill tool; for its documents, follow the Requires line. scripts/ and references/ below are relative to this skill. {REPO_ROOT} denotes the project root (where .adlc/ lives).

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:

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:
   • Invoke the architect-clarify skill to load architecture artifacts (Requires that skill: adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify)
   • 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

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:

ADR Quality Checklist:

For each ADR, verify:

• Clear context explaining the problem/opportunity
• Explicit, actionable decision statement
• Positive AND negative consequences documented
• Common Alternatives with neutral trade-offs (not "Rejected because")
• Risks identified with mitigation strategies
• Valid status value
• No conflicts with constitution MUST principles

Pass B: Inter-ADR Consistency

Objective: Detect conflicts and inconsistencies between ADRs

Checks:

1. Conflicting Decisions:
   • ADRs that contradict each other (e.g., one chooses PostgreSQL, another assumes MongoDB)
   • Technology stack incoherence
2. Missing Dependencies:
   • ADRs that should reference each other but don't
   • Implicit assumptions about other decisions
3. Terminology Drift:
   • Same concept named differently across ADRs
   • Inconsistent component naming
4. Technology Stack Coherence:
   • Frontend/backend/infrastructure choices align
   • No conflicting framework decisions

Pass C: ADR to AD Drift (Forward Sync)

Objective: Detect ADR decisions not reflected in AD.md

Checks:

Detection Logic:

For each ADR:

1. Identify the ADR's primary view impact (use mapping table above)
2. Search AD.md for reflection of that decision
3. Flag if decision is absent or contradicted

Pass D: AD to ADR Drift (Backward Sync)

Objective: Detect AD.md elements without supporting ADRs

Checks:

1. Components Without ADRs:
   • Major components shown in Functional View without decision rationale
   • External dependencies in Context View without ADR justification
2. Patterns Without Rationale:
   • Architectural patterns described but not explained via ADR
   • Technology choices embedded in views without supporting decision
3. Infrastructure Decisions:
   • Deployment topology without infrastructure ADR
   • Scaling approach without performance ADR

Pass E: AD Internal Consistency

Objective: Validate AD.md coherence across views

Checks:

1. Cross-View Consistency:
   • Same components named identically across all views
   • Data entities in Information View match Functional View references
   • Deployment nodes consistent with Functional components
2. Diagram-Text Alignment:
   • Mermaid diagrams match prose descriptions
   • No components in diagrams missing from text
   • No components in text missing from diagrams
3. View Completeness:
   • Required sections present (Introduction, Stakeholders, Views, Perspectives)
   • Core views included (Context, Functional, Information, Development, Deployment)
   • Perspectives addressed (Security, Performance)
4. Diagram Syntax Validation (deterministic — the mermaid detection pass):
   • Mermaid syntax valid (no broken diagrams)
   • Consistent styling across diagrams

   • Run the shared validator; it produces one finding per broken block with severity, location (file + line + fence index) and a suggested patch:

     Invoke the `architect-clarify` skill to run the shared mermaid validator (Requires that skill: `adlc-cli skills add tikalk/adlc-team-skills --skill architect-clarify`)

     The rule set is documented once, in the validator itself — read it there rather than re-deriving the rules here. Exit code: 0 clean, 1 a HIGH (syntax-break) is present, 2 only MEDIUM (style) findings. An unrecognised diagram type is MEDIUM, never HIGH: this rule set must not produce a false syntax break. The pass is read-only (the lifecycle write scope) — remediation belongs to /architect-implement or a human.

5. View File Consistency (DAG State Validation):
   • Check if .adlc/architect/state.json exists and reports views as "completed"
   • Check if docs/adlc/architect/views/ (legacy .adlc/architect/views/ fallback) directory exists
   • Verify that for each "completed" view in state.json, a corresponding file exists on disk
   • Flag as HIGH severity if:
     • state.json reports views "completed" but views/ directory is empty
     • View files exist but are under 20 lines (placeholder/skeleton content)
     • View files cannot be read (corrupted/missing permissions)
   • Report format:

     DAG State Inconsistency Detected:
     - State reports: [N] views completed
     - Files on disk: [M] view files found
     - Missing files: [list of missing views]
     - Recommendation: Regenerate views or reset state.json

6. Technology Neutrality (Functional View):
   • Scan Functional View (§3.2) for product/vendor names in element descriptions and Mermaid diagrams
   • Architectural roles (acceptable): Database, Object Storage, Cache, Message Queue, AI Gateway, Workflow Runtime, App Shell, API Gateway, Authentication Service, etc.
   • Product names (flag as MEDIUM): PostgreSQL, Neon, Vercel, Next.js, Redis, MongoDB, AWS, Azure, S3, etc.
   • Severity: MEDIUM — Not blocking but indicates abstraction violation
   • Note: ADR Traceability sections may reference products (that's acceptable); only flag element descriptions and diagram labels
7. Functional-Development Mapping:
   • Verify Development View (§3.5) contains a Technology Stack Mapping table (§3.5.2)
   • Check that every element in Functional View's element table (§3.2.1) has at least one corresponding entry in the mapping table
   • N:1 mappings (multiple functional elements → one technology) are acceptable
   • Severity: MEDIUM if elements are missing; LOW if mapping table is absent
   • Cross-check: Technology Architecture diagram (§3.5.3) should mirror Functional View diagram (§3.2.2) structure

Pass F: Staleness Detection

Objective: Identify outdated references and placeholders

Checks:

1. Deprecated ADRs Still Referenced:
   • AD.md references ADRs with status "Deprecated"
   • Superseded decisions still implemented
2. Placeholder Detection:
   • [TODO], [TBD], [PLACEHOLDER] markers
   • [SYSTEM_NAME], [STAKEHOLDER_*] unfilled
   • ???, ..., <placeholder> patterns
3. Date Inconsistencies:
   • ADR dates significantly older than AD last-updated
   • Feature architecture out of sync with system architecture
4. Orphaned References:
   • ADR IDs mentioned but ADR doesn't exist
   • Component names referenced but not defined

Pass G: Feature-System Alignment (if feature architecture exists)

Objective: Validate feature architecture fits within system boundaries

Checks:

1. Feature ADR Alignment:
   • Feature ADRs marked "Aligns with ADR-XXX" reference valid system ADRs
   • No VIOLATION flags without documented justification
   • Feature decisions consistent with system constraints
2. Boundary Compliance:
   • Feature components fit within system Functional View structure
   • Feature data entities align with system Information View
   • Feature doesn't exceed system scope (Context View)
3. Integration Points:
   • Feature-to-system interfaces documented
   • Data flow across feature boundary consistent

Phase 4: Severity Assignment

Severity Criteria:

Phase 5: Generate Analysis Report

Output Format:

## Architecture Analysis Report

### Analysis Summary

| Attribute | Value |
|-----------|-------|
| **Mode** | [Full/System/Feature/ADRs/Views] |
| **Scope** | [Description of what was analyzed] |
| **Files Analyzed** | [List of files] |
| **Analysis Date** | [Current date] |

### Findings

| ID | Pass | Severity | Location | Summary | Recommendation |
|----|------|----------|----------|---------|----------------|
| A1 | ADR Quality | MEDIUM | ADR-003 | Missing negative consequences | Add trade-offs section |
| B1 | Inter-ADR | HIGH | ADR-002, ADR-005 | Conflicting database choices | Resolve PostgreSQL vs MongoDB conflict |
| C1 | ADR->AD Drift | HIGH | ADR-005 | Caching decision not in Information View | Update AD.md 3.3 |
| D1 | AD->ADR Drift | HIGH | AD.md:3.2 | Redis component has no ADR | Create ADR for cache choice |
| E1 | AD Consistency | MEDIUM | AD.md:3.2/3.6 | Component naming mismatch | Standardize "AuthService" naming |
| F1 | Staleness | LOW | AD.md:3.1 | [SYSTEM_NAME] placeholder | Fill in system name |
| G1 | Feature Align | HIGH | specs/auth/adr.md | VIOLATION flag unresolved | Document override justification |

### Coverage Metrics

| Metric | System | Feature: auth | Feature: payments |
|--------|--------|---------------|-------------------|
| ADR Count | 13 | 3 | 2 |
| AD Views Complete | 5/7 | 3/5 | 3/5 |
| ADR->AD Coverage | 85% | 100% | 67% |
| AD->ADR Coverage | 92% | 100% | 100% |
| Quality Score | 78% | 85% | 72% |

### Constitution Alignment

| Status | Count | Details |
|--------|-------|---------|
| Compliant | [N] | ADRs following MUST principles |
| Violations | [N] | ADRs violating MUST principles (CRITICAL) |
| Deviations | [N] | Justified SHOULD principle deviations |

### Issue Distribution

| Severity | Count |
|----------|-------|
| CRITICAL | [N] |
| HIGH | [N] |
| MEDIUM | [N] |
| LOW | [N] |

### Next Actions

Based on findings, recommended actions:

**If CRITICAL issues exist:**
- **Immediate**: Resolve constitution violations before proceeding
- Command: `/architect-clarify` to address ADR compliance

**If HIGH ADR quality issues:**
- **Refine**: Address missing alternatives and consequences
- Command: `/architect-clarify` to improve ADR quality

**If ADR->AD drift detected:**
- **Sync AD**: Update AD.md to reflect ADR decisions
- Command: `/architect-implement` to regenerate views

**If AD->ADR drift detected:**
- **Document**: Create missing ADRs for undocumented decisions
- Command: `/architect-specify` or `/architect-init` to add ADRs

**If feature alignment issues:**
- **Align**: Resolve feature-system boundary violations
- Command: Run `/architect-specify` or `/architect-init` to create missing ADRs

Phase 6: Offer Remediation

After presenting the report, ask:

"Would you like me to suggest specific remediation steps for the top [N] issues? I can provide detailed guidance for each finding, though I will not make any changes automatically."

Key Rules

Analysis Integrity

• NEVER modify files — this is read-only analysis
• NEVER hallucinate missing content — report absences accurately
• Prioritize constitution violations — these are always CRITICAL
• Use evidence-based findings — cite specific locations and content

Consistency Standards

• Cross-reference everything — validate bidirectionally (ADR to AD)
• Check all levels — system and feature architecture must align
• Validate terminology — same concepts must use same names
• Verify diagrams — Mermaid syntax must be valid

Reporting Standards

• Limit to 50 findings — aggregate overflow in summary
• Include location — always cite file:line or section
• Provide actionable recommendations — each finding gets a fix suggestion
• Calculate coverage metrics — quantify completeness

Next Steps

If issues are found:

• Run /architect-clarify to refine ADRs (quality issues, missing consequences/alternatives, constitution violations).
• Run /architect-implement to regenerate AD.md when ADR-to-AD drift is detected.

For missing ADRs or feature boundary issues, use /architect-specify or /architect-init as appropriate.

Verification

Concrete outputs of this skill:

• Architecture Analysis Report in structured markdown, including:
  • Analysis Summary (mode, scope, files analyzed, analysis date)
  • Findings table with ID, pass, severity, location, summary, and recommendation
  • Coverage Metrics (ADR count, AD views complete, ADR→AD coverage, AD→ADR coverage, quality score)
  • Constitution Alignment summary (compliant, violations, deviations)
  • Issue Distribution by severity (CRITICAL, HIGH, MEDIUM, LOW)
  • Next Actions tailored to finding types
• Mermaid syntax validation run over the AD and every artifact carrying diagrams (shared linter, the mermaid detection pass) — every broken block reported with severity, location and a suggested patch.
• No files modified — analysis is strictly read-only.
• User-approved remediation guidance offered after the report.