madr-gen

Category: Tools & Productivity | Uploader: JiHongKim98 | Downloads: 0 | Version: v1.0（Latest）
Analyze current session for architectural decisions and generate/update mADR documents
Changelog: Source: GitHub https://github.com/JiHongKim98/madr-gen
Directory Structure

Current level: skills/madr-gen/
📄 SKILL.md 8.6 KB
SKILL.md

---
description: Analyze current session for architectural decisions and generate/update mADR documents
triggers:
  - "madr"
  - "architecture decision"
  - "decision record"
  - "document decisions"
  - "adr"
allowed-tools: Bash(git *), Bash(ls *), Bash(find *), Bash(bash *), Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion
---

# mADR Generator Skill

Generate and update Markdown Architecture Decision Records (mADR) by analyzing the current Claude Code session.

## Overview

This skill implements a 3-phase pipeline:
1. **Phase 1 - Detection** (Parallel): Analyze session context to detect architectural decisions
2. **Phase 2 - Validation** (Sequential): Check proposals against existing ADRs
3. **Phase 3 - Execution** (Interactive): Present options and write selected ADRs

## Subcommand Routing

Parse the user's input to determine which subcommand was invoked:

- **`/madr`** (no args): Run the full interactive pipeline (Steps 0–6)
- **`/madr scan`**: Run Steps 0–3 only (detect + validate), then display results without writing files. Skip Steps 4–6.
- **`/madr init`**: Run Step 0 only (create directory, generate index, inject CLAUDE.md setup block), then stop.

If the argument doesn't match `scan` or `init`, treat it as the default interactive mode.

## Error Handling

Each step can fail. Handle failures gracefully instead of silently continuing:

| Failure Case | Action |
|-------------|--------|
| Session JSONL files not found | Warn user, continue with git-only analysis |
| Git not initialized | Warn user, continue with session-only analysis |
| `jq` not available | Script falls back to grep-based extraction automatically |
| decision-detector returns no decisions | Inform user "No architectural decisions detected in this session", stop |
| decision-detector returns invalid JSON | Strip markdown code fences (` ```json ... ``` `), retry parse. If still invalid, report error and stop |
| duplicate-checker returns invalid JSON | Same as above |
| `docs/decisions/` not writable | Report permission error, stop |

**JSON validation:** After each agent returns, strip any surrounding markdown code fences and validate the result is a parseable JSON array. If the result contains explanatory text outside the JSON, extract only the JSON array portion.

## Step-by-Step Workflow

### Step 0: Initialize

Ensure the `docs/decisions/` directory exists in the project root. If not, create it.

```
mkdir -p docs/decisions
```

Generate (or regenerate) the ADR index:
```bash
bash scripts/update-adr-index.sh "docs/decisions"
```

#### CLAUDE.md Setup (on `/madr init`)

When the user runs `/madr init`, also inject the madr-gen setup block into CLAUDE.md.
This ensures future sessions automatically read existing ADRs before making architectural suggestions.

```bash
bash scripts/setup-claude-md.sh "$(pwd)" "docs/decisions"
```

The script manages a marker block in CLAUDE.md:
```markdown
<!-- madr-gen:setup:start -->
## [IMPORTANT] Architecture Decisions
Read `docs/decisions/README.md` for the active ADR index before making architectural suggestions.
Before ending a session with significant architectural changes, run `/madr` to document decisions.
<!-- madr-gen:setup:end -->
```

Behavior:
- **No CLAUDE.md**: Creates it with the block
- **CLAUDE.md exists, no markers**: Appends the block
- **Markers already present**: Updates content between markers (idempotent)

The `adrDirectory` path is read from `.madr-gen.json` if present (default: `docs/decisions`).

### Step 1: Gather Session Context

Collect information from multiple sources in parallel:

#### 1a. Git Changes (run in parallel)
```bash
git diff --stat
git log --oneline -20
```

#### 1b. Existing ADR Index (run in parallel)
```bash
cat docs/decisions/README.md 2>/dev/null
```
Read the ADR index to understand what's already documented and the status of each decision.
Only read individual ADR files when deeper context is needed for a specific match.

#### 1c. Session JSONL Logs (run in parallel)
Claude Code stores session histories as JSONL at `~/.claude/projects/<encoded-cwd>/`.

Use `find-session-logs.sh` to locate session files (single source of truth for path encoding):

```bash
bash scripts/find-session-logs.sh "$(pwd)" 24
```

For each session file, extract conversation text using `extract-decisions.sh` (single source of truth for JSONL parsing):

```bash
bash scripts/extract-decisions.sh <session-file> 500
```

> **Important:** Always use the helper scripts instead of inline jq/grep. The scripts handle macOS compatibility, user array messages, jq fallback, and edge cases consistently.

**Processing strategy:**
- 1-3 JSONL files: Extract each directly
- 4+ files: Focus on the most recent file only

#### 1d. Config (run in parallel)
```bash
cat .madr-gen.json 2>/dev/null  # Check for project-level config overrides
```

### Step 2: Phase 1 - Decision Detection (Parallel)

Launch the `decision-detector` agent with all gathered context:

```
Agent(
  subagent_type="decision-detector",
  model="sonnet",
  prompt="Analyze the current session to detect architectural decisions.

  Session conversation (from JSONL):
  {extracted_conversation}

  Git changes summary: {git_diff_stat}
  Recent commits: {git_log}

  Existing ADR index (from README.md):
  {adr_index_table}

  Note: Only ADRs with status 'Accepted' or 'Proposed' are active.
  ADRs marked 'Superseded' or 'Deprecated' are no longer in effect.

  Return decisions as a JSON array following the output format in your instructions.
  Only include decisions with medium or high confidence."
)
```

The agent will return a JSON array of detected decisions with:
- Title, category, context, drivers
- Considered options and chosen option
- Rationale and consequences
- Confidence level

### Step 3: Phase 2 - Duplicate Validation (Sequential)

Launch the `duplicate-checker` agent with the detected decisions and the ADR index:

```
Agent(
  subagent_type="duplicate-checker",
  model="haiku",
  prompt="Check these proposed decisions against existing ADRs using the index.

  Proposed decisions: {decisions_json}
  ADR index (from docs/decisions/README.md): {adr_index_table}

  Classify each as new/update/supersede/duplicate."
)
```

### Step 4: Present Suggestions to User

After filtering out duplicates, present the remaining suggestions to the user using `AskUserQuestion`.

Format the suggestions as a numbered list with:
- Decision title
- Category badge
- Action type (NEW / UPDATE / SUPERSEDE)
- Brief context (1-2 sentences)
- Confidence indicator

Example presentation:

```
## Detected Architectural Decisions

Based on this session, I found the following decisions that could be documented:

1. **[NEW] Use Zustand for State Management** (Technology, High confidence)
   > Chose Zustand over Redux for client-side state due to simpler API and smaller bundle size.

2. **[UPDATE] API Authentication Strategy** (Architecture, Medium confidence)
   > Updated from JWT-only to JWT + refresh token rotation. Existing: 0003-api-auth-strategy.md

3. **[NEW] Adopt Vitest for Unit Testing** (Technology, High confidence)
   > Switched from Jest to Vitest for better ESM support and faster execution.
```

Use `AskUserQuestion` with multiSelect to let the user pick which ones to create/update.

### Step 5: Phase 3 - Write ADRs

For each selected decision, launch the `madr-writer` agent:

```
Agent(
  subagent_type="madr-writer",
  model="sonnet",
  prompt="Create/update the following ADR in docs/decisions/:

  Action: {new|update|supersede}
  Decision data: {decision_json}
  Existing file (if update/supersede): {file_path}
  Next sequence number (if new): {next_number}
  Today's date: {YYYY-MM-DD}

  Write the mADR file following the MADR 4.0 template."
)
```

For multiple selections, run writers in parallel since they write to different files.

### Step 6: Summary

After all writes complete, present a summary:
- List of created/updated files with paths
- Quick view of each ADR title and status

## Configuration

### ADR Directory
Default: `docs/decisions/`
Can be overridden by setting `adrDirectory` in the project's `.madr-gen.json` config file.

### Template Style
Default: Full template (all sections)
Alternative: Minimal template (context, options, outcome only)
Set via `templateStyle: "full" | "minimal"` in `.madr-gen.json`.

### Language
By default, ADRs are written in the language the user uses in the session.
Can be forced via `language: "en" | "ko" | ...` in `.madr-gen.json`.

## Example Config (.madr-gen.json)

```json
{
  "adrDirectory": "docs/decisions",
  "templateStyle": "full",
  "language": "auto",
  "autoSuggest": true,
  "categories": [
    "technology",
    "architecture",
    "convention",
    "infrastructure",
    "refactoring"
  ]
}
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
madr-gen

Directory Structure

SKILL.md

Report

Notice
