architect-clarify
Refine and validate system-level ADRs through targeted clarification questions. Use when ADRs need review, gaps need filling, or ADR status must be approved before architecture generation.
tikalk · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tikalk/adlc-team-skills --skill architect-clarify技能说明
name: architect-clarify description: Refine and validate system-level ADRs through targeted clarification questions. Use when ADRs need review, gaps need filling, or ADR status must be approved before architecture generation. disable-model-invocation: true
architect-clarify
What this skill does
Identify underspecified areas in existing ADRs and refine them through targeted clarification questions. Ensure ADRs are complete, consistent, and ready for architecture generation.
You act as an Architecture Reviewer ensuring ADR quality by:
- Validating ADR completeness against MADR standards
- Identifying gaps in consequences or alternatives
- Detecting conflicts between ADRs or with constitution
- Refining decisions through targeted clarification
When to use
Use this skill:
- After
/architect-init: Refine initial ADRs before architecture generation - ADR Review: Validate ADRs before major milestones
- New Team Member: Ensure ADRs make sense to fresh eyes
- Conflict Resolution: Resolve identified inconsistencies
Do not use this skill when:
- No ADRs exist: Use
/architect-initfirst to create ADRs - Brownfield projects: Use
/architect-initto reverse-engineer ADRs from code
Process
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Examples of User Input:
"Focus on data architecture decisions - we're reconsidering database choice""Security ADRs need more detail for compliance review""ADR-003 consequences seem incomplete"- Empty input: Review all ADRs for completeness
Goal
Identify underspecified areas in existing ADRs and refine them through targeted clarification questions. Ensure ADRs are complete, consistent, and ready for architecture generation.
ADR Quality Checklist
Each ADR should have:
- Clear context explaining the problem/opportunity
- Explicit decision statement
- Positive AND negative consequences
- Common Alternatives documented (neutral trade-offs, not "Rejected because")
- Risks identified with mitigation strategies
- Status is accurate (Proposed/Accepted/Deprecated/Superseded/Discovered)
- No conflicts with other ADRs
- Alignment with constitution principles
- No fabricated rejection rationale for reverse-engineered ADRs
Outline
- Load Current State: Parse ADRs from
{REPO_ROOT}/.adlc/drafts/adr/(individual file format) and{REPO_ROOT}/.adlc/memory/constitution.md
IMPORTANT - Path Resolution:
- The setup script outputs
REPO_ROOT- use this to determine the correct paths - REPO_ROOT is found by searching upward from current directory for
.adlcdirectory - NEVER use relative paths like
.adlc/drafts/adr.md- always use{REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md - The setup script reads individual ADR files from the
adr/directory - When running from a subdirectory (e.g., a subproject directory),
.adlcmay be in the parent directory
- Analyze ADRs: Check each ADR against quality checklist
- Identify Gaps: List areas needing clarification
- Interactive Refinement: Ask targeted questions to fill gaps
- Update ADRs: Write refined ADRs back to file
Execution Steps
Phase 1: Context Loading
Objective: Establish current ADR state
-
Run Prerequisites Script:
- Execute
scripts/bash/setup-architect.shfrom repo root - Parse JSON for paths to memory files
- Handle errors gracefully if files don't exist
- Execute
-
Load ADR File:
- Read
{REPO_ROOT}/.adlc/drafts/adr/adr.mdfor the ADR list - Read individual ADRs from
{REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md - Count total ADRs and identify status distribution
- Read
-
Load Constitution:
- Read
{REPO_ROOT}/.adlc/memory/constitution.mdif it exists - Extract principles for alignment checking
- Note governance constraints
- Read
-
User Focus:
- If user specified specific ADRs or areas, narrow scope
- Otherwise, review all ADRs
Phase 2: ADR Analysis
Objective: Identify quality gaps in each ADR
Quality Dimensions to Check
-
Context Completeness:
- Is the problem clearly stated?
- Are the forces/drivers documented?
- Is the decision scope clear?
-
Decision Clarity:
- Is the decision actionable?
- Are implementation implications clear?
- Can this decision be validated/tested?
-
Consequence Coverage:
- Are positive outcomes documented?
- Are negative trade-offs acknowledged?
- Are risks identified with mitigations?
-
Alternatives Documentation:
- Are at least 2 alternatives listed?
- Is rejection reasoning clear for each?
- Were reasonable options considered?
-
Cross-ADR Consistency:
- Do decisions conflict with other ADRs?
- Are dependencies between ADRs documented?
- Is terminology consistent?
-
Constitution Alignment:
- Does decision comply with MUST principles?
- Are SHOULD principles addressed?
- Are violations explicitly justified?
Phase 2.5: Risks & Gaps Analysis (Cross-Cutting)
Objective: Identify operational gaps, technical debt, SPOFs, and security concerns NOT documented across all views
Analysis Dimensions:
| Dimension | Views to Check | What to Look For |
|---|---|---|
| Operational Gaps | Operational (3.7), Deployment (3.6) | Missing monitoring, undefined on-call, no runbooks, unclear rollback |
| Technical Debt | Development (3.5), Information (3.3) | Deprecated dependencies, no tests, legacy code, schema debt |
| Single Points of Failure | Deployment (3.6), Concurrency (3.4) | Single DB instance, no redundancy, critical path bottlenecks |
| Security Concerns | All views | Unencrypted data, no auth, exposed secrets, missing audit trails |
Gap Identification Process:
- Scan Each View: Check if view exists, identify missing cri