Initial commit
This commit is contained in:
Zhongwei Li
167
commands/adr-identify.md
Normal file
167
commands/adr-identify.md
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
description: Identify potential ADRs for specific modules based on the codebase mapping (Phase 2)
|
||||
tags: [project, adr]
|
||||
---
|
||||
|
||||
Launches the `adr-analyzer` agent to identify potential ADRs in specified modules.
|
||||
|
||||
When multiple modules are specified, launches agents in parallel for faster analysis.
|
||||
|
||||
**Prerequisites**: Run `/adr-map` first if mapping.md doesn't exist in the output directory.
|
||||
|
||||
**What it does**:
|
||||
- Analyzes specified module(s) with strict architectural filtering
|
||||
- Executes multiple modules in parallel when 2+ modules are specified
|
||||
- Uses git history internally to enrich potential ADRs with temporal context
|
||||
- Creates individual ADR files in priority-based folders (NO numbers in filenames)
|
||||
- Weaves git insights naturally into content (dates, keywords, evolution)
|
||||
- Updates the index with findings
|
||||
|
||||
**Usage**:
|
||||
```
|
||||
/adr-identify [module-ids] [--output-dir=PATH] [--adrs-dir=PATH]
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
/adr-identify
|
||||
# Prompts which modules to analyze (uses docs/adrs by default)
|
||||
|
||||
/adr-identify AUTH
|
||||
# Analyze only AUTH module
|
||||
|
||||
/adr-identify AUTH DATA API
|
||||
# Analyze multiple modules
|
||||
|
||||
/adr-identify --output-dir=output/adrs AUTH
|
||||
# Analyze AUTH module with custom output directory
|
||||
|
||||
/adr-identify --adrs-dir=docs/adrs/generated AUTH
|
||||
# Uses existing ADRs from custom directory for context and duplicate detection
|
||||
```
|
||||
|
||||
**Output Structure**:
|
||||
```
|
||||
{OUTPUT_DIR}/potential-adrs/ # Default: docs/adrs/potential-adrs
|
||||
├── must-document/ # High priority (score ≥100 out of 150)
|
||||
│ └── MODULE-ID/
|
||||
│ ├── decision-title-kebab-case.md
|
||||
│ └── another-architectural-decision.md
|
||||
└── consider/ # Medium priority (score 75-99 out of 150)
|
||||
└── MODULE-ID/
|
||||
└── medium-priority-decision.md
|
||||
```
|
||||
|
||||
**Important**: Filenames use descriptive kebab-case WITHOUT numbers. Numbering happens in Phase 3 when formal ADRs are generated.
|
||||
|
||||
**Existing ADR Integration**: Automatically scans {OUTPUT_DIR}/generated/ (or --adrs-dir path) for existing ADRs to:
|
||||
- Avoid duplicate identification (>70% similarity warning)
|
||||
- Detect relationships with existing decisions (40-70% similarity)
|
||||
- Provide timeline context (decision evolution, supersession patterns)
|
||||
- Suggest consolidation opportunities (implementation details of existing ADRs)
|
||||
|
||||
**How It Works**:
|
||||
- **Scoring**: 3 dimensions (Scope+Impact, Cost to Change, Team Knowledge), 150 points total (75 base score from Step 0 + 75 from dimensions)
|
||||
- **Thresholds**: ≥100 pts (67%, high priority), 75-99 pts (50-66%, medium priority), <75 pts (discard)
|
||||
- **Filtering**: Step 0 (Positive Identification) + Red Flags 1-5
|
||||
- **Git Integration**: Enriches content with temporal context (dates, evolution, intent keywords)
|
||||
|
||||
**Key Features**:
|
||||
- **Step 0 (Positive Identification)**: Base technology decisions (infrastructure services, framework, ORM, API, auth, payment, AI/ML) automatically trigger ADR creation with base score
|
||||
- **Red Flag 5**: Consolidates overly granular decisions into larger strategic ADRs (prevents ADR sprawl)
|
||||
- **Operational Impact**: Captures observability, resilience, and production reliability decisions
|
||||
|
||||
**Expected Results**:
|
||||
- Only ~5% of findings become ADRs (strict filtering)
|
||||
- Potential ADRs enriched with git history (dates, evolution, intent keywords)
|
||||
- No separate "Git History" section - insights woven naturally into content
|
||||
|
||||
**Note**: This identifies potential ADRs with evidence. You decide which to formally document in Phase 3.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Instructions
|
||||
|
||||
When the user invokes `/adr-identify` with module IDs:
|
||||
|
||||
### Parse Arguments
|
||||
Extract from command:
|
||||
- Module IDs (e.g., AUTH, DATA, API)
|
||||
- `--output-dir=<path>`: Optional output directory (default: `docs/adrs`)
|
||||
- `--adrs-dir=<path>`: Optional existing ADRs directory (default: `{OUTPUT_DIR}/generated/`)
|
||||
|
||||
### Single Module (e.g., `/adr-identify AUTH`)
|
||||
Launch a single `adr-analyzer` agent with the Task tool:
|
||||
|
||||
**Without --output-dir:**
|
||||
```
|
||||
Task tool:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the AUTH module"
|
||||
```
|
||||
|
||||
**With --output-dir:**
|
||||
```
|
||||
Task tool:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the AUTH module with --output-dir=custom/path"
|
||||
```
|
||||
|
||||
**With --adrs-dir:**
|
||||
```
|
||||
Task tool:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the AUTH module with --adrs-dir=docs/adrs/generated"
|
||||
```
|
||||
|
||||
### Multiple Modules (e.g., `/adr-identify AUTH DATA API` or `/adr-identify --output-dir=output/adrs AUTH DATA`)
|
||||
Launch multiple `adr-analyzer` agents **in parallel** using a single message with multiple Task tool calls:
|
||||
|
||||
**Without --output-dir:**
|
||||
```
|
||||
Single message with multiple Task tool calls:
|
||||
|
||||
Task tool call 1:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the AUTH module"
|
||||
|
||||
Task tool call 2:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the DATA module"
|
||||
|
||||
Task tool call 3:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the API module"
|
||||
```
|
||||
|
||||
**With --output-dir:**
|
||||
```
|
||||
Single message with multiple Task tool calls:
|
||||
|
||||
Task tool call 1:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the AUTH module with --output-dir=custom/path"
|
||||
|
||||
Task tool call 2:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the DATA module with --output-dir=custom/path"
|
||||
|
||||
Task tool call 3:
|
||||
- subagent_type: adr-analyzer
|
||||
- prompt: "Identify potential ADRs for the API module with --output-dir=custom/path"
|
||||
```
|
||||
|
||||
**IMPORTANT**:
|
||||
- When 2+ modules are specified, you MUST send a single message with multiple Task tool calls
|
||||
- Each agent should analyze only ONE specific module
|
||||
- Do NOT run agents sequentially - run them in parallel for better performance
|
||||
- Each agent will create its own potential ADR files in the appropriate priority folders
|
||||
- The index file will be updated by each agent independently
|
||||
- All agents must use the same --output-dir if specified
|
||||
|
||||
### No Modules Specified (e.g., `/adr-identify` or `/adr-identify --output-dir=custom/path`)
|
||||
1. Determine output directory (from --output-dir or default `docs/adrs`)
|
||||
2. Read `{OUTPUT_DIR}/mapping.md` to get available modules
|
||||
3. Present the module list to the user
|
||||
4. Ask which module(s) they want to analyze
|
||||
5. Once specified, follow the logic above (single or multiple)
|
||||
Reference in New Issue
Block a user