/architect-clarify

name: architect-clarify
description: Use when ADRs need review, gaps need filling, or ADR status must be approved as Accepted 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}/docs/adlc/memory/constitution.md` (legacy `{REPO_ROOT}/.adlc/memory/constitution.md` fallback — dual-read)

**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

2. **Analyze ADRs**: Check each ADR against quality checklist 3. **Identify Gaps**: List areas needing clarification 4. **Interactive Refinement**: Ask targeted questions to fill gaps 5. **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}/docs/adlc/memory/constitution.md` (legacy `{REPO_ROOT}/.adlc/memory/constitution.md` fallback) if either 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

Step 0: Detect Lightweight Draft Format

Check if the draft being reviewed uses the lightweight draft template (indicated by presence of `type`, `evidence`, `source`, `revisit-when` fields in frontmatter and `## Rejected Alternatives` / `## Reason` body sections without the full formal template sections).

If lightweight: 1. Read the draft's captured fields (Context, Decision, Rejected Alternatives, Reason) 2. Transform to full formal template:

• ADR: full MADR format with Decision Drivers, Considered Options, Pros/Cons, Constitution Alignment, Related ADRs
• PDR: full PDR format with Market Forces, Consequences, Alternatives Considered, Links
• ChDR: full ChDR format with Issue Links, Commits, Consequences, Evidence
• CDR: full CDR format with Context Type, Target Module, Descriptor, Evidence
• EVAL: full eval format with Error Analysis, Pass/Fail Examples, Implementation Notes

3. Enrich from session context (add details the lightweight draft may have omitted) 4. Present the enriched draft for review

If already full format, proceed with normal review.

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 dec