跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

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-init first to create ADRs
  • Brownfield projects: Use /architect-init to 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

  1. 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 .adlc directory
  • 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), .adlc may be in the parent directory
  1. Analyze ADRs: Check each ADR against quality checklist
  2. Identify Gaps: List areas needing clarification
  3. Interactive Refinement: Ask targeted questions to fill gaps
  4. Update ADRs: Write refined ADRs back to file

Execution Steps

Phase 1: Context Loading

Objective: Establish current ADR state

  1. Run Prerequisites Script:

    • Execute scripts/bash/setup-architect.sh from repo root
    • Parse JSON for paths to memory files
    • Handle errors gracefully if files don't exist
  2. Load ADR File:

    • Read {REPO_ROOT}/.adlc/drafts/adr/adr.md for the ADR list
    • Read individual ADRs from {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md
    • Count total ADRs and identify status distribution
  3. Load Constitution:

    • Read {REPO_ROOT}/.adlc/memory/constitution.md if it exists
    • Extract principles for alignment checking
    • Note governance constraints
  4. 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
  1. Context Completeness:

    • Is the problem clearly stated?
    • Are the forces/drivers documented?
    • Is the decision scope clear?
  2. Decision Clarity:

    • Is the decision actionable?
    • Are implementation implications clear?
    • Can this decision be validated/tested?
  3. Consequence Coverage:

    • Are positive outcomes documented?
    • Are negative trade-offs acknowledged?
    • Are risks identified with mitigations?
  4. Alternatives Documentation:

    • Are at least 2 alternatives listed?
    • Is rejection reasoning clear for each?
    • Were reasonable options considered?
  5. Cross-ADR Consistency:

    • Do decisions conflict with other ADRs?
    • Are dependencies between ADRs documented?
    • Is terminology consistent?
  6. 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:

DimensionViews to CheckWhat to Look For
Operational GapsOperational (3.7), Deployment (3.6)Missing monitoring, undefined on-call, no runbooks, unclear rollback
Technical DebtDevelopment (3.5), Information (3.3)Deprecated dependencies, no tests, legacy code, schema debt
Single Points of FailureDeployment (3.6), Concurrency (3.4)Single DB instance, no redundancy, critical path bottlenecks
Security ConcernsAll viewsUnencrypted data, no auth, exposed secrets, missing audit trails

Gap Identification Process:

  1. Scan Each View: Check if view exists, identify missing cri
阅读完整来源 ↗