mADR Generator Skill

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 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 scripts/setup-claude-md.sh "$(pwd)" "docs/decisions"

The script manages a marker block in CLAUDE.md:

<!-- 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)

git diff --stat
git log --oneline -20

1b. Existing ADR Index (run in parallel)

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

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)

{
  "adrDirectory": "docs/decisions",
  "templateStyle": "full",
  "language": "auto",
  "autoSuggest": true,
  "categories": [
    "technology",
    "architecture",
    "convention",
    "infrastructure",
    "refactoring"
  ]
}