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 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tikalk/adlc-team-skills --skill architect-analyze技能说明
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:
- ADR Quality — Completeness, clarity, and standards compliance
- ADR to AD Consistency — Bidirectional drift detection
- Internal Consistency — Cross-artifact coherence
- 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:
| Document | Location | Purpose |
|---|---|---|
AD.md | Project root | Full 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
- Initialize Analysis Context — Load architecture artifacts
- Determine Analysis Scope — System, feature, or full
- Execute Detection Passes — A through G
- Assign Severities — CRITICAL/HIGH/MEDIUM/LOW
- Generate Report — Structured markdown analysis
- Provide Next Actions — Remediation suggestions
Phase 1: Initialize Analysis Context
Objective: Load all architecture artifacts for analysis
-
Run Setup Script:
- Execute
scripts/bash/setup-architect.shfrom repo root - Parse JSON for file paths and existence status
- Execute
-
Load System-Level Artifacts:
- Read
AD.md(project root) if exists - Read ADRs from all locations (priority order):
{REPO_ROOT}/.adlc/memory/adr/adr.md(canonical — Accepted ADRs){REPO_ROOT}/.adlc/drafts/adr/(working copy — Proposed/Discovered, individual file format)
- Read
{REPO_ROOT}/.adlc/memory/constitution.mdif exists
- Read
-
Load Feature-Level Artifacts (if analyzing features):
- Scan
specs/*/AD.mdfor feature architectures - Scan
specs/*/adr/ADR-*.mdfor feature ADRs
- Scan
-
Build Artifact Inventory:
Artifact Path Status System AD AD.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 ADs specs/*/AD.mdCount: 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, forces documented | MEDIUM |
| Decision | Actionable, testable decision statement | HIGH |
| Positive Consequences | Benefits documented | MEDIUM |
| Negative Consequences | Trade-offs acknowledged | HIGH |
| Risks | Identified with mitigations | MEDIUM |
| Alternatives | At least 2 options with neutral trade-offs | HIGH |
| Status | Valid status (Proposed/Accepted/Deprecated/Superseded/Discovered) | LOW |
| Constitution Alignment | MUST principles complied with | CRITICAL |
ADR Quality Checklist:
For each ADR, verify:
- Clear context explaining the prob